convez.ai
Agente
m-haziq

fullstack-ai-agent-boilerplate

m-haziq/fullstack-ai-agent-boilerplate

Ver no GitHub
InicialPluginScore · de 0 a 100

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-boilerplate

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Fullstack AI Agent Boilerplate

License: MIT Built for Claude Code Stack: React + Express + Prisma

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

LayerTechnology
FrontendReact 19, Vite, TypeScript, TanStack Router/Query, Zustand, Tailwind v4, shadcn/ui
API clientOpenAPI → Orval → typed React Query hooks
BackendExpress 5, TypeScript, Node.js
ORMPrisma
DatabasePostgreSQL (shared, multi-tenant via tenantId)
AuthJWT — 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

  • tenantId is server-controlled — set once at signup to the 'default' tenant and embedded in the JWT. Never trust an x-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 a member. Use requireRoles(...) (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), or public. Post is owner-scoped. Inaccessible records return 404 — existence is never leaked.

License

MIT — use it for anything, including commercial projects.

Ver o original no GitHub

Bom para

Relacionados