docs(quotesdb): add project CLAUDE.md with workflow and design reference
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>quotesdb
Elijah Voigt
3 months ago
parent
05bad425a7
commit
4c48370373
@ -0,0 +1,177 @@
|
||||
# CLAUDE.md — quotesdb
|
||||
|
||||
> Inherits all conventions from [@../CLAUDE.md](../CLAUDE.md). This file adds project-specific workflow, structure, and agent dispatch rules.
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
`quotesdb` is a quotes web application in the vibed mono-repo. It consists of:
|
||||
|
||||
- **`api/`** — Rust/Axum backend on Cloudflare Workers
|
||||
- **`ui/`** — Yew (Rust/Wasm) frontend on Cloudflare Pages
|
||||
- **`tests/`** — Integration test crate
|
||||
- **`infra/`** — OpenTofu infrastructure (Cloudflare D1, Workers, Pages)
|
||||
- **`docs/`** — Project-level docs and design plans
|
||||
|
||||
Design reference: `docs/plans/2026-02-27-quotesdb-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Ticket Hierarchy
|
||||
|
||||
Tickets are organised as a dependency tree rooted at the project ticket:
|
||||
|
||||
```
|
||||
quotesdb (root project ticket, ec118c)
|
||||
├── quotesdb/api (sub-project ticket)
|
||||
│ ├── quotesdb/api/<ticket-id> (task/feature/bug tickets)
|
||||
│ └── ...
|
||||
├── quotesdb/ui
|
||||
│ └── ...
|
||||
├── quotesdb/qa
|
||||
│ └── ...
|
||||
└── quotesdb/infra
|
||||
└── ...
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Create a ticket **before** starting any non-trivial work.
|
||||
- Each work ticket must list its sub-project ticket as a dependency (`--deps <sub-project-id>`).
|
||||
- Each sub-project ticket must list the root project ticket (`ec118c`) as a dependency.
|
||||
- **Only close a ticket after its work has been validated** (all `cargo fmt/check/clippy/test` pass, or equivalent for infra).
|
||||
|
||||
---
|
||||
|
||||
## Branch & Worktree Workflow
|
||||
|
||||
All work happens in **git worktrees** on named branches.
|
||||
|
||||
### Branch naming
|
||||
|
||||
```
|
||||
quotesdb/<domain>/<ticket-id>
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `quotesdb/api/a1b2c3`
|
||||
- `quotesdb/ui/d4e5f6`
|
||||
- `quotesdb/qa/g7h8i9`
|
||||
- `quotesdb/infra/j0k1l2`
|
||||
|
||||
### Merge target
|
||||
|
||||
All completed work branches merge into the **`quotesdb`** branch (not `main`).
|
||||
|
||||
### Typical flow
|
||||
|
||||
```bash
|
||||
# Create worktree for a ticket
|
||||
git worktree add .claude/worktrees/quotesdb-api-<id> -b quotesdb/api/<id>
|
||||
|
||||
# ... do the work ...
|
||||
|
||||
# Validate before merging (from the relevant sub-directory)
|
||||
cargo fmt && cargo check && cargo clippy && cargo test
|
||||
|
||||
# Merge into quotesdb branch
|
||||
git checkout quotesdb
|
||||
git merge quotesdb/api/<id>
|
||||
|
||||
# Remove worktree
|
||||
git worktree remove .claude/worktrees/quotesdb-api-<id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Expert Sub-Agents
|
||||
|
||||
Dispatch all implementation work to a domain expert sub-agent. Match the domain to the agent:
|
||||
|
||||
| Domain | Agent role |
|
||||
|--------|-----------|
|
||||
| `api/` | Senior Rust backend engineer — expert in API design, Axum, workers-rs, SQLx, and unit testing |
|
||||
| `ui/` | Senior Rust frontend engineer — expert in Yew, Wasm, Trunk, and web design |
|
||||
| `tests/` | Senior QA engineer — expert in Rust integration testing and HTTP test harnesses |
|
||||
| `infra/` | DevOps/infrastructure engineer — expert in OpenTofu, Terraform, and Cloudflare |
|
||||
| Anything else | Software architect — expert in cloud services, Rust software patterns, and system design |
|
||||
|
||||
Each sub-agent should receive:
|
||||
1. The relevant section of `docs/plans/2026-02-27-quotesdb-design.md`
|
||||
2. The specific nbd ticket body
|
||||
3. The validation commands to run before closing the ticket
|
||||
4. The conventional commit scope to use (e.g., `feat(quotesdb-api): ...`)
|
||||
|
||||
---
|
||||
|
||||
## Design Reference
|
||||
|
||||
### Database Schema
|
||||
|
||||
```sql
|
||||
CREATE TABLE quotes (
|
||||
id TEXT PRIMARY KEY, -- NanoID (~21 chars)
|
||||
text TEXT NOT NULL,
|
||||
author TEXT NOT NULL,
|
||||
source TEXT, -- optional: book, speech, etc.
|
||||
date TEXT, -- optional: ISO date YYYY-MM-DD
|
||||
auth_code TEXT NOT NULL, -- 4-word passphrase e.g. ocean-table-purple-storm
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
|
||||
CREATE TABLE quote_tags (
|
||||
quote_id TEXT NOT NULL REFERENCES quotes(id) ON DELETE CASCADE,
|
||||
tag TEXT NOT NULL,
|
||||
PRIMARY KEY (quote_id, tag)
|
||||
);
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Method | Path | Description | Auth |
|
||||
|--------|------|-------------|------|
|
||||
| GET | `/api/` | OpenAPI spec (JSON) | None |
|
||||
| GET | `/api/quotes` | List quotes, 10/page. Query: `?page=N&author=X&tag=Y` | None |
|
||||
| GET | `/api/quotes/random` | Random quote | None |
|
||||
| GET | `/api/quotes/:id` | Get quote by NanoID | None |
|
||||
| PUT | `/api/quotes` | Create a quote | None (auth_code optional in body) |
|
||||
| POST | `/api/quotes/:id` | Update a quote | `X-Auth-Code` header |
|
||||
| DELETE | `/api/quotes/:id` | Delete a quote | `X-Auth-Code` header |
|
||||
|
||||
> **Router order:** `GET /api/quotes/random` must be registered **before** `GET /api/quotes/:id`.
|
||||
|
||||
### Auth
|
||||
|
||||
- No user accounts. Each quote has an `auth_code` (4-word passphrase), stored plaintext.
|
||||
- Provided via `X-Auth-Code` header for update/delete. On mismatch: `403 Forbidden`.
|
||||
- Auth code is always returned in the create response.
|
||||
|
||||
### Frontend Routes (Yew)
|
||||
|
||||
| Route | Page |
|
||||
|-------|------|
|
||||
| `/` | Home — random quote + "Browse all" link |
|
||||
| `/browse` | Paginated list with author/tag filter controls |
|
||||
| `/quotes/:id` | Single quote — view, edit (auth prompt), delete (auth prompt) |
|
||||
| `/author/:name` | All quotes by an author |
|
||||
| `/submit` | New quote submission form |
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
Run in order from the relevant sub-directory before closing any ticket:
|
||||
|
||||
```sh
|
||||
cargo fmt # 1. formatting
|
||||
cargo check # 2. syntax
|
||||
cargo clippy # 3. best practices
|
||||
cargo test # 4. correctness
|
||||
```
|
||||
|
||||
For infra tickets:
|
||||
```sh
|
||||
tofu validate
|
||||
tofu plan
|
||||
```
|
||||
Loading…
Reference in New Issue