> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão arquitetural

> Componentes, fontes da verdade e infraestrutura planejada da Orquena.

# Visão arquitetural

A primeira implementação da Orquena seguirá um **monólito modular orientado a eventos**, acompanhado por processos separados quando carga, escala ou isolamento justificarem.

```text theme={null}
Experience Plane
├── Web App
├── Platform Admin
└── Mintlify Documentation

Application Plane
├── API
├── Realtime Gateway
├── Workers
└── AI Runtime

Platform Kernel
├── Identity and tenancy
├── Permissions
├── Plugin registry
├── Events and jobs
├── Audit
├── Files
└── Billing and entitlements

First-party domains
├── Contacts
├── Service Catalog
├── Professionals
├── Scheduling
├── Inbox
├── CRM
├── Knowledge Base
├── Notifications
└── Automations

Providers and connectors
├── WAHA and future Meta Cloud API
├── Google and Microsoft Calendar
├── S3-compatible storage
├── Model providers
├── Twenty, EspoCRM and Chatwoot connectors
└── Optional Activepieces connector

Infrastructure
├── PostgreSQL
├── Valkey
├── Managed S3 or SeaweedFS candidate
├── WAHA
└── Observability
```

## Platform Kernel

O kernel oferece identidade, tenancy, permissions, plugins, eventos, jobs, arquivos, billing e auditoria. Ele não conhece corte de cabelo, appointment, lead ou conversa.

## Domínios first-party

Contacts, Inbox, Scheduling e CRM possuem fontes da verdade próprias e coordenadas.

| Dado                            | Fonte oficial   |
| ------------------------------- | --------------- |
| Identidade do cliente           | Contacts        |
| Conversa e mensagem             | Inbox           |
| Serviço e preço vigente         | Service Catalog |
| Profissional                    | Professionals   |
| Disponibilidade e appointment   | Scheduling      |
| Pipeline e oportunidade         | CRM             |
| Política e histórico de entrega | Notifications   |

Aplicações externas nunca redefinem esses owners silenciosamente.

## Integrações externas

Projetos open source maduros entram por connectors e deployments separados.

```text theme={null}
Orquena contract
    ↓
Connector
    ↓
External API and webhooks
    ↓
Independent application and database
```

Consulte [Estratégia open source](/architecture/open-source-strategy).

## Processamento assíncrono

Operações demoradas são executadas por workers através de contratos de jobs.

O adapter inicial será BullMQ sobre Valkey. Eventos originados por transações serão persistidos por transactional outbox no PostgreSQL antes da publicação.

```text theme={null}
Database transaction
├── Domain change
└── Outbox record

Outbox publisher
    ↓
EventBus or JobBus
    ↓
Idempotent consumer
```

## AI Runtime

O runtime Mastra permanece separado do banco. Agents utilizam ferramentas tipadas que chamam APIs internas autorizadas da Orquena.

Modelos, providers, prompts, tools e policies são controlados pela plataforma.

## Mensageria

WAHA será o primeiro provider não oficial para desenvolvimento e pilotos controlados. Payloads específicos ficam dentro do adapter. Meta Cloud API será adicionada no futuro através do mesmo contrato.

Cada conexão de canal pertence a uma organização tenant. O tenant é resolvido pelo mapeamento interno da conexão, não por um campo livre do webhook.

## Storage

Arquivos utilizam contrato S3-compatible. Managed storage é válido para produção; SeaweedFS será avaliado para self-hosting. MinIO não será o default de novas instalações.

## Tempo real

A interface utiliza cache local, optimistic updates e eventos realtime. O evento atualiza a experiência, mas o estado persistido permanece authoritative.

## Segurança multi-tenant

```text theme={null}
Request, event or job
    ↓
Authenticated or trusted origin
    ↓
Membership, connection mapping and permission
    ↓
Trusted organization context
    ↓
Repository ownership filter and RLS
```

## Identidade da plataforma

Orquena é o nome canônico do produto, dos futuros deployments e do repositório `Fulixts/Orquena`. O caminho anterior pertence apenas ao histórico da migração e não deve aparecer em novas configurações.

## Evolução

A topologia começa em Docker Compose numa VPS. Serviços permanecem stateless quando possível, e contratos permitem separar workers, AI Runtime, realtime, providers e storage conforme testes e uso real justificarem.