GLC_RFM-0010
sistema

Arquitetura do sistema

Como os blocos se conectam (C4), modelo de dominio v1, fluxos principais, stack por camada (cada escolha casa com uma regra do _RFM-0000) e rastreabilidade decisao → regra.

arquitetura

Diagrama C4

Contexto (quem conversa com quem) e containers (o que roda na VPS na v1). Ascii porque e o que esta no docs/arquitetura.md.

Nivel 1 — Contexto
 +-----------------+      +------------------+      +----------------+
 |  Cliente final  |      |  Lider projeto   |      |  Orgaos        |
 |  (empresa com   |<---->|  (operador GLC)  |<---->|  publicos      |
 |   licencas)     |      |                  |      |  (Fed/Est/Mun) |
 +--------+--------+      +---------+--------+      +--------+-------+
          | WhatsApp/email          | Painel web             | Portais/forms
          |                         |                        |
          v                         v                        v
 +--------------------------------------------------------------+
 |                   Sistema GLC (v1 = so Bloco A)              |
 |                                                              |
 |  +-----------+   +-----------+   +-----------+  +---------+  |
 |  | Bloco A   |   | Bloco B   |   | Bloco C   |  | Bloco D |  |
 |  | MAPEAR    |-->| WORKPLAN  |-->| PRODUCAO  |  | PROMO   |  |
 |  | (v1)      |   | (v2)      |   | (v3)      |  | (v4)    |  |
 |  +-----+-----+   +-----+-----+   +-----+-----+  +----+----+  |
 |        |               |               |             |        |
 |        +---------------+---------------+-------------+        |
 |                        |                                      |
 |                        v                                      |
 |          +------------------------------+                     |
 |          | Dominio compartilhado        |                     |
 |          |  - Empresa (CNPJ, socios)    |                     |
 |          |  - Licenca (tipo, numero,    |                     |
 |          |    orgao, emissao, venc)     |                     |
 |          |  - Catalogo licencas         |                     |
 |          |    (por vertical/municipio)  |                     |
 |          +------------------------------+                     |
 +--------------------------------------------------------------+
Nivel 2 — Containers (v1)
 +--------------------------------------------------------------+
 |                         VPS Rafael                           |
 |                                                              |
 |   +-------------+   +----------+   +------------------+     |
 |   |  Traefik    |-->|  glc-web |-->|    glc-api       |     |
 |   |  (443)      |   | Next.js  |   |   FastAPI        |     |
 |   |  Regra 9    |   | Regra 15 |   |   Regra 12       |     |
 |   +-------------+   +----------+   +--------+---------+     |
 |                                             |                |
 |                                             v                |
 |                                    +-----------------+       |
 |                                    |   PocketBase    |       |
 |                                    |   (glc-db)      |       |
 |                                    |   Regra 11      |       |
 |                                    +--------+--------+       |
 |                                             |                |
 |                                             v                |
 |                                    +-----------------+       |
 |                                    |    data/        |       |
 |                                    |    (volume)     |       |
 |                                    +-----------------+       |
 |                                                              |
 |   Rede: coolify (externa, compartilhada com Traefik)         |
 +--------------------------------------------------------------+

   Fora: Claude API (classificacao), SMTP (alertas)
dominio

Modelo de entidades (v1 draft)

So o que a v1 precisa. Entidades de Workplan/Producao entram em v2/v3.

Empresa
  • id
  • cnpj
  • razao_social
  • socios[] (nome, cpf, participacao)
  • endereco (municipio, uf, cep)
  • cnae_principal
  • cnaes_secundarios[]
  • estrutura_fisica (texto livre por enquanto)
  • cliente_de (ref tenant)
CatalogoLicenca
  • id
  • nome
  • orgao (nome + esfera: federal/estadual/municipal)
  • vertical (ex: alimentacao, industria)
  • municipio (null se nao for municipal)
  • frequencia_renovacao_meses
  • checklist_docs[] (lista de documentos exigidos)
  • criterios_aplicabilidade (regras simples: cnae, estrutura, produto)
