# Tessera

Open-source ticketing system — Request Tracker's paradigm rebuilt in modern TypeScript.

## Architecture

```
tessera/
├── src/                    # Backend: Bun + Hono + Drizzle ORM
│   ├── index.ts            # Hono server entry (port 9876)
│   ├── config.ts           # Zod-validated env config
│   ├── db/                 # Drizzle ORM schema + migrations
│   ├── routes/             # REST API endpoints
│   ├── models/             # TypeScript types + Zod schemas
│   ├── scrip/              # Scrip engine (prepare/commit two-phase)
│   └── lifecycle/          # State machine validator
├── web/                    # Frontend: Next.js 15 + shadcn/ui
│   └── src/app/            # App Router pages
├── drizzle/                # SQL migration files
└── docs/                   # Architecture + design specs
```

## Stack

**Backend:** Bun runtime, Hono web framework, Drizzle ORM, PostgreSQL 17, Zod validation, Handlebars templates, nodemailer

**Frontend:** Next.js 15 App Router, shadcn/ui (Tailwind CSS), next-themes (light/dark), React Hook Form + Zod, TanStack Table, date-fns, lucide-react icons

**Fonts:** Inter (variable, with cv01+ss03 OpenType features), JetBrains Mono

## Running Locally

### Prerequisites
- Bun (`nix-shell -p bun` or install globally)
- Node.js 22+ (`nix-shell -p nodejs_22`)
- Docker (for PostgreSQL)
- PostgreSQL container: `docker run -d --name tessera-db -e POSTGRES_USER=tessera -e POSTGRES_PASSWORD=*** -e POSTGRES_DB=tessera -p 127.0.0.1:5433:5432 postgres:17-alpine`

### Start backend
```bash
cd ~/projects/tessera
cp .env.example .env   # Edit DATABASE_URL to point to postgres://tessera:***@127.0.0.1:5433/tessera
bun run src/index.ts   # Starts on port 9876
```

### Run migrations
```bash
bun run src/db/migrate.ts
```

### Start frontend
```bash
cd web
npm install        # Use npm, NOT bun (bun has compatibility issues with Next.js dev server)
npx next build     # Production build
npx next start --port 5173   # Production server
```

**Note:** `bun run dev` (Turbopack) has WebSocket HMR issues in this environment. Use production mode only.

## API Endpoints

All endpoints are served by the backend on port 9876. The frontend proxies `/api/*` to the backend via `next.config.ts`.

| Method | Path | Description |
|--------|------|-------------|
| GET | /health | Health check |
| GET | /tickets | List tickets (?queue_id=&status=) |
| POST | /tickets | Create ticket |
| GET | /tickets/:id | Get ticket with custom fields |
| PATCH | /tickets/:id | Update ticket (validates lifecycle, runs scrips) |
| POST | /tickets/:id/preview | Dry-run scrips for status change |
| POST | /tickets/:id/comment | Add comment to ticket |
| GET | /tickets/:id/transactions | List ticket transactions |
| GET/POST | /queues | List/create queues |
| GET/POST/PATCH | /scrips | CRUD scrips |
| GET/POST | /custom-fields | List/create custom fields |
| GET/POST | /lifecycles | List/create lifecycles |

## Key Design Decisions

- **Ticket IDs are sequential integers** (1, 2, 3...), formatted as `TKT-0001` for display. No UUIDs.
- **Transaction-centric:** Every state change creates a transaction record. The scrip engine runs on transactions.
- **Two-phase scrip engine:** Prepare (no side effects) then Commit (execute actions). Supports dry-run mode.
- **Lifecycle state machines:** Per-queue configurable status transitions with wildcard support.
- **Light mode is default.** Dark mode available via theme toggle (next-themes).
- **No ORM for frontend:** Drizzle is only on the backend. Frontend uses a typed fetch wrapper (`web/src/lib/api.ts`).

## Git Workflow

Repo: `https://git.gjermund.xyz/gjermund/tessera`

Push via HTTPS with token auth (SSH port 2222 is not configured on Gitea):
```bash
git remote set-url origin https://gjermund:TOKEN@git.gjermund.xyz/gjermund/tessera.git
```

## Development Workflow

All code is written by **OpenCode** (AI coding agent). Hermes writes specs, OpenCode writes code, Gjermund reviews.

OpenCode server: `opencode serve --port 4096` (Gjermund attaches with `opencode --attach http://127.0.0.1:4096`)

After OpenCode makes changes:
1. `cd web && npx next build` — verify zero errors
2. `npx next start --port 5173` — restart production server
3. `git push` — push to origin

## Common Issues

- **Frontend shows skeleton/blank page:** The frontend dev server (Turbopack) has WebSocket HMR issues. Use production mode (`npx next build` + `npx next start`).
- **Backend not running on 9876:** Restart with `bun run src/index.ts`. Check port with `ss -tlnp | grep 9876`.
- **Database connection refused:** Docker container may be stopped. `docker start tessera-db`.
- **Build errors after migration:** Run `bun run src/db/migrate.ts` to apply new migrations.