# AI Coding Starter Kit

> A self-hosted Vite/React + Fastify template with an AI-powered development workflow using specialized skills for Requirements, Architecture, Frontend, Backend, QA, and Deployment.

## Tech Stack

- **Frontend:** Vite + React 19 + TypeScript
- **Styling:** Tailwind CSS + shadcn/ui (copy-paste components)
- **Backend:** Fastify + Drizzle ORM + PostgreSQL, own JWT auth
- **Deployment:** self-hosted Linux server — git pull + rsync + systemd, updates pulled from Gitea
- **Validation:** Zod + react-hook-form
- **State:** React useState / Context API

## Project Structure

```
frontend/
  src/
    main.tsx, App.tsx    Entry points
    components/
      ui/                 shadcn/ui components (NEVER recreate these)
    hooks/                Custom React hooks
    lib/                  Utilities (utils.ts)
backend/
  src/
    server.ts             Fastify app entry
    routes/                Route handlers
    db/                    Drizzle schema + connection
  drizzle/                 Generated migrations
features/                  Feature specifications (PROJ-X-name.md)
  INDEX.md                 Feature status overview
docs/
  PRD.md                   Product Requirements Document
  production/              Production guides (error tracking, security, performance)
```

## Development Workflow

1. `/requirements` - Create feature spec from idea
2. `/architecture` - Design tech architecture (PM-friendly, no code)
3. `/frontend` - Build UI components (shadcn/ui first!)
4. `/backend` - Build APIs, database schema, auth checks
5. `/qa` - Test against acceptance criteria + security audit
6. `/deploy` - Deploy to the server + production-ready checks

## Feature Tracking

All features tracked in `features/INDEX.md`. Every skill reads it at start and updates it when done. Feature specs live in `features/PROJ-X-name.md`.

## Key Conventions

- **Feature IDs:** PROJ-1, PROJ-2, etc. (sequential)
- **Commits:** `feat(PROJ-X): description`, `fix(PROJ-X): description`
- **Single Responsibility:** One feature per spec file
- **shadcn/ui first:** NEVER create custom versions of installed shadcn components
- **Human-in-the-loop:** All workflows have user approval checkpoints
- **No RLS backstop:** authorization/ownership checks are explicit in Fastify route handlers, not enforced by the database

## Build & Test Commands

```bash
# frontend/
npm run dev        # Vite dev server (localhost:5173)
npm run build      # Production build
npm run lint       # ESLint

# backend/
npm run dev        # tsx watch (localhost:4000)
npm run build      # tsc build
npm run start      # node dist/server.js
npm run db:generate  # generate Drizzle migration
npm run db:migrate   # apply migrations
```

## Product Context

@docs/PRD.md

## Feature Overview

@features/INDEX.md