111 lines
4.6 KiB
Markdown
111 lines
4.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
GearBox is a single-user web app for managing gear collections (bikepacking, sim racing, etc.), tracking weight/price, and planning purchases through research threads. Full-stack TypeScript monolith running on Bun.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Development
|
|
bun run dev # Starts both Vite client (:5173) and Hono server (:3000) concurrently
|
|
bun run dev:client # Vite dev server on :5173 (proxies /api to :3000)
|
|
bun run dev:server # Hono server on :3000 with hot reload
|
|
|
|
# Database
|
|
bun run db:generate # Generate Drizzle migration from schema changes
|
|
bun run db:push # Apply migrations to gearbox.db
|
|
|
|
# Testing
|
|
bun test # Run all tests
|
|
bun test tests/services/item.service.test.ts # Run single test file
|
|
|
|
# Lint & Format
|
|
bun run lint # Biome check (tabs, double quotes, organized imports)
|
|
|
|
# Build
|
|
bun run build # Vite build → dist/client/
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**Stack**: React 19 + Hono + Drizzle ORM + SQLite, all running on Bun.
|
|
|
|
### Client (`src/client/`)
|
|
- **Routing**: TanStack Router with file-based routes in `src/client/routes/`. Route tree auto-generated to `routeTree.gen.ts` — never edit manually.
|
|
- **Data fetching**: TanStack React Query via custom hooks in `src/client/hooks/` (e.g., `useItems`, `useThreads`, `useSetups`). Mutations invalidate related query keys.
|
|
- **UI state**: Zustand store (`stores/uiStore.ts`) for panel/dialog state only — server data lives in React Query.
|
|
- **API calls**: Thin fetch wrapper in `lib/api.ts` (`apiGet`, `apiPost`, `apiPut`, `apiDelete`, `apiUpload`).
|
|
- **Styling**: Tailwind CSS v4.
|
|
|
|
### Server (`src/server/`)
|
|
- **Routes** (`routes/`): Hono handlers with Zod validation via `@hono/zod-validator`. Delegate to services.
|
|
- **Services** (`services/`): Pure business logic functions that take a db instance. No HTTP awareness — testable without mocking.
|
|
- Route registration in `src/server/index.ts` via `app.route("/api/...", routes)`.
|
|
|
|
### Shared (`src/shared/`)
|
|
- **`schemas.ts`**: Zod schemas for API request validation (source of truth for types).
|
|
- **`types.ts`**: Types inferred from Zod schemas + Drizzle table definitions. No manual type duplication.
|
|
|
|
### Database (`src/db/`)
|
|
- **Schema**: `schema.ts` — Drizzle table definitions for SQLite.
|
|
- **Prices stored as cents** (`priceCents: integer`) to avoid float rounding.
|
|
- **Timestamps**: stored as integers (unix epoch) with `{ mode: "timestamp" }`.
|
|
- Tables: `categories`, `items`, `threads`, `threadCandidates`, `setups`, `setupItems`, `settings`.
|
|
|
|
### Testing (`tests/`)
|
|
- Bun test runner. Tests at service level and route level.
|
|
- `tests/helpers/db.ts`: `createTestDb()` creates in-memory SQLite with full schema and seeds an "Uncategorized" category. When adding schema columns, update both `src/db/schema.ts` and the test helper's CREATE TABLE statements.
|
|
|
|
## Path Alias
|
|
|
|
`@/*` maps to `./src/*` (configured in tsconfig.json).
|
|
|
|
## Key Patterns
|
|
|
|
- **Thread resolution**: Resolving a thread copies the winning candidate's data into a new item in the collection, sets `resolvedCandidateId`, and changes status to "resolved".
|
|
- **Setup item sync**: `PUT /api/setups/:id/items` replaces all setup_items atomically (delete all, re-insert).
|
|
- **Image uploads**: `POST /api/images` saves to `./uploads/` with UUID filename, returned as `imageFilename` on item/candidate records.
|
|
- **Image URL fetching**: `POST /api/images/from-url` fetches an image from a URL, saves locally, returns `{ filename, sourceUrl }`.
|
|
- **Aggregates** (weight/cost totals): Computed via SQL on read, not stored on records.
|
|
- **Authentication**: Public-read, authenticated-write. Cookie sessions for web UI, API keys for programmatic access. `POST /api/auth/setup` for first-time account creation.
|
|
|
|
## MCP Server
|
|
|
|
GearBox includes a built-in MCP server for integration with Claude Code and Claude Desktop. Enabled by default, disable with `GEARBOX_MCP=false`.
|
|
|
|
### Configuration
|
|
|
|
**Claude Code** (`.claude/settings.json`):
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"gearbox": {
|
|
"type": "streamable-http",
|
|
"url": "http://localhost:3000/mcp",
|
|
"headers": {
|
|
"X-API-Key": "<your-api-key>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Claude Desktop** (`claude_desktop_config.json`):
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"gearbox": {
|
|
"type": "streamable-http",
|
|
"url": "http://localhost:3000/mcp",
|
|
"headers": {
|
|
"X-API-Key": "<your-api-key>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Generate an API key from Settings > API Keys after logging in. |