burntop.dev Development Guide

Comprehensive guidelines for AI coding agents working on burntop.dev - a gamified AI usage tracking platform for developers.

Project Architecture

Monorepo structure:

Issue Tracking with bd (beads)

Always use the bd system for task management:

```bash

bd onboard # Get started with the project

bd ready # Find available work

bd show <id> # View issue details

bd update <id> --status in_progress # Claim work

bd close <id> # Complete work

bd sync # Sync with git

```

Development Commands

Workspace-wide

Backend (FastAPI)

```bash

cd packages/backend

uv run uvicorn src.app.main:app --reload # Dev server

uv run ruff check src/ # Lint

uv run ruff format src/ # Format

uv run pytest tests/unit/test_file.py # Single file test

uv run alembic upgrade head # Run migrations

uv run alembic revision --autogenerate -m "description" # Create migration

```

Frontend (TanStack Start)

```bash

cd packages/frontend

npx vitest run path/to/file.test.ts # Single file test

bun run generate:api # Regenerate API client after backend changes

```

Database (Local Development)

```bash

docker compose -f docker-compose.db.yml up -d # Start PostgreSQL

cd packages/backend && uv run alembic upgrade head

docker compose -f docker-compose.db.yml down # Stop

```

Connection string: `postgresql://burntop:burntop_dev_password@localhost:5433/burntop`

Code Style Standards

TypeScript/React Guidelines

1. **Strict typing**: No `any`, no `@ts-ignore` without justification

2. **Explicit return types** on all exported functions

3. **Prefer `interface` for objects**, `type` for unions

4. **Use `import type`** for type-only imports

5. **React 19 patterns**: Hooks and functional components only

6. **No `console.log`** in production code

Import Order (TypeScript)

```typescript

// 1. React/framework

import { createFileRoute } from '@tanstack/react-router';

// 2. Third-party libraries

import { z } from 'zod';

// 3. Internal (@/)

import { db } from '@/lib/db';

// 4. Relative imports

import { StatsCard } from './stats-card';

// 5. Type imports

import type { User } from '@/types';

```

Python (Backend) Guidelines

1. **Python 3.12+** with type hints required

2. **Async SQLAlchemy 2.0** with `Mapped[]` type annotations

3. **Use `Decimal`** for financial calculations

4. **Use `datetime.UTC`** instead of deprecated `timezone.utc`

5. **3-layer architecture**: Router → Service → Repository (never skip layers)

Backend Architecture Pattern

```

packages/backend/src/app/{entity}/

├── models.py # SQLAlchemy ORM models

├── schemas.py # Pydantic schemas (validation)

├── repository.py # Data access layer

├── service.py # Business logic

├── router.py # FastAPI endpoints

└── dependencies.py # Dependency injection

```

Naming Conventions

Critical Architecture Rules

1. **Frontend is client-side only** - All database operations MUST go through FastAPI backend

2. **Route files MUST NOT import `@/lib/db` directly** - Use server functions instead

3. **CLI requires Bun runtime** - Uses `bun:sqlite` for local database

4. **Dark mode only** - Base: `--bg-base: #0A0A0A`, Accent: `--ember-500: #FF6B00`

5. **No production console.log statements**

6. **Regenerate API client after backend changes**: `cd packages/frontend && bun run generate:api`

Common Implementation Patterns

Frontend Component Pattern

```typescript

import { cn } from '@/lib/utils';

import { Card } from '@/components/ui/card';

export function StatsCard({ className }: { className?: string }) {

return (

<Card className={cn('bg-bg-elevated border-border-default', className)} />

);

}

```

API Integration Pattern

```typescript

import { useGetUserProfileApiV1UsersUsernameGet } from '@/api/users';

const { data, isLoading } = useGetUserProfileApiV1UsersUsernameGet({

username: 'johndoe'

});

```

Recommended Skills for Tasks

Backend Development

Frontend Development

UI/UX Work

Delegate styling, layout, and animations to the `frontend-ui-ux-engineer` agent for best results.

Session Completion Checklist

**MANDATORY workflow before ending any work session:**

1. **File issues for remaining work** - Create bd issues for any follow-up tasks

2. **Run quality gates** (if code changed):

- Run relevant tests

- Fix linting errors

- Verify builds pass

3. **Update issue status**:

- Close finished work with `bd close <id>`

- Update in-progress items

4. **PUSH TO REMOTE** (MANDATORY):

```bash

git pull --rebase

bd sync

git push

git status # MUST show "up to date with origin"

```

5. **Clean up** - Clear stashes, prune remote branches

6. **Verify** - Confirm all changes are committed AND pushed

7. **Hand off** - Provide context for next session

**CRITICAL**: Work is NOT complete until `git push` succeeds. NEVER stop before pushing - that leaves work stranded locally. If push fails, resolve conflicts and retry until it succeeds.

Testing Strategy

Single File Tests (Preferred)

```bash

Frontend

cd packages/frontend && npx vitest run path/to/file.test.ts

Backend

cd packages/backend && uv run pytest tests/unit/test_file.py

```

Run single file tests during development for fast feedback. Run full test suites before pushing.

Notes