# Arquitetura Técnica de Referência

## Decisões principais

- TypeScript será a linguagem principal.
- Angular será utilizado no front-end.
- NestJS será utilizado na API.
- MySQL será a fonte relacional oficial.
- Prisma será utilizado para migrations e acesso aos dados.
- A aplicação começará como monólito modular.
- Processamentos demorados serão executados por workers.
- Provedores de IA serão acessados por uma camada de abstração.
- O mecanismo de recuperação semântica poderá ser substituído sem alterar o domínio.
- Segurança, auditoria e custos serão tratados desde as primeiras integrações de IA.

## Visão do sistema

```mermaid
flowchart TB
    U[Usuário] --> WEB[Aplicação Angular]
    WEB --> API[API NestJS]

    API --> AUTH[Autenticação e autorização]
    API --> MYSQL[(MySQL)]
    API --> STORAGE[Armazenamento de arquivos]
    API --> AIGW[AI Gateway]
    API --> QUEUE[Fila]

    QUEUE --> WORKER[Worker Node.js]
    WORKER --> MYSQL
    WORKER --> AIGW

    AIGW --> MODEL[Provedor de modelos]
    AIGW --> RAG[Serviço de conhecimento]
    RAG --> MYSQL
    RAG --> RETRIEVER[Adaptador de recuperação]

    AGENT[Agente] --> MCP[Servidor MCP]
    MCP --> API

    API --> OBS[Logs, métricas e auditoria]
    WORKER --> OBS
    MCP --> OBS
```

## Monólito modular

O primeiro back-end será uma única aplicação implantável, organizada por módulos de negócio:

```text
src/
|-- auth/
|-- users/
|-- organizations/
|-- projects/
|-- conversations/
|-- documents/
|-- knowledge/
|-- ai-gateway/
|-- agents/
|-- tools/
|-- mcp/
|-- approvals/
|-- evaluations/
|-- usage/
`-- audit/
```

Essa decisão reduz a complexidade operacional durante o aprendizado. Workers e servidores MCP poderão ser separados quando houver uma razão técnica clara.

## Responsabilidades do MySQL

O MySQL armazenará:

- usuários, organizações e permissões;
- projetos;
- conversas e mensagens;
- documentos e metadados;
- referências aos arquivos;
- execuções de IA;
- execuções de ferramentas;
- estado dos agentes;
- solicitações de aprovação;
- retornos e avaliações;
- consumo e custos;
- registros de auditoria.

Estrutura inicial de entidades:

```text
users
organizations
organization_members
projects
conversations
messages
documents
document_chunks
ai_executions
tool_executions
agent_runs
approval_requests
evaluations
usage_costs
audit_logs
```

Arquivos binários não serão gravados diretamente no banco. O MySQL guardará metadados, propriedade, estado de processamento e localização do arquivo.

## Camada de IA

O domínio da aplicação não deve chamar diretamente o SDK de um provedor. Será utilizada uma porta:

```ts
export interface LanguageModel {
  generate(input: GenerationInput): Promise<GenerationResult>;
  stream(input: GenerationInput): AsyncIterable<GenerationEvent>;
}
```

Cada integração será um adaptador:

```text
LanguageModel
|-- ProviderAAdapter
|-- ProviderBAdapter
`-- LocalModelAdapter
```

Isso permite trocar modelos, criar fallback, medir custos e testar a aplicação sem realizar chamadas externas.

## Camada de recuperação para RAG

O mecanismo de busca será acessado por uma interface:

```ts
export interface KnowledgeRetriever {
  index(document: KnowledgeDocument): Promise<void>;
  search(query: string, limit: number): Promise<SearchResult[]>;
  remove(documentId: string): Promise<void>;
}
```

Progressão didática:

1. busca textual com MySQL;
2. compreensão manual da similaridade entre embeddings;
3. implementação de um adaptador para busca vetorial;
4. busca híbrida e reranking;
5. avaliação da recuperação.

## Segurança

Regras obrigatórias:

- nenhuma credencial de provedor no front-end;
- toda entrada externa deve ser validada;
- consultas devem respeitar organização e proprietário;
- ferramentas devem possuir schemas restritos;
- ações críticas exigem aprovação;
- operações repetíveis devem utilizar idempotência;
- prompts e documentos não são considerados confiáveis;
- custos e limites devem ser registrados;
- dados sensíveis não devem aparecer nos registros;
- toda ação executada por agentes deve ser auditável.

## Evolução do produto

| Marco | Capacidade |
|---|---|
| 1 | Página responsiva |
| 2 | Aplicação Angular |
| 3 | API NestJS |
| 4 | MySQL e autenticação |
| 5 | Chat com IA e streaming |
| 6 | Upload e processamento de documentos |
| 7 | RAG com fontes |
| 8 | Tools e servidor MCP |
| 9 | Agente com aprovação humana |
| 10 | Avaliações, observabilidade e custos |
| 11 | CI/CD e implantação |
| 12 | Micro-SaaS final |