Visões Arquiteturais

Versão: 1.0

Este documento complementa o diagrama de Contexto e Container (01-Contexto-Container.md) com visões arquiteturais adicionais no estilo "4+1".

Visão Lógica

Organização lógica do backend NestJS em Bounded Contexts (Auth, Cadernos, Itens, Calendário, Busca), cada um com suas 4 camadas (domain, application, infrastructure, interface) seguindo a Clean Architecture (ADR-001).

flowchart TB
    subgraph Modulos["Bounded Contexts — Backend NestJS"]
        subgraph Auth["Auth Module"]
            A1[interface] --> A2[application]
            A2 --> A3[domain]
            A1 --> A4[infrastructure]
            A4 --> A3
        end
        subgraph Cadernos["Cadernos Module"]
            C1[interface] --> C2[application]
            C2 --> C3[domain]
            C1 --> C4[infrastructure]
            C4 --> C3
        end
        subgraph Itens["Itens Module"]
            I1[interface] --> I2[application]
            I2 --> I3[domain]
            I1 --> I4[infrastructure]
            I4 --> I3
        end
        subgraph Calendario["Calendário Module"]
            Cal1[interface] --> Cal2[application]
            Cal2 --> Cal3[domain]
            Cal1 --> Cal4[infrastructure]
            Cal4 --> Cal3
        end
        subgraph Busca["Busca Module"]
            B1[interface] --> B2[application]
            B2 --> B3[domain]
            B1 --> B4[infrastructure]
            B4 --> B3
        end
    end

Visão de Processo

Fluxo de autenticação e comunicação protegida (ADR-006, ADR-008, ADR-028).

sequenceDiagram
    participant U as Usuário (Browser)
    participant F as Frontend (Next.js)
    participant A as API Backend (NestJS)
    participant DB as PostgreSQL

    U->>F: Submete e-mail + senha
    F->>A: POST /api/auth/login
    A->>DB: Busca usuário por e-mail
    DB-->>A: Registro do usuário
    A->>A: Verifica hash da senha (Argon2id)
    A->>DB: Cria sessão (hash do refresh token)
    A-->>F: 200 OK + cookies (Access Token + Refresh Token)
    F-->>U: Redireciona para dashboard

    Note over U,DB: Requisição protegida (Access Token válido)
    U->>F: Acessa /cadernos
    F->>A: GET /api/notebooks (cookie com Access Token)
    A->>A: AuthGuard valida JWT
    A->>DB: Busca cadernos do userId
    DB-->>A: Lista de cadernos
    A-->>F: 200 OK + dados
    F-->>U: Renderiza cadernos

    Note over U,DB: Renovação silenciosa (Access Token expirado)
    U->>F: Acessa /items
    F->>A: GET /api/items (Access Token expirado)
    A-->>F: 401 Unauthorized
    F->>A: POST /api/auth/refresh (cookie com Refresh Token)
    A->>DB: Valida hash do refresh token
    A-->>F: 200 OK + novo Access Token (cookie)
    F->>A: GET /api/items (novo Access Token)
    A-->>F: 200 OK + dados

Visão de Implementação

Estrutura de diretórios do monorepo (ADR-001, ADR-002).

flowchart TD
    Root["root/"] --> Apps["apps/"]
    Root --> Packages["packages/"]
    Apps --> API["api/ (NestJS)"]
    Apps --> Web["web/ (Next.js)"]
    Packages --> Shared["shared/ (tipos e DTOs)"]

    API --> Src["src/"]
    Src --> AuthMod["auth/"]
    Src --> NotebooksMod["notebooks/"]
    Src --> ItemsMod["items/"]
    Src --> CalendarMod["calendar/"]
    Src --> SearchMod["search/"]

    AuthMod --> AD["domain/"]
    AuthMod --> AA["application/"]
    AuthMod --> AI["infrastructure/"]
    AuthMod --> AInt["interface/"]

Visão de Implantação (Deploy)

Componentes de deploy do MVP.

C4Deployment
    title Diagrama de Implantação — MVP

    Deployment_Node(browser, "Navegador do Usuário", "Chrome/Firefox/Safari") {
        Container(spa, "Frontend Web", "Next.js", "Interface do usuário")
    }

    Deployment_Node(server, "Servidor de Aplicação", "Node.js Runtime") {
        Container(api_deploy, "API Backend", "NestJS", "Lógica de negócio")
    }

    Deployment_Node(db_server, "Servidor de Banco de Dados", "PostgreSQL 15+") {
        ContainerDb(pg, "PostgreSQL", "Banco relacional", "Dados persistidos")
    }

    Rel(spa, api_deploy, "HTTPS/JSON + cookies httpOnly")
    Rel(api_deploy, pg, "SQL/TCP via Prisma Client")

Rastreabilidade Backward

• G-000, G-014, ADR-001, ADR-002, ADR-006, ADR-008, ADR-028