Pular para o conteúdo principal

Visão Geral da Arquitetura

O APAH Assistant é construído com uma arquitetura moderna e escalável, seguindo os princípios do T3 Stack e as melhores práticas de desenvolvimento web.

Diagrama de Arquitetura​

┌─────────────────────────────────────────────────────────────────┐
│                         Cliente (Browser)                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Next.js App Router                     │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
│  │  │   Pages     │  │ Components  │  │   Hooks         │   │   │
│  │  │   (RSC)     │  │  (shadcn)   │  │   (React Query) │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Servidor (Next.js)                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                      API Layer                            │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
│  │  │   tRPC      │  │  REST API   │  │   Server        │   │   │
│  │  │   Routers   │  │  Routes     │  │   Actions       │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Business Logic                         │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐   │   │
│  │  │   Auth      │  │   AI/LLM    │  │   Document      │   │   │
│  │  │   Service   │  │   Service   │  │   Service       │   │   │
│  │  └─────────────┘  └─────────────┘  └─────────────────┘   │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Data Layer                             │   │
│  │  ┌─────────────────────────────────────────────────────┐ │   │
│  │  │              Drizzle ORM                             │ │   │
│  │  └─────────────────────────────────────────────────────┘ │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Serviços Externos                           │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────┐     │
│  │  PostgreSQL  │  │  Azure       │  │  Azure             │     │
│  │  Database    │  │  OpenAI      │  │  Communication     │     │
│  └──────────────┘  └──────────────┘  └────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘

Camadas da Aplicação​

1. Camada de Apresentação (Frontend)​

  • Next.js App Router com React Server Components
  • shadcn/ui para componentes de interface
  • Tailwind CSS para estilização
  • React Query para gestão de estado do servidor

2. Camada de API​

  • tRPC para APIs type-safe entre cliente e servidor
  • REST API Routes para integrações externas
  • Server Actions para mutações simples

3. Camada de Negócio​

  • Serviço de Autenticação (Better Auth)
  • Serviço de IA (Vercel AI SDK + LangChain)
  • Serviço de Documentos (Gestão de PDFs e embeddings)

4. Camada de Dados​

  • Drizzle ORM para acesso à base de dados
  • PostgreSQL como base de dados principal
  • Migrações versionadas e auditáveis

Padrões Arquiteturais​

Server Components First​

O APAH Assistant privilegia o uso de React Server Components (RSC), renderizando o máximo possível no servidor para melhor performance e SEO.

// Exemplo de Server Component
async function ChatPage() {
  const session = await getSession();
  const history = await getChatHistory(session.userId);

  return <ChatInterface initialHistory={history} />;
}

Type Safety End-to-End​

Com tRPC e TypeScript, temos tipagem completa desde a base de dados até ao frontend:

// Schema Drizzle → tRPC Router → React Component
// Tudo type-safe!

Colocation​

Ficheiros relacionados são agrupados por funcionalidade, não por tipo:

src/app/[lang]/(app)/users/
├── page.tsx           # Página
├── _components/       # Componentes específicos
├── actions.ts         # Server Actions
└── types.ts           # Tipos

Fluxo de Dados​

Leitura de Dados​

  1. Componente faz request via tRPC ou Server Component
  2. Router tRPC valida input com Zod
  3. Query Drizzle executa na base de dados
  4. Dados são transformados e retornados
  5. React Query faz cache no cliente

Escrita de Dados​

  1. Formulário submete dados
  2. Server Action ou tRPC mutation recebe
  3. Validação com Zod
  4. Operação Drizzle na base de dados
  5. Revalidação de cache

Segurança​

  • Autenticação via Better Auth com sessões seguras
  • Autorização baseada em roles (RBAC)
  • Validação de todos os inputs com Zod
  • CSRF Protection automática
  • Rate Limiting em endpoints sensíveis

Próximos Tópicos​