From d95af4ed902d387dba2427ce0c4097b96aeb7089 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Sat, 14 Feb 2026 08:30:37 -0600 Subject: [PATCH] Optimize CLAUDE.md from 116 to 37 lines Remove boilerplate, directory tree listing, and discoverable architecture docs. Keep commands, key patterns, env vars, and important gotchas. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 128 ++++++++++-------------------------------------------- 1 file changed, 24 insertions(+), 104 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 542521c..72eaae6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,116 +1,36 @@ -# CLAUDE.md +# Major Domo Database API -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +FastAPI backend serving SBA fantasy league data. Peewee ORM with PostgreSQL. -## Project Overview +## Commands -This is the Database API component of the Major Domo system - a FastAPI backend serving data for a Strat-o-Matic Baseball Association (SBA) fantasy league. It provides REST endpoints for Discord bots and web frontends to access league data. +```bash +docker-compose up # Start PostgreSQL + API + Adminer +docker-compose up --build # Rebuild and start +docker-compose --profile sync up sync-prod # One-time production data sync +python migrations.py # Run migrations (SQL files in migrations/) +``` -## Development Commands - -### Local Development -- **Dev server location**: `10.10.0.42` -- **Start all services**: `docker-compose up` (PostgreSQL + API + Adminer) -- **Build and start**: `docker-compose up --build` (rebuilds image with latest changes) -- **Sync from production**: `docker-compose --profile sync up sync-prod` (one-time production data sync) -- **Database migrations**: `python migrations.py` (uses files in root directory) -- **Database admin interface**: Available at `http://10.10.0.42:8080` (Adminer) - -### Docker Deployment -- **Production deployment**: Uses same `docker-compose up` workflow -- **Production server access**: `ssh akamai` then `cd container-data/sba-database` -- **Manual build**: `docker build -f Dockerfile -t major-domo-database .` +- **Dev server**: `10.10.0.42` | **Adminer**: `http://10.10.0.42:8080` +- **Production**: `ssh akamai` → `cd container-data/sba-database` ## Architecture -### Application Structure -``` -app/ -├── main.py # FastAPI application setup, router registration -├── db_engine.py # Peewee ORM models, database configuration -├── dependencies.py # Authentication, error handling decorators -└── routers_v3/ # API endpoints organized by domain - ├── awards.py # League awards and recognition endpoints - ├── battingstats.py # Batting statistics (seasonal and career) - ├── current.py # Current season/week status and configuration - ├── custom_commands.py # Custom command creation and management - ├── decisions.py # Strat-o-Matic game decisions and choices - ├── divisions.py # League division information - ├── draftdata.py # Draft status and current pick tracking - ├── draftlist.py # Team draft priority lists and rankings - ├── draftpicks.py # Draft pick ownership and trading - ├── fieldingstats.py # Fielding statistics (seasonal and career) - ├── injuries.py # Player injury tracking and management - ├── keepers.py # Keeper selection and management - ├── managers.py # Team manager information and profiles - ├── pitchingstats.py # Pitching statistics (seasonal and career) - ├── players.py # Player information, rosters, and statistics - ├── results.py # Game results and outcomes - ├── sbaplayers.py # SBA player pool and eligibility - ├── schedules.py # Game scheduling and matchups - ├── standings.py # League standings and team records - ├── stratgame.py # Strat-o-Matic game data and simulation - ├── stratplay.py # Individual play-by-play data and analysis - ├── teams.py # Team data, rosters, and organization - ├── transactions.py # Player transactions (trades, waivers, etc.) - └── views.py # Database views and aggregated statistics -``` - -### Database Configuration -- **Database**: PostgreSQL via `PooledPostgresqlDatabase` (production and development) -- **ORM**: Peewee with model-based schema definition -- **Migrations**: SQL migration files in `migrations/` directory -- **Table Naming**: Peewee models must specify `Meta.table_name` to match PostgreSQL table names - -### Authentication & Error Handling -- **Authentication**: OAuth2 bearer token validation via `API_TOKEN` environment variable -- **Error Handling**: `@handle_db_errors` decorator provides comprehensive logging, rollback, and HTTP error responses +- **Routers**: Domain-based in `app/routers_v3/` under `/api/v3/` prefix +- **ORM**: Peewee — always specify `Meta.table_name` to match PostgreSQL naming +- **Auth**: OAuth2 bearer token via `API_TOKEN` env var +- **Error handling**: `@handle_db_errors` decorator (logging, rollback, HTTP errors) +- **POST models**: Use `Optional[int] = None` for `id` fields (DB auto-generates) - **Logging**: Rotating file handler (`/tmp/sba-database.log`, 8MB max, 5 backups) -### API Design Patterns -- **Routers**: Domain-based organization under `/api/v3/` prefix -- **Models**: Pydantic models for request/response validation -- **Database Access**: Direct Peewee ORM queries with automatic connection pooling -- **Response Format**: Consistent JSON with proper HTTP status codes -- **POST Requests**: Pydantic models for POST (create) endpoints should use `Optional[int] = None` for `id` fields since the database auto-generates IDs +## Environment Variables -### Environment Variables -**Required**: -- `API_TOKEN` - Authentication token for API access +**Required**: `API_TOKEN`, `POSTGRES_HOST`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` +**Optional**: `POSTGRES_PORT` (5432), `LOG_LEVEL` (WARNING), `PRIVATE_IN_SCHEMA` -**PostgreSQL Configuration** (required): -- `POSTGRES_HOST` - PostgreSQL server hostname (default: 10.10.0.42) -- `POSTGRES_DB` - Database name (default: sba_master) -- `POSTGRES_USER` - Database user (default: sba_admin) -- `POSTGRES_PASSWORD` - Database password -- `POSTGRES_PORT` - Database port (default: 5432) +## Important -**Optional**: -- `LOG_LEVEL` - INFO or WARNING (defaults to WARNING) -- `PRIVATE_IN_SCHEMA` - Include private endpoints in OpenAPI schema - -### Key Data Models -- **Current**: Season/week status, trade deadlines, playoff schedule -- **Player/Team**: Core entities with seasonal and career statistics -- **Statistics**: Separate models for batting, pitching, fielding (seasonal + career) -- **Draft System**: Draft picks, draft lists, keeper selections -- **Game Data**: Schedules, results, Strat-o-Matic play-by-play data -- **League Management**: Standings, transactions, injuries, decisions -- **Custom Commands**: User-created Discord bot commands with creator tracking and usage statistics -- **Help Commands**: Static help text for Discord bot commands - -### Testing & Quality -- **No formal test framework currently configured** -- **API Documentation**: Auto-generated OpenAPI/Swagger at `/api/docs` -- **Health Checks**: Built into Docker configuration -- **Database Integrity**: Transaction rollback on errors via decorator - -## Important Notes - -- All active development occurs in the `/app` directory -- Root directory files (`main.py`, `db_engine.py`, etc.) are legacy and not in use -- **PostgreSQL migration completed**: System now uses PostgreSQL exclusively (no SQLite fallback) -- Database migrations are SQL files in `migrations/` directory, applied manually via psql -- Authentication is required for all endpoints except documentation and public read endpoints -- **Peewee Models**: Always specify `Meta.table_name` to match PostgreSQL naming conventions -- **Custom Commands**: Fully functional with creator tracking, usage statistics, and Discord bot integration \ No newline at end of file +- All active code is in `/app` — root-level `main.py`, `db_engine.py` are legacy, not in use +- PostgreSQL only (no SQLite fallback) +- Migrations are SQL files in `migrations/`, applied manually via psql +- API docs auto-generated at `/api/docs`