Reparou — Stack Técnica

Decisão (11/06/2026): a base do Reparou é a mesma stack do ailook (~/IdeaProjects/ailook), hospedada no Railway por ora. Stack já dominada pelo time, com padrões operacionais validados em produção.

Stack

Camada	Tecnologia
Monorepo	pnpm 9 + Turborepo 2
Backend	Node 20 + Express 4 + Prisma 6 + PostgreSQL + Zod + Pino
Web	Next.js 15 + React 19 + Tailwind v4 + TanStack Query + Zustand
Mobile	Expo (expo-router) + React Native + TanStack Query
Shared	`packages/shared` — Zod schemas + tipos compartilhados
Infra	100% Railway (api + web + Postgres plugin), Nixpacks; mobile via EAS Build (release only)
Design system	RaceOS (ver `design-language.md`) sobre Tailwind v4 — tokens dark/light desde o início

Estrutura do monorepo

reparou/
├── apps/
│   ├── api/         # @reparou/api    (Express + Prisma)
│   ├── web/         # @reparou/web    (Next.js 15 — cockpit da oficina + portal do cliente)
│   └── mobile/      # @reparou/mobile (Expo — app da oficina, único e multipapel, F2)
├── packages/
│   └── shared/      # @reparou/shared (Zod + types)
├── docs/            # análise de mercado, visão, blueprint, design language
├── turbo.json
├── pnpm-workspace.yaml
├── railway.toml     # raiz fallback; cada service tem o seu (apps/api, apps/web)
└── nixpacks.toml

Adaptações em relação ao ailook

As 5 decisões de fundação do blueprint-plataforma.md mapeadas para esta stack:

Multi-tenancy hierárquico. No ailook o tenant é plano (contaId). No Reparou o schema nasce com dois níveis: Conta (tenant raiz — a empresa/grupo) e Unidade (a oficina física). Toda entidade operacional (OS, orçamento, box, estoque) carrega contaId + unidadeId; entidades de cadastro (cliente, veículo) carregam contaId (compartilhadas entre unidades da mesma conta). A UI da Fase 1 expõe 1 unidade; o modelo já suporta rede/franquia (módulos 1, 28, 42, 44).
RBAC + audit log dia 1. Papéis iniciais: OWNER · GESTOR · CONSULTOR · MECANICO. Tabela de auditoria (quem, o quê, quando, antes/depois) escrita pelos services desde a primeira entidade.
Campos customizados. Entidades centrais (OS, orçamento, checklist) com coluna JSONB customFields validada por schema Zod dinâmico por conta.
Eventos de domínio. Services publicam eventos (os.criada, orcamento.aprovado, veiculo.entregue) numa tabela outbox no Postgres — sem broker por enquanto (Railway, simplicidade); consumidores: automações/WhatsApp hoje, Workflow Engine (37) e Data Platform (45) depois.
API-first. O web/mobile consomem a mesma API REST validada por Zod que será a API pública (46) — nenhum acesso Prisma fora de apps/api.

Integrações de plataforma (providers abstraídos desde o início)

Fiscal: NFS-e/NF-e via API terceirizada (candidata: Focus NFe — mesma da Griffo). Abstrair atrás de um FiscalProvider.
WhatsApp: aproveitar a experiência do wpp-gateway/Ogmma; abstrair atrás de um MessagingProvider (canal-agnóstico, módulo 38).
Portal do cliente: acesso por token/magic-link (sem papel de usuário), padrão já usado no Portal da Cliente do ailook.

Padrões operacionais (herdados do ailook — ver CLAUDE.md)

Clean Architecture lite: Routes → Controllers → Services → Prisma → Postgres; controller ≤ 200 linhas e sem lógica de negócio; service ≤ 300 linhas.
Validação Zod em toda rota; Pino (nunca console.log); AppError; Argon2; JWT access + refresh.
Branch única main; push em main = deploy Railway; builds e testes 100% locais antes de qualquer push (regra inviolável — Railway não é ambiente de teste).
Conventional Commits; arquivos kebab-case.ts.