From bcdde572e81610564221f9cb7e23d492bb56d82d Mon Sep 17 00:00:00 2001
From: Cal Corum <calcorum@users.noreply.github.com>
Date: Tue, 17 Feb 2026 15:22:33 -0600
Subject: [PATCH] docs: Add subdirectory CLAUDE.md files for routers,
 stratplay, and services

Provide targeted context for each app subdirectory so Claude Code
understands local patterns without relying on the root CLAUDE.md.
Also simplifies root CLAUDE.md dev/prod environment sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 app/routers_v3/CLAUDE.md           | 26 ++++++++++++++++++++++++++
 app/routers_v3/stratplay/CLAUDE.md | 24 ++++++++++++++++++++++++
 app/services/CLAUDE.md             | 17 +++++++++++++++++
 3 files changed, 67 insertions(+)
 create mode 100644 app/routers_v3/CLAUDE.md
 create mode 100644 app/routers_v3/stratplay/CLAUDE.md
 create mode 100644 app/services/CLAUDE.md

diff --git a/app/routers_v3/CLAUDE.md b/app/routers_v3/CLAUDE.md
new file mode 100644
index 0000000..be2e36e
--- /dev/null
+++ b/app/routers_v3/CLAUDE.md
@@ -0,0 +1,26 @@
+# Routers (v3)
+
+Domain-based FastAPI routers under `/api/v3/` prefix. Each file = one resource.
+
+## Patterns
+
+- Every endpoint uses `@handle_db_errors` decorator (from `dependencies.py`)
+- GET endpoints use `@cache_result(ttl=N, key_prefix="name")` for Redis caching
+- Auth: `token: str = Depends(oauth2_scheme)` + `valid_token(token)` check on mutating endpoints
+- Pydantic models for POST/PATCH bodies are defined inline in router files (not db_engine)
+- POST models: `id` fields must be `Optional[int] = None` (DB auto-generates)
+
+## Two Styles Coexist
+
+- **Refactored** (players, teams): Thin HTTP layer → delegates to `services/` layer
+- **Legacy** (most others): Business logic directly in router, imports models from `db_engine`
+
+## Adding a New Router
+
+1. Create `app/routers_v3/newrouter.py` with `router = APIRouter(prefix="/api/v3/name", tags=["name"])`
+2. Import and register in `app/main.py`: `from .routers_v3 import newrouter` + `app.include_router(newrouter.router)`
+
+## IMPORTANT
+
+- PATCH endpoints: build update dict explicitly from parameters. Never use `locals()`.
+- `stratplay/` is a sub-package with its own `__init__.py` and sub-routers (batting, pitching, fielding, plays, crud)
diff --git a/app/routers_v3/stratplay/CLAUDE.md b/app/routers_v3/stratplay/CLAUDE.md
new file mode 100644
index 0000000..e5bad1c
--- /dev/null
+++ b/app/routers_v3/stratplay/CLAUDE.md
@@ -0,0 +1,24 @@
+# Stratplay Router (sub-package)
+
+Play-by-play data for Strat-o-Matic games. Mounted at `/api/v3/plays`.
+
+## Structure
+
+| File | Purpose |
+|------|---------|
+| `__init__.py` | Assembles sub-routers into parent `router` |
+| `common.py` | Shared `build_season_games()` filter builder |
+| `models.py` | Pydantic models (`PlayModel`, `POS_LIST` literal) |
+| `plays.py` | General play queries |
+| `batting.py` | Batting stats aggregated from plays |
+| `pitching.py` | Pitching stats aggregated from plays |
+| `fielding.py` | Fielding stats aggregated from plays |
+| `crud.py` | POST/PATCH/DELETE operations (auth required) |
+
+## Key Patterns
+
+- All stat endpoints use `build_season_games()` from `common.py` for consistent filtering
+- Filter params: `season`, `week`, `s_type` (regular/post), `week_start`/`week_end`, `manager_id`
+- `week` and `s_type` are mutually exclusive; `week` and `week_start`/`week_end` are mutually exclusive
+- Stats aggregate from `StratPlay` joined to `StratGame` via `game_id`
+- CRUD writes trigger `update_season_batting_stats()` / `update_season_pitching_stats()` from `dependencies.py`
diff --git a/app/services/CLAUDE.md b/app/services/CLAUDE.md
new file mode 100644
index 0000000..256a4d1
--- /dev/null
+++ b/app/services/CLAUDE.md
@@ -0,0 +1,17 @@
+# Services Layer
+
+Business logic extracted from routers for testability. Uses dependency injection.
+
+## Architecture
+
+- `interfaces.py` — Protocol classes (`AbstractPlayerRepository`, `AbstractTeamRepository`, `AbstractCacheService`)
+- `base.py` — `BaseService` with lazy-loaded default repos (imports from `db_engine` on first access)
+- `mocks.py` — Mock implementations for testing without DB/Redis
+- `player_service.py`, `team_service.py` — Domain services (class methods, no instance needed for reads)
+
+## Key Patterns
+
+- Services use `@staticmethod`/`@classmethod` for read operations (no instantiation needed)
+- Default repos are created lazily inside `@property` methods to avoid circular imports with `db_engine`
+- For testing: pass mock repos via `ServiceConfig` or constructor kwargs
+- Only `players` and `teams` routers currently use the service layer; others call `db_engine` directly