You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Hub central de documentação. Cada seção aponta para a fonte canônica — nunca duplicamos, sempre referenciamos.
AI-powered SaaS B2B que transforma conversas comerciais confusas em escopos claros, aprovados e prontos para execução — guiando prestadores de serviço (freelancers, microagências) por um processo estruturado de discovery com IA.
Branch ativa:develop | Atualizado: 2026-04-13 | Status: User Service em staging ✅
Pequenos prestadores de serviço B2B perdem contratos por escopo mal definido. Reuniões de discovery são longas, subjetivas e resultam em propostas imprecisas — gerando retrabalho, conflitos e margens erodidas.
A Solução
ScopeFlow AI guia o cliente por um briefing estruturado via IA, detecta lacunas automaticamente, consolida respostas e gera propostas com escopo claro para aprovação digital.
Capacidades Principais
Capacidade
Descrição
AI-Assisted Discovery
Perguntas dinâmicas, gap detection, follow-ups automáticos
Nota:Client não é um bounded context separado. É referenciado como ClientId (value object) no domínio Briefing e como client_id UUID em Proposal — candidato a contexto futuro.
Relações entre Serviços
graph LR
mono["Monólito"]
us["User Service"]
mq["RabbitMQ"]
pgm["PostgreSQL\nscopeflow"]
pgu["PostgreSQL\nscopeflow_users"]
mono -->|"REST (CB+Retry)\nfindByEmail, createInvited"| us
mono -->|"Outbox → publish"| mq
mono --> pgm
us --> pgu
type(scope): descrição breve em PT-BR (máx 70 chars, imperativo)
Corpo opcional explicando o porquê (72 chars/linha).
Closes #issue
Tipo
Uso
feat
Nova feature
fix
Correção de bug
docs
Documentação
refactor
Refatoração sem mudança de comportamento
test
Adição ou correção de testes
chore
Manutenção, dependências, configurações
ci
CI/CD pipelines
perf
Melhoria de performance
Branching
Branch
Propósito
Proteções
main
Produção — sempre deployável
PR obrigatório, CI deve passar
develop
Staging — integração de features
Branch ativa atual
feature/{nome}
Nova feature
—
bugfix/{nome}
Correção de bug
—
hotfix/{nome}
Correção urgente em produção
—
7. Padrão de Documentação
Quando criar cada tipo
Tipo
Quando usar
Onde salvar
ADR (Architecture Decision Record)
Decisão técnica relevante, irreversível ou com trade-offs significativos
docs/architecture/adr/ ou docs/migration/adr/
RFC (Request for Comments)
Proposta que precisa de revisão antes de decidir
docs/architecture/rfc/ (criar quando necessário)
Extraction Card
Plano detalhado de extração de um bounded context
docs/migration/extraction-cards/
Guia técnico
How-to, procedimentos operacionais
docs/{categoria}/
Plano de sessão
Planejamento de execução (aprovado pelo time)
.claude/plans/
Template ADR
# ADR-{NNN}: {Título}**Data:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{NNN}
**Decisores:**[nomes ou times]## Contexto[Descreva o problema ou situação que gerou a necessidade desta decisão]## Decisão[A decisão tomada, de forma clara e afirmativa]## Consequências### Positivas-[benefício 1]### Negativas / Trade-offs-[custo ou risco 1]## Alternativas Consideradas| Alternativa | Razão para não escolher ||-------------|------------------------|| Opção A |[motivo]|
Template RFC
# RFC-{NNN}: {Título}**Data:** YYYY-MM-DD
**Autor:**[nome]**Status:** Draft | In Review | Accepted | Rejected
**Prazo para comentários:** YYYY-MM-DD
## Sumário[Uma frase descrevendo a proposta]## Motivação[Por que precisamos disso?]## Proposta Detalhada[Como implementar — código, diagramas, exemplos]## Impacto e Riscos[O que pode dar errado? Quanto esforço?]## Alternativas[O que mais foi considerado e por quê foi descartado]
Template Guia Técnico
# {Título}**Última atualização:** YYYY-MM-DD
**Contexto:**[serviço ou domínio relacionado]## Objetivo[Uma frase — o que este guia ensina a fazer]## Pré-requisitos-[ ] item 1
## Passo a Passo### 1. {Step}[instrução + código/comando]## Verificação[Como confirmar que funcionou]## Troubleshooting| Problema | Causa | Solução ||---------|-------|---------|
Regras de Documentação
Nunca duplicar — se já existe em outro .md, referencie com link relativo
Datas absolutas — sempre YYYY-MM-DD, nunca "ontem" ou "semana passada"
Status explícito — todo ADR/RFC/Card tem status visível no topo
Arquivos históricos → docs/sessions/archive/ (não deletar — são rastreabilidade)
Máximo de 1 nível de aninhamento em listas (legibilidade em mobile e PDF)
8. Fluxos Principais
Fluxo 1 — Briefing Discovery (Happy Path)
sequenceDiagram
participant C as Cliente (Browser)
participant T as Traefik
participant M as Monólito
participant AI as OpenAI
C->>T: GET /public/briefings/{token}
T->>M: encaminha (prioridade 50)
M-->>C: BriefingSession + próxima pergunta
loop Para cada pergunta
C->>T: POST /public/briefings/{token}/answers
T->>M: encaminha
M->>AI: genera follow-up (se resposta vaga)
AI-->>M: follow-up gerado
M-->>C: próxima pergunta (ou completion)
end
C->>T: POST /public/briefings/{token}/complete
T->>M: encaminha
M-->>C: BriefingCompleted (score ≥ 80%)
Loading
Fluxo 2 — Auth via User Service (Strangler Fig)
sequenceDiagram
participant B as Browser
participant T as Traefik
participant US as User Service
participant M as Monólito
participant PG as PostgreSQL
B->>T: POST /api/v1/auth/login
T->>US: prioridade 100 → user-service:8081
US->>PG: SELECT users (scopeflow_users)
PG-->>US: user encontrado
US-->>B: { accessToken, refreshToken }
B->>T: GET /api/v1/proposals (Bearer token)
T->>M: prioridade 50 → monolith:8080
M->>M: valida JWT (shared secret)
M-->>B: proposals[]
Loading
Fluxo 3 — Evento de Domínio via Outbox
sequenceDiagram
participant App as Application Layer
participant DB as PostgreSQL
participant OB as OutboxPublisher
participant MQ as RabbitMQ
App->>DB: BEGIN TRANSACTION
App->>DB: INSERT business_data
App->>DB: INSERT outbox_events (status=PENDING)
App->>DB: COMMIT
loop A cada 5s
OB->>DB: SELECT outbox_events WHERE published_at IS NULL
OB->>MQ: publish event
OB->>DB: UPDATE published_at = NOW()
end
Note over DB,OB: PurgeJobService limpa\neventos publicados > 7 dias\nàs 02:00 UTC
Loading
9. Onboarding Rápido
Pré-requisitos
Ferramenta
Versão mínima
Verificar
Java (Temurin)
21
java -version
Maven
3.8+
./mvnw -v
Node.js
20 LTS
node -v
Docker Desktop
4.x
docker -v
Docker Compose
v2
docker compose version
Setup em 5 Minutos
# 1. Clone e configure variáveis
git clone <repo>&&cd projeto-service-b2b
cp .env.example .env
# Edite .env: defina JWT_SECRET (mín 32 chars) → openssl rand -hex 32# OPENAI_API_KEY é opcional — serviço retorna mock local sem ele# 2. Suba a stack completa
docker compose up -d
# 3. Aguarde os health checks (≈ 2 min no primeiro boot)
docker compose ps
# 4. Acesse# Frontend: http://localhost:3000# API (via Traefik): http://localhost/api/v1/...# Traefik dashboard: http://localhost:8888/dashboard/# RabbitMQ: http://localhost:15672 (guest/guest)
Setup Staging (DB-per-service)
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d
# User Service → banco dedicado scopeflow_users (:5433)# Ver: docs/migration/DB-MIGRATION-USER-SERVICE.md para cut-over em produção
Desenvolvimento Local (sem Docker para os serviços Java)
# Infraestrutura apenas
docker compose up postgres user-db rabbitmq redis -d
# Monólitocd backend && ./mvnw spring-boot:run # http://localhost:8080/api/v1# User Servicecd user-service && ./mvnw spring-boot:run # http://localhost:8081/api/v1# Frontendcd frontend && npm install && npm run dev # http://localhost:3000
Toda decisão arquitetural relevante gera um ADR em docs/architecture/adr/ ou docs/migration/adr/. Usar o template em §7. Regra: se uma decisão vai gerar pergunta "por quê fizemos assim?" no futuro, ela merece um ADR.
Métricas do Projeto
Métrica
Valor
Linhas de código Java (monólito)
~15.000
Classes Java (user-service)
40
Testes — monólito
62 arquivos (59 classes de teste + 3 fixtures/configs)
Testes — user-service
7
Suítes Vitest — frontend
7
Flyway migrations (monólito)
V1–V9 (9 aplicadas)
Flyway migrations (user-service)
V1 (1 aplicada)
ADRs documentados
12 (8 arquitetura + 4 migração)
Extraction cards
4 (1 extraído, 1 próxima, 2 backlog)
Dúvidas sobre este documento? Ver CLAUDE.md para contexto de implementação ou docs/README.md para o índice completo de documentação.