LicencaDaEmpresa
  • id
  • empresa_id
  • catalogo_licenca_id
  • status (ativa, vencida, em_renovacao, dispensada, faltando)
  • numero
  • data_emissao
  • data_vencimento
  • proxima_renovacao (calculada)
  • obs
Tenant
  • id
  • nome (nome da operacao GLC, ou da empresa contratante)
  • licenses_ativas_count (usado para billing)
fluxos v1

Como as coisas acontecem

3 fluxos vivem na v1. Workplan, coleta e submissao entram em v2+.

Fluxo 1
Cadastrar empresa e mapear licencas
  1. 1Lider cadastra empresa (CNPJ, socios, endereco, CNAE, estrutura)
  2. 2Sistema lista catalogo aplicavel (filtro por vertical + municipio + CNAE)
  3. 3Lider marca quais licencas a empresa **ja tem**, **nao tem**, **nao se aplica** (validacao humana — item 2 do MAPEAMENTO do email)
  4. 4Para as que tem, lider cadastra numero + datas
  5. 5Sistema calcula proxima renovacao por frequencia do catalogo
  6. 6Dashboard mostra semaforo
Fluxo 2
Alertas
  1. 1Cron diario no FastAPI consulta licencas com vencimento em D-60/D-30/D-15
  2. 2Dispara email para lider (e opcionalmente cliente)
  3. 3Registra log de alerta enviado (para relatorio)
Fluxo 3
Visualizacao por cliente
  1. 1Cliente loga (PocketBase Auth)
  2. 2Ve so suas empresas e licencas
  3. 3Painel read-only (v1). Edicao e 100% da lider.
stack

Tecnologia por camada

Cada escolha casa com uma regra do _RFM-0000. Nada aqui foi inventado pelo projeto.

CamadaTecnologiaRegraNota
RuntimeBunR11Mais rapido que Node para dev
BackendFastAPI (Python)R12Logica de classificacao e workflow
BancoPocketBaseR11CRUD + Auth v1. Postgres se doer.
FrontendNext.js + Tailwind + shadcn/uiR15, R16Painel + semaforo
LLMClaude APIR14Classificacao CNAE, extracao de docs
OrquestradorLangGraphR13Fluxo de renovacao v2+
DeployDocker + Coolify + TraefikR7, R8, R9VPS Rafael
WhatsAppEvolution + ChatwootR17Coleta de docs v2+
rastreabilidade

Bloco → Regra

Cada decisao arquitetural materializa uma ou mais regras do metodo. Se algo aqui nao tiver regra, ou a regra falta ou a decisao esta solta.

DecisaoRegrasPor que
4 frentes como blocos independentes1 (principios)Blocos, nao monolitos
`docs/` primeiro, codigo depois2Estrutura padronizada
Git init do projeto2, 31 repo por projeto
`.env` fora do git3Seguranca
Docker Compose + rede `coolify`7, 8, 9Container isolado + Traefik
Traefik com labels + SSL9Proxy com SSL automatico
Cloudflare DNS10DNS + CDN + SSL na borda
PocketBase como banco11MVP, CRUD + Auth + API
FastAPI para logica de dominio12Backend padrao
Claude API para classificacao14Melhor qualidade
Next.js + Tailwind + shadcn15, 16Painel dinamico com UI pronta
Email como canal de alerta v117Integracao simples, sem HSM
WhatsApp via Evolution (v2)17Canal variavel, entra quando precisar
LangGraph p/ fluxo renovacao (v2)13Cerebro + corpo para workflow
Validacao smoke: `curl /health`1 (principio 3)Validar antes de empilhar
`test:unit` vs `test:integration`15 (split de testes)CI rapido, integracao so quando up
fetch SSR com AbortController 5s12 (resiliencia HTTP)Backend travado nao pode travar SSR
em aberto

O que ainda nao foi decidido

Assuntos arquiteturais esperando ADR proprio.