01 — Arquitetura e Stack

Princípio

Lógica de negócio pesada no service; UIs separadas por audiência; conteúdo público no website; persistência via PostgreSQL + Hasura; cache Redis quando aplicável.

Apps (boilerplate)

App	Stack	Audiência	Domínio prod
`apps/service`	NestJS	API REST	service.framework.forestbit.io
`apps/app`	React + Vite + TanStack Router + Apollo	Cliente final	app.framework.forestbit.io
`apps/backoffice`	React + Vite + TanStack Router + Apollo	Admin interno	backoffice.framework.forestbit.io
`apps/website`	Next.js	Marketing / SEO	framework.forestbit.io
`apps/hasura`	Hasura + PostgreSQL	GraphQL / permissions	api.framework.forestbit.io
`apps/pgbouncer`	PgBouncer	Pool de conexões	(infra Docker)

O que cada app inclui (features shipped): README raiz.

Stack

Camada	Tecnologia
Frontend	React, Vite, Tailwind, shadcn/ui, TanStack Router
Backend	NestJS (REST API)
DB	PostgreSQL + PgBouncer (pool)
GraphQL	Hasura
Cache	Redis
Infra	Docker Compose, Dokploy

Fluxo de dados

Browser (app/website)
    → service (REST/API)
    → Hasura → PgBouncer → PostgreSQL
    → Redis (cache, jobs)
    → Integrações externas (Stripe, email, APIs de terceiros, …)

Connection pooling (PgBouncer)

GraphQL subscriptions e picos de API abrem muitas conexões no Hasura. PgBouncer na porta 6432 multiplexa clientes em um pool menor de conexões reais no Postgres (porta 5432 local; 5439 em prod para admin/migrations).

Config: apps/pgbouncer/
Hasura: HASURA_GRAPHQL_DATABASE_URL → pgbouncer:6432
Pool mode: transaction (use_prepared_statements: false na metadata)

Onde documentar o quê

Assunto	Documento
Módulos, regras de negócio, fluxos, status	product/04-features-modules.md
Endpoints REST, Hasura, webhooks, integrações	04-api-integrations
Identidade, tema, logos, domínios (`@framework/brand`)	10-brand-kit
Status shipped do template (gates)	00-boilerplate-status
Specs técnicas por feature	`specs/NNN-nome/`

Fronteiras importantes

Não duplicar regras de negócio críticas no frontend — service é source of truth
Hasura: permissões e queries; regras complexas no service
Help docs (apps/app/public/docs/): conteúdo para cliente, não arquitetura

Decisões arquiteturais (ADR index)

ADR	Título	Status
—	Monorepo pnpm	Adotado
—	Spec Kit para features	Adotado

Registrar ADRs novos em docs/development/adr/ quando necessário.

Links relacionados

04-api-integrations
product/04-features-modules.md
.specify/memory/constitution.md