# {{projectName}}

A SpecVerse starter — backend API, database, and React frontend
generated from a single specification. This is the **default** template
when you run `spv init` without a `--template` flag.

Your `specs/main.specly` was loaded from the canonical default spec in
`@specverse/engines` — the same spec that app-demo's Server Manager
"new spec" action creates. Two models (Category and Item), one
belongsTo relationship, one lifecycle — small enough to read in a
minute, rich enough to demonstrate the generated-UI rules. Extend it
freely.

For a richer starting point with User / Project / Task / lifecycles /
behaviors already filled in, try `spv init my-app --template full-stack`.
For a fully standalone editable React output (no `@specverse/runtime`
dep), add `--static` — same scaffold, different frontend factory.

## 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)