# {{projectName}}

A SpecVerse **full-stack demo** starter — backend API, database, and
React frontend generated from a rich specification. Unlike the
`default` template (minimal Category+Item spec), this ships with a
three-model demo (`User`, `Project`, `Task`) wired up with
relationships, lifecycles, events, and behaviors — enough to see
most of what SpecVerse can do from one spec.

Pick this template when you want to learn by reading a filled-out
example. Pick `default` (or omit `--template` entirely) when you
want the smallest viable starter to build your own spec on.

## Quick start

```bash
# 1. Generate code, install dependencies, and set up the database
npm run setup

# 2. Start backend and frontend in two terminals
npm run dev:backend       # API server on http://localhost:3000
npm run dev:frontend      # React app on http://localhost:5173

# 3. (Optional) run the example end-to-end test
npm run test:e2e
```

## Project structure

```
{{projectName}}/
├── specs/
│   └── main.specly              # Your specification — edit this
├── manifests/
│   └── implementation.yaml      # Technology stack config
├── tests/
│   └── e2e/                     # Hand-written Playwright tests
│       ├── example.spec.ts
│       └── README.md
├── playwright.config.ts         # Playwright config for tests/e2e/
├── tsconfig.json                # TypeScript config (for tests/)
├── generated/
│   └── code/                    # Generated application — do NOT edit by hand
│       ├── backend/             # Fastify + Prisma
│       └── frontend/            # React + Vite + Tailwind
├── docs/                        # Generated docs and diagrams
├── CLAUDE.md                    # AI assistant guide
└── package.json
```

## Commands

| Command | Description |
|---|---|
| `npm run validate` | Validate the spec |
| `npm run infer` | Run AI inference (writes `specs/inferred.specly`) |
| `npm run build` | Validate + realize (regenerates `generated/code/`) |
| `npm run setup` | Build + install deps + set up database |
| `npm run dev:backend` | Start the backend dev server |
| `npm run dev:frontend` | Start the frontend dev server |
| `npm run start` | Run the production backend |
| `npm run test:e2e` | Run hand-written Playwright tests in `tests/e2e/` |
| `npm run gen:docs` | Generate documentation under `docs/` |
| `npm run gen:diagrams` | Generate Mermaid diagrams under `docs/diagrams/` |
| `npm run clean` | Remove `generated/code/` and `specs/inferred.specly` |

## What ships in the starter spec

The starter `specs/main.specly` is a small task-management demo with:

- **User**, **Project**, **Task** models
- A simple lifecycle on tasks (`pending → in_progress → completed`)
- List, detail, and dashboard views
- Notification + assignment service stubs

Replace it with your own domain — keep the same component / model
shape and the realize engine takes care of the rest.

## Technology stack

| Layer | Technology |
|---|---|
| Spec → code | SpecVerse engines (`@specverse/engines`) |
| Backend | Fastify + TypeScript |
| ORM | Prisma |
| Database | **SQLite** for `development` (zero-deps), **PostgreSQL** for `production` (set `DATABASE_URL`) |
| Frontend | React + Vite + Tailwind CSS |
| Runtime view engine | `@specverse/runtime` |
| Tests (auto-generated) | Playwright contract tests under `generated/code/tests/contract/` |
| Tests (hand-written) | Playwright behavioral tests under `tests/e2e/` |

To switch the dev database to Postgres, edit
`manifests/implementation.yaml` → `configuration.environments.development.database`
and rerun `npm run build`.

## Prerequisites

- **Node.js 20+** (the realize engine and the generated backend require it)
- **`@specverse/self`** installed globally:
  ```bash
  npm install -g @specverse/self
  ```

## Iterate

1. Edit `specs/main.specly`
2. `npm run validate` — catches schema and convention errors
3. `npm run build` — regenerates `generated/code/`
4. `cd generated/code && npm run db:push` if your models changed
5. Reload the dev servers (Vite hot-reloads, the backend watches and restarts)

## Learn more

- [SpecVerse User Guide](https://github.com/SpecVerse/specverse-self/blob/main/docs/guides/SPECVERSE-USER-GUIDE.md)
- [Examples](https://github.com/SpecVerse/specverse-self/tree/main/generated/code/examples)