Pular para conteúdo

Arquitetura de Software — Contexto e Visão de Blocos

Versão: 1.0

Este documento cobre as seções 2 (Contexto) e 4 (Visão de Blocos) do arc42 reduzido, conforme referenciado em 00-Visao-Geral-DAS.md. As seções 1 e 3 (Metas/Restrições e Decisões Arquiteturais) estão em 00-Visao-Geral-DAS.md; a seção 5 (Riscos/Dívida Técnica) está em 04-Riscos-Dívida-Tecnica.md.

2. Contexto (C4 Nível 1)

2.1. Visão Geral

O sistema Cadernos possui um único ator humano — o Usuário — que interage diretamente com a plataforma para gerenciar tanto produtividade pessoal (tarefas) quanto agenda (compromissos), sempre autenticando-se previamente (G-014.7).

Diferentemente da maioria dos sistemas web modernos, não há sistemas externos no contexto desta versão (MVP - Versão 1). Essa ausência é uma decisão de escopo deliberada — estando diretamente amarrada às restrições registradas no modelo KAOS e nos ASRs:

Sistema externo tipicamente esperado Por que está fora do contexto na V1 Rastreabilidade
Provedor de identidade Autenticação 100% interna, sem login social G-014, RNF-003, ASR-008
Serviço de e-mail (verificação, “esqueci minha senha”) Sem double opt-in e sem fluxo de recuperação de senha nesta versão OBS-004, RNF-003, RISCO-001
Provedor de 2FA / SMS Sem autenticação multifator nesta versão OBS-004, RNF-003

Essas ausências estão listadas como riscos aceitos em 04-Riscos-Dívida-Tecnica.md (RISCO-001, RISCO-002) e como metas candidatas a V2.

2.2. Diagrama de Contexto

C4Context
    title Diagrama de Contexto - Cadernos

    Person(usuario, "Usuário", "Pessoa que gerencia sua produtividade pessoal (tarefas) e sua agenda (compromissos) através da plataforma, sempre a partir de uma sessão autenticada.")

    System(cadernos, "Cadernos", "Plataforma pessoal que unifica tarefas e compromissos em um único modelo de dados hierárquico (Cadernos), com Sistema de Autenticação 100% interno.")

    Rel(usuario, cadernos, "Cadastra-se, autentica-se, cria Cadernos, captura itens na Inbox, gerencia TODOs e SCHEDULEs, consulta Calendário/Planner/Busca e administra a própria conta", "HTTPS")

2.3. Rastreabilidade

  • < Backward: G-000, G-014 (metas raiz co-dependentes — ver 00-Visao-Geral-DAS.md, seção 1.1), RNF-003, OBS-004
  • > Forward: Seção 4 deste documento (Container); ADR-002 (Monorepo)

4. Visão de Blocos (C4 Nível 2)

4.1. Visão Geral

O sistema é dividido em três containers, refletindo diretamente as decisões já registradas em 03-Decisoes-ADR.md: um monorepo (ADR-002) com frontend Next.js e backend NestJS estruturado em Clean Architecture/DDD (ADR-001), persistindo dados via Prisma em PostgreSQL (ADR-003).

4.2. Diagrama de Container

C4Container
    title Diagrama de Container - Cadernos

    Person(usuario, "Usuário", "Pessoa que gerencia tarefas e agenda pessoal.")

    Container_Boundary(cadernos, "Cadernos") {
        Container(web, "Frontend Web", "Next.js (React)", "Interface responsiva com as telas de Cadastro, Login, Configurações, Inbox, Cadernos, Todo List, Calendário (Diário/Semanal/Mensal/Agenda), Planner Diário e Busca.")
        Container(api, "API Backend", "NestJS", "Expõe API REST/JSON e concentra toda a lógica de negócio (autenticação, sessão, itens, recorrência, calendário, busca) organizada em módulos domain/application/infrastructure/interface.")
        ContainerDb(db, "Banco de Dados", "PostgreSQL", "Armazena usuários e seus estados de conta, sessões (hash de refresh tokens), cadernos, itens (SCHEDULE/TODO) e sub-itens.")
    }

    Rel(usuario, web, "Acessa pelo navegador e interage com a interface", "HTTPS")
    Rel(web, api, "Consome endpoints REST (ex.: /api/auth/login, /api/items, /api/calendar/daily, /api/search)", "HTTPS/JSON, cookies httpOnly/Secure/SameSite")
    Rel(api, db, "Lê e persiste dados através dos repositórios Prisma (Ports & Adapters)", "SQL/TCP (Prisma Client)")

4.3. Notas de Implementação por Container

Frontend Web (Next.js)

  • Armazena a sessão via cookies httpOnly, Secure, SameSite recebidos da API — nunca em localStorage (RF-021, ADR-006).
  • Validação client-side com React Hook Form + Zod, tratada como camada de UX; o backend permanece a autoridade final da regra (ADR-018).
  • Componentes de apresentação (calendário, cards de item, formulários) desenvolvidos isoladamente no Storybook, sem chamada direta à API (ADR-019).
  • Trata o terceiro estado de resposta do login (requires_reactivation), além de sucesso/falha (ADR-011).

API Backend (NestJS)

  • Organizado por Bounded Context (Auth, Cadernos, Itens, Calendário, Busca), em camadas domain/application/infrastructure/interface (ADR-001).
  • AuthGuard global via APP_GUARD; endpoints públicos exigem decorator explícito @Public() (ADR-008, RNF-002).
  • Autenticação híbrida: Passport JWT para Access Token + serviço custom para Refresh Token (ADR-006).
  • Recorrência calculada sob demanda com rrule, sem tabela de instâncias materializadas (ADR-013).
  • Regras de visibilidade Calendário/Planner centralizadas em CalendarVisibilityService (ADR-015); filtro de Snooze centralizado em findVisibleItems (ADR-014).
  • Busca textual via ILIKE (ADR-016).

Banco de Dados (PostgreSQL)

  • Acessado exclusivamente pela camada infrastructure da API — nenhuma camada domain/application importa @prisma/client diretamente (ADR-003).
  • Modelagem de Item via Single Table Inheritance (items.type = SCHEDULE/TODO) (ADR-004).
  • Índice GIN trigram (pg_trgm) para acelerar a busca por título (ADR-016; dívida técnica DIVIDA-001 enquanto o índice não é criado).
  • Tabela sessions armazena apenas o hash do refresh token, associada a user_id e device/user-agent (ASR-003).

4.4. Rastreabilidade

  • < Backward: G-000, G-014, ASR-003, ASR-004, ASR-009, ASR-010; ADR-001, ADR-002, ADR-003, ADR-004, ADR-006, ADR-008
  • > Forward: TASK-001 a TASK-070 (implementação por container); 03-Riscos-Dívida-Tecnica.md (RISCO-003 a RISCO-006, relativos à infraestrutura destes containers)