# burntop

> burntop (https://burntop.dev) is the showcase site for fullstack-ai-template, an open-source full-stack template for apps built by AI coding agents: FastAPI, React 19 and Postgres with auth, CRUD and 203 end-to-end tests. Mocks and untested routes fail the build, so the agent can't fake a green check.

The template has no generator and no AI inside the app. A new project is a copy of the repo. The "AI" part is for the agent that writes the code: nested AGENTS.md files, a project-standards skill with recipes, and guards that catch shortcuts. It works with Claude Code, Cursor, Codex or any agent that reads AGENTS.md.

## Start a project

Give your agent this prompt:

> Create a new project from https://github.com/agusmdev/fullstack-ai-template as described in its README, then open AGENTS.md and follow it.

Or do it by hand (needs Docker and the GitHub CLI):

```bash
gh repo create my-app --template agusmdev/fullstack-ai-template --private --clone
cd my-app && cp .env.example .env && docker compose up -d --build
```

App on http://localhost:3000, API on http://localhost:9095 (OpenAPI docs at /docs).

## Stack

- Backend: Python 3.12, FastAPI, SQLAlchemy 2 (async), Alembic, Pydantic 2, uv
- Frontend: React 19, TanStack Start, Router and Query, Tailwind 4, shadcn/ui, Bun
- Database: PostgreSQL 18
- Ops: Docker Compose, multi-stage Dockerfiles, GitHub Actions, Sentry, exact version pins

## What is included

- Session auth: register, login, logout, logout from all devices, Google OAuth, password reset, email verification, Argon2 hashing
- A reference `items` feature (router, service, repository; search, filters, sorting, pagination; ownership checks) that new features copy
- One error shape for every error: `{detail, error_code}`
- Structured request logging with secrets redacted
- About 60 make targets; `make ci` runs what CI runs

## Guarantees

- Only end-to-end tests: 161 backend tests against real Postgres (Testcontainers) and a live server, 42 Playwright tests against the full stack
- 39 mocking libraries are banned by ruff, so a mock import fails the build
- A route no test calls, a page no spec opens or a model without a migration fails the run
- A feature is done only when `make ci` passes

## Links

- [Template repository](https://github.com/agusmdev/fullstack-ai-template): source, README and quickstart
- [AGENTS.md](https://github.com/agusmdev/fullstack-ai-template/blob/main/AGENTS.md): where a coding agent starts
- [Linear clone](https://github.com/agusmdev/linear-clone-template): an app built from the template with one prompt
- [Notion clone](https://github.com/croto-bot/notion-clone): another app built from the template
- [burntop.dev](https://burntop.dev): the site, with live demos and the quickstart