fullstack-ai-agent-boilerplate
m-haziq/fullstack-ai-agent-boilerplate
Production-ready full-stack starter built for AI coding agents. React 19 + Vite + Express 5 + Prisma + PostgreSQL + JWT auth. Every layer ships a CLAUDE.md.
Instalação
npx convez-ai m-haziq/fullstack-ai-agent-boilerplate1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Fullstack AI Agent Boilerplate
A lean, contract-first fullstack starter for an AI web-app generator. Standard CRUD is generated from an
AppContract; agents implement only custom logic.
How it works
An external runner owns the AppContract and compiles it down the stack. The goal is
to minimize the code an agent writes per app:
AppContract
→ shared/openapi.yaml (generated contract)
→ frontend/src/api/generated/** (Orval: typed React Query hooks + models)
→ backend/prisma/schema.prisma (generated DB schema)
→ backend/src/generated/** (generated standard CRUD)
→ frontend/src/generated/** (generated standard pages)
→ Claude implements CUSTOM logic only (backend/src/custom, frontend/src/custom)
→ npm run validate
Source of truth — read this first
- The external runner owns the AppContract.
- shared/openapi.yaml is GENERATED from the AppContract.
- backend/prisma/schema.prisma is GENERATED from the AppContract.
- frontend/src/api/generated/** is GENERATED by Orval from shared/openapi.yaml.
- backend/src/generated/** is GENERATED standard CRUD.
- frontend/src/generated/** is GENERATED standard pages/components.
RULES
- NEVER hand-edit generated artifacts — they are overwritten on every generation.
- NEVER create a manual API client or a custom React Query hook when an Orval
hook already exists — import the generated hook.
- NEVER hand-author CRUD that already exists in a generated folder.
- Add custom logic ONLY through the custom/** extension points.
- Authentication (JWT) is a stable prebuilt foundation — it is NOT generated.
Per-layer guides: CLAUDE.md · backend/CLAUDE.md ·
frontend/CLAUDE.md. The Post resource is the golden
generated pattern (backend CRUD + list/detail/create/edit pages, all via generated hooks).
Stack
| Layer | Technology |
|---|---|
| Frontend | React 19, Vite, TypeScript, TanStack Router/Query, Zustand, Tailwind v4, shadcn/ui |
| API client | OpenAPI → Orval → typed React Query hooks |
| Backend | Express 5, TypeScript, Node.js |
| ORM | Prisma |
| Database | PostgreSQL (shared, multi-tenant via tenantId) |
| Auth | JWT — token in localStorage, injected by the generated fetch client |
Quick start
docker compose up -d # 1. PostgreSQL
cp backend/.env.example backend/.env # 2. env (DATABASE_URL pre-filled)
npm run install:all # 3. install backend + frontend
npm --prefix backend run db:migrate:dev # 4. create tables
npm run api:generate # 5. generate Orval hooks from openapi.yaml
npm --prefix backend run dev # 6. API on :3000
npm --prefix frontend run dev # 7. app on :3001 (new terminal)
Then open http://localhost:3001 → /signup, /login, /dashboard, and the /posts
reference resource (list / detail / create / edit / delete).
Commands (root)
npm run api:generate # Orval: openapi.yaml → typed hooks
npm run db:generate # Prisma client
npm run db:validate # Prisma schema validation (no DB connection)
npm run typecheck # backend + frontend tsc --noEmit
npm run build # backend + frontend production builds
npm run validate # fast deterministic gate (see below)
npm run validate:release # validate + backend production build
npm run test:security # backend security baseline (needs PostgreSQL)
npm run test:e2e # Playwright (NOT part of validate)
npm run validate runs, in order: openapi existence check → Orval generation →
Prisma schema validation → Prisma client generation → backend typecheck → frontend
typecheck → frontend production build. It needs backend/.env for DATABASE_URL but
never connects to the database. E2E is excluded on purpose to keep it fast.
test:security and CI (.github/workflows/validate.yml) do need a running PostgreSQL
with migrations applied.
Multi-tenant & RBAC security
tenantIdis server-controlled — set once at signup to the'default'tenant and embedded in the JWT. Never trust anx-tenant-id(or any tenant/owner id) from the client. Onboarding into an existing org must use a signed invitation token.- The JWT carries
{ id, email, tenantId, role }.role(admin|member) is server-controlled; a public signup is always amember. UserequireRoles(...)(backend/src/lib/authorize.ts) to gate routes. - Every generated query is scoped by an access policy (
backend/src/lib/accessPolicy.ts):owner(userId + tenantId),tenant(tenantId), orpublic. Post isowner-scoped. Inaccessible records return404— existence is never leaked.
License
MIT — use it for anything, including commercial projects.