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