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

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:

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:

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:

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

Cada integração será um adaptador:

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:

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