You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
252 lines
7.3 KiB
Markdown
252 lines
7.3 KiB
Markdown
@../CLAUDE.md
|
|
|
|
# CLAUDE.md — quotesdb
|
|
|
|
<working-directory>
|
|
Run all commands from the relevant sub-directory within `quotesdb/` (e.g., `api/`, `ui/`, `infra/`) — not from the repository root or the `quotesdb/` root.
|
|
</working-directory>
|
|
|
|
<project-overview>
|
|
|
|
## Project Overview
|
|
|
|
`quotesdb` is a quotes web application in the vibed mono-repo. It is a **single Cargo crate** with two binaries and shared library code:
|
|
|
|
```
|
|
quotesdb/
|
|
├── Cargo.toml # single crate, default-run = "api"
|
|
├── src/
|
|
│ ├── lib.rs # shared types/utilities (compiles for host + wasm32)
|
|
│ └── bin/
|
|
│ ├── api/
|
|
│ │ └── main.rs # API server binary
|
|
│ └── ui/
|
|
│ └── main.rs # Yew frontend binary (compiled by Trunk)
|
|
├── tests/ # Cargo integration tests (cargo test runs these)
|
|
├── index.html # Trunk HTML entry
|
|
├── Trunk.toml # Trunk config
|
|
├── infra/ # OpenTofu infrastructure
|
|
└── docs/ # Planning, architecture, and design docs
|
|
└── plans/
|
|
└── 2026-02-27-quotesdb-design.md
|
|
```
|
|
|
|
Design reference: `docs/plans/2026-02-27-quotesdb-design.md`
|
|
|
|
</project-overview>
|
|
|
|
<ticket-hierarchy>
|
|
|
|
## nbd Ticket Tracking
|
|
|
|
**Always run `nbd` commands from the `quotesdb/` directory.** Tickets are scoped to the directory where `nbd init` was run. Running `nbd` from a parent directory will not find these tickets.
|
|
|
|
```sh
|
|
# Correct — from quotesdb/
|
|
nbd list --json
|
|
nbd read b38032 --json
|
|
nbd update b38032 --status done --json
|
|
|
|
# Wrong — from qdb/ or vibed/
|
|
cd quotesdb && nbd list --json # must be in quotesdb/
|
|
```
|
|
|
|
### Ticket Hierarchy
|
|
|
|
```
|
|
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.
|
|
- Work tickets are **dependencies of** their sub-project ticket — add them with `nbd update <sub-project-id> --deps "...existing...,<new-ticket-id>"`. Work tickets do **not** list the sub-project in their own `--deps`.
|
|
- Sub-project tickets are **dependencies of** the root project ticket (`ec118c`) — they do **not** list `ec118c` in their own `--deps`.
|
|
- The dependency flows upward: `work → sub-project → root`. Each level can only close after all tickets below it are done.
|
|
- **Only close a ticket after its work has been validated** (all `cargo fmt/check/clippy/test` pass, or equivalent for infra).
|
|
|
|
</ticket-hierarchy>
|
|
|
|
<branch-and-worktree-workflow>
|
|
|
|
## 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 inside quotesdb/ root ...
|
|
|
|
# Validate before merging (always from quotesdb/ root)
|
|
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>
|
|
```
|
|
|
|
</branch-and-worktree-workflow>
|
|
|
|
<domain-expert-agents>
|
|
|
|
## Domain Expert Sub-Agents
|
|
|
|
Dispatch all implementation work to a domain expert sub-agent. Match the domain to the agent:
|
|
|
|
| Domain | Path | Agent role |
|
|
|--------|------|-----------|
|
|
| API | `src/bin/api/` | Senior Rust backend engineer — expert in API design, Axum, workers-rs, SQLx, and unit testing |
|
|
| UI | `src/bin/ui/` | Senior Rust frontend engineer — expert in Yew, Wasm, Trunk, and web design |
|
|
| Shared | `src/lib.rs` | Software architect — must keep code compatible with both host and wasm32 targets |
|
|
| Infra | `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): ...`)
|
|
|
|
</domain-expert-agents>
|
|
|
|
<design-reference>
|
|
|
|
## Design Reference
|
|
|
|
<database-schema>
|
|
|
|
### 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)
|
|
);
|
|
```
|
|
|
|
</database-schema>
|
|
|
|
<api-endpoints>
|
|
|
|
### 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`.
|
|
|
|
</api-endpoints>
|
|
|
|
<auth>
|
|
|
|
### 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.
|
|
|
|
</auth>
|
|
|
|
<frontend-routes>
|
|
|
|
### 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 |
|
|
|
|
</frontend-routes>
|
|
|
|
</design-reference>
|
|
|
|
<api-specification>
|
|
|
|
## API Specification
|
|
|
|
The API spec lives at `api/openapi.yaml` (OpenAPI 3.1.0, YAML format).
|
|
|
|
- The spec is the source of truth for all endpoint contracts.
|
|
- Validate with Redocly CLI after any changes (from the `quotesdb/` directory):
|
|
|
|
```sh
|
|
redocly lint api/openapi.yaml
|
|
```
|
|
|
|
## Validation
|
|
|
|
Run in order from the **`quotesdb/` root** before closing any ticket:
|
|
|
|
```sh
|
|
cargo fmt # 1. formatting
|
|
cargo check # 2. syntax
|
|
cargo clippy # 3. best practices
|
|
cargo test # 4. correctness
|
|
```
|
|
|
|
For API spec changes:
|
|
```sh
|
|
redocly lint api/openapi.yaml
|
|
```
|
|
|
|
For infra changes, run from the `infra/` directory:
|
|
```sh
|
|
tofu validate
|
|
tofu plan
|
|
```
|
|
|
|
</api-specification>
|