Fundamentos de APIs com Node.js e Express presentes nos serviços do backend.
Stack
React 19
Vite
Node.js
Express 5
PostgreSQL/Supabase
Prisma 7
Carregando documentação do repositório…
Ler documentação completa
README.mdmain
SafeAnchor
Digitalizando gestao de frota, segurança operacional e capacitacao profissional para o setor maritimo.
MVP de apresentacao — investidores, Parque Tecnologico do Mar banca e parceiros
Este README e o Project Control Plane do SafeAnchor: a fonte principal de
contexto para desenvolvedores e agentes de IA. Ele descreve o que o produto
e, como esta arquitetado, o que ja foi implementado e o que vem a
seguir.
Regra central: nada aqui foi inventado. Todo status foi extraido do estado
atual do repositorio. Se algo precisa mudar, o repositorio muda primeiro e o
README depois.
Product Vision
SafeAnchor e uma plataforma Vertical SaaS pensada para o ecossistema
maritimo — proprietarios, gestores de frota, prestadores de servicos e marinas.
Se a premissa for correta, o setor nao precisa so de um app, mas de uma camada
operacional que conecte todo o ecossistema maritimo.
O projeto nasce no Parque Tecnologico do Mar (PTM), em Caucaia (CE), e nasce
como MVP de apresentacao: funcional o suficiente para demonstrar a proposta
de valor e validar a visao com investidores, parceiros e a banca de incubacao.
Problem
O que o setor ainda usa hoje
Planilhas e cadernos
Checklists em papel e inspecoes manuais
Registro informal de manutencao
Documentacao descentralizada
Treinamentos profissionais fragmentados
Esses processos aumentam riscos operacionais, reduzem eficiencia e
dificultam a conformidade.
O que o SafeAnchor entrega
Uma camada operacional unificada que centraliza:
Gestao de frotas — prontidao das embarcacoes em tempo real
Manutencao — agenda, historico, previsao
Documentacao — certificados e conformidade
Checklists e inspecoes — execucao, historico, certificados
Treinamento — trilhas de capacitacao e certificados de conclusao
Marketplace — conexao entre proprietarios, prestadores e marinas
O produto e organizado em torno dessa jornada. Cada feature do rebaseline
contribui para uma etapa dela, do acesso (Login) ate a decisao de prontidao
operacional.
MVP Scope
In Scope
Features definidas no rebaseline 2026 (Features 031–038):
Feature
Nome
Situacao
031
Ownership & Access Scope
✅ backend implementado
032
Product Shell & Main Dashboard
⬜ planejada
033
Vessel Operational Profile
⬜ planejada
034
Documents Core
⬜ planejada
035
Expiration & Compliance
⬜ planejada
036
Safety Completion & Mobile Polish
⬜ planejada
037
MVP UX Polish
⬜ planejada
038
CI/CD & Production Deploy
🔶 parcial (frontend publicado; backend nao)
A Definition of Ready completa esta em
docs/product/mvp-rebaseline.md: a jornada
Login → Prontidao funciona de ponta a ponta, dados isolados por ownership,
dashboard com dados reais, documentos com vencimentos, checklist mobile
funcional, UI consistente e backend + frontend publicados com health check e
smoke test.
Out of Scope
Nao fazem parte do MVP atual (definido em
docs/product/mvp.md e mvp-rebaseline.md):
App mobile nativo e execucao de checklist offline-first
Integracoes AIS e sensores IoT (previsao preditiva com IA)
Marketplace completo de prestadores (transacao/pagamento)
Processamento de pagamentos
Suporte multi-idioma
Analytics avancados / dados agregados (Fase 4)
Assinatura nativa de documentos e workflows de certificacao complexos
Automacoes de notificacao avancadas (alem de alertas do MVP)
Maritime Academy (Features 021–025) e QR Code avancado — ficam pos-MVP
conforme rebaseline
Além disso, conforme
AGENTS.md: nao adicionar Next.js, TypeScript ou Tailwind
nesta fase; preservar Prisma + PostgreSQL.
Personas
Personas de produto (modelo de negocio)
Persona
Papel
Valor pago
Proprietario / gestor de frota
Gerencia embarcacoes, manutencao e documentos
Assinatura mensal (SaaS)
Prestador de servicos
Recebe chamados, agenda inspecoes, gera certificados
Comissao por servico + planos premium
Marina
Gerencia ocupacao, equipe, servicos e reservas
Planos de operacao + comissao por intermedio
Mecanismos de receita
Subscriptions (SaaS) — planos mensais por persona
Transacoes (Marketplace) — comissao sobre concretizacao de servicos
Dados agregados (Analytics) — relatorios e insights para o setor
Fases de evolucao
Fase 1 (MVP) — Proprietarios (frota + manutencao + inspecao)
Fase 2 — Inclusao de prestadores e marketplace
Fase 3 — Marina como operadora central
Fase 4 — dados agregados, analytics e insights
Roles no backend (estado atual)
O schema do banco define roles USER, MANAGER e ADMIN
(enum UserRole em apps/backend/prisma/schema.prisma). Escritas em vessels,
maintenances, checklists e preventivas exigem MANAGER ou ADMIN. A
navegacao por persona no frontend e feita com contas demo (mock).
Core User Journey
Jornada do MVP (rebaseline 2026), de acesso ate a decisao de prontidao:
Estado verificado no snapshot atual do repositorio (branch main).
Nao confie em "funcional" sem olhar a tabela — no frontend, muitos modulos
exibem dados mock.
Completed
Backend (API real, PostgreSQL via Prisma):
Autenticacao (register/login/me) com bcrypt (custo 12) + JWT (1h)
Autorizacao por roles USER / MANAGER / ADMIN (authorizeRoles)
Ownership & Access Scope (Feature 031) — accessScopeService filtra por party do usuario + organizacoes
CRUD de embarcacoes (listar, criar, detalhe, atualizar, remover)
Manutencoes + dashboard
Manutencao preventiva
Templates e execucoes de checklist
Endpoint /modules
Health check com conexao ao banco
Logging estruturado com pino + redacao de campos sensiveis
Database — Prisma + PostgreSQL + migrations e RLS sem policies prontos. Pendente: modelo Document, políticas de propriedade quando necessario.
Authentication — JWT + bcrypt prontos no backend. Pendente no MVP: refresh token; tela de login consumindo a API real.
Authorization — Roles + ownership prontos. Pendente: permissoes por modulo e por organizacao.
Core Maritime Domain — Frota, manutencao, preventiva e checklists prontos. Pendente: inspecoes (backend) e documentos.
Storage — Nao iniciado; necessario para Documents (Supabase Storage).
Mobile — Nao iniciado; mobile polish de checklists (Feature 036) e PWA sao itens futuros.
Testing — Backend coberto; faltam testes de controllers no backend e testes no frontend.
Security — Base presente (hashing, JWT, ownership, RLS, redacao de logs). Pendente: rate limiting, upload security, dependency/security scanning.
Observability — Logging estruturado + health check prontos. Pendente: metricas, tracing e alertas.
Infrastructure — Dev local funciona. Pendente: hospedagem de producao do backend.
CI/CD — CI e deploy do frontend prontos. Pendente: deploy do backend e smoke test em producao (Feature 038).
Production Readiness — Pendente (Feature 038 + Definition of Ready).
Pilot / Validation — Pendente; validacao com PTM, parceiros e investidores.
AI Development Workflow
A IA nunca decide sozinha mudancas de escopo. O fluxo e:
Human
→ Analysis
→ Specification
→ AI Implementation
→ Human Review
→ Tests
→ Commit
→ Pull Request
→ Merge
A especificacao vem do humano (ou de documento aprovado) antes de qualquer
implementacao. Alteracoes de escopo sao propostas pela IA, mas sempre
aprovadas pelo humano.
AI Rules
Regras para agentes de IA que atuarem neste repositorio (tambem em
AGENTS.md):
Primeiro entender o contexto.
Depois analisar.
Depois propor plano.
So entao implementar.
Trabalhar em pequenos incrementos.
Nao alterar arquivos fora do escopo.
Nao adicionar dependencias sem justificativa.
Nao apagar funcionalidades existentes sem autorizacao.
Nao considerar uma tarefa concluida sem validacao.
Sempre informar arquivos alterados.
Sempre informar comandos de validacao executados.
Sempre informar limitacoes ou problemas encontrados.
Cuidados de stack nesta fase: nao adicionar Next.js, TypeScript ou Tailwind;
preservar Prisma e PostgreSQL; nunca versionar .env ou credenciais do
Supabase; usar DATABASE_URL no runtime e DIRECT_URL no Prisma CLI.
Definition of Done
Uma tarefa so e considerada concluida quando:
implementacao realizada;
testes relevantes executados;
build validado quando aplicavel;
comportamento revisado;
documentacao atualizada quando necessario;
alteracao revisada pelo humano;
commit criado.
Development Commands
Comandos reais extraidos dos package.json do repositorio. Nada foi inventado.
Nao existe script de lint (sem ESLint configurado).
Instalacao
# raiz — instala frontend e backend
npm run install:all
# ou por app
npm install --prefix apps/backend
npm install --prefix apps/frontend
Backend
cd apps/backend
cp .env.example .env # preencha DATABASE_URL / DIRECT_URL / JWT_SECRET
npm run dev # dev com watch (node --watch src/server.js)
npm start # producao local (node src/server.js)
API por padrao em http://localhost:3001 (define PORT no .env).
Frontend
cd apps/frontend
npm run dev # Vite dev server
npm run build # build de producao (dist/)
npm run preview # previsualiza o build
Aplicacao em http://localhost:5173.
Rodar pela raiz (scripts do monorepo): npm run dev:frontend,
npm run dev:backend, npm run start:backend.
Testes
cd apps/backend
npm test # node --test (nao toca no Supabase)
ALLOW_DATABASE_SMOKE=true npm run test:db:smoke # smoke test contra o banco (consultar docs)
Database / Migrations (backend)
cd apps/backend
npx prisma generate # gera o client Prisma
npm run prisma:validate # valida o schema
npm run prisma:status # status das migrations
# Seed de desenvolvimento — BLOQUEADO por padrao; habilite somente ciente do destino
ALLOW_DATABASE_SEED=true npx prisma db seed
# Comparar schema com o banco antes de registrar baseline (diff vazio)
npx prisma migrate diff --from-config-datasource --to-schema=prisma/schema.prisma --script
Nunca use prisma migrate reset ou prisma db push no projeto remoto.
deploy-frontend.yml — build com VITE_BASE_URL=/safeanchor-monorepo/ e deploy no GitHub Pages
Environment
Somente as variaveis realmente utilizadas pelo projeto. Nenhum secret ou
valor sensivel aqui — nunca versione .env.
Backend (apps/backend/.env)
Variable
Obrigatoria
Descricao
DATABASE_URL
sim
Conexao de runtime (Supabase pooler)
DIRECT_URL
sim*
Conexao para Prisma CLI (migrations/generate/validate)
JWT_SECRET
sim
Assinatura dos tokens JWT (valor aleatorio longo)
PORT
nao
Porta do servidor (padrao 3001)
*DIRECT_URL e obrigatoria para comandos do Prisma CLI; em runtime o backend usa apenas DATABASE_URL.
Flags de operacao (avaliacao do proprio contexto):
Flag
Efeito
ALLOW_DATABASE_SEED
Libera a execucao do seed
ALLOW_DATABASE_SMOKE
Libera o smoke test contra o banco
Frontend
Variable
Obrigatoria
Descricao
VITE_API_URL
sim (prod)
URL publica da API; em dev usa /api
VITE_BASE_URL
sim (GH Pages)
Base do build; no CI e ./safeanchor-monorepo/
Na raiz nao ha .env; o apps/frontend/.env.example ainda nao existe no
repositorio.
Security Baseline
Principios de seguranca do MVP — marcados pelos que ja existem no repositorio.
Tema
Situacao
Authentication
✅ JWT + bcrypt (custo 12), expiracao 1h
Authorization
✅ Roles USER/MANAGER/ADMIN no backend
Ownership / Access Scope
✅ accessScopeService isola dados por party/organizacao
Password hashing
✅ bcrypt; hash nunca exposto
JWT security
✅ payload minimo, JWT_SECRET via env
Input validation
✅ validacoes nos controllers
Rate limiting
⬜ nao implementado
Secure secrets
✅ .env* ignorado; apenas .env.example versionado
Database security
✅ RLS ativo sem policies; privilegios de anon/authenticated revogados; acesso so via backend
Upload security
⬜ depende da Feature 034 (Documents)
Logging
✅ pino estruturado com redacao de headers/body sensiveis
Backups
🔶 via Supabase (gerenciado; fora do codigo)
Dependency / security scanning
⬜ nao configurado
Product Decision Log
Decisoes ja tomadas. Datas aproximadas pelo historico do git.
Date
Decision
Reason
2026
Monorepo com apps/backend + apps/frontend
Separar API e UI mantendo repo unico de estudo
2026
Frontend em MVVM; backend em Route → Controller → Service → Prisma
Camadas testaveis e didaticas
2026
Prisma 7 + PostgreSQL (Supabase)
ORM com types/safety e migrations; banco gerenciado
2026
DATABASE_URL no runtime, DIRECT_URL no Prisma CLI
Pooling no runtime, conexao direta para migrations
2026
JWT sem refresh token no MVP
Simplicidade; refresh sera adicionado na fase de producao
2026
RLS habilitado sem policies; acesso so pelo backend
Bloquear Data API e manter um unico caminho de acesso
2026
Datas como String e items/responses como JSON nos contratos atuais
Preservar contratos da API existente
2026
packages/shared reservado, sem uso agora
Aprender com estrutura simples antes de abstrair
2026
GitHub Pages com fallback 404.html
Roteamento SPA em subpath
2026
Seed e operacoes destrutivas protegidas por flags
Evitar alteracoes acidentais no banco remoto
2026-09
Rebaseline do MVP: Operational Readiness (Features 031–038)
Focar na jornada Login → Prontidao Operacional
2026
Sem Next.js / TypeScript / Tailwind nesta fase
Fase de aprendizado, stack simples e didatica
Current Focus
O que estamos tentando resolver AGORA?
Completar o MVP de apresentacao (Rebaseline 2026 — Operational Readiness):
entregar a jornada Login → Dashboard → Frota → Embarcacao →
Manutencao/Checklists/Documentos → Prontidao Operacional com dados reais,
ownership aplicado de ponta a ponta e frontend + backend publicados — pronto
para ser validado por investidores, parceiros e PTM.
Next Action
Next Action
Feature 032 — Product Shell & Main Dashboard (rebaseline): implementar o
shell autenticado padronizado e o dashboard principal consolidando a prontidao
da frota, manutencoes pendentes/proximas, inspecoes recentes e documentos
proximos do vencimento — com os dados reais vindos da API do backend (iniciando
pela conexao dos services de embarcacoes e manutencoes que hoje estao em mock).
