# CC Dashboard — Project Entry Point

<!-- SCOPE: root | owner: agent | generated: 2026-04-29 -->

## What Is This Project

FastAPI + PostgreSQL personal productivity dashboard that ingests Claude Code session data (via a stop hook), aggregates it into daily stats, and displays KPIs, timeline, project breakdown, tool usage, and session activity through a single-page web UI with JWT authentication.

**Client:** Oliver Internal (Vadym Samoilenko — personal tooling)
**Server:** unknown
**URL:** unknown (base path `/cc-dashboard`)

---

## Quick Navigation

| Need | Go to |
|------|-------|
| FastAPI app entry point + routers | `src/main.py` |
| App config and env var schema | `src/config.py` |
| SQLAlchemy models (Project, Session, DailyStat) | `src/models/` |
| Pydantic response schemas | `src/schemas/` |
| Auth router (login, refresh, JWT) | `src/routers/auth.py` |
| Dashboard aggregation endpoints | `src/routers/dashboard.py` |
| Data ingest endpoint (session stop hook) | `src/routers/ingest.py` |
| Project management endpoints | `src/routers/projects.py` |
| API key management | `src/routers/keys.py` |
| Admin routes | `src/routers/admin.py` |
| Event endpoints | `src/routers/events.py` |
| Database init and session factory | `src/database.py` |
| SPA frontend (static HTML/JS/CSS) | `src/static/index.html` |
| Docker compose (app + postgres:16) | `docker-compose.yml` |
| Environment config template | `.env.example` |
| Python dependencies | `requirements.txt` |

---

## Dev Commands

| Action | Command |
|--------|---------|
| Start full stack (Docker) | `docker compose up -d` |
| Rebuild after code changes | `docker compose up -d --build` |
| Stop stack | `docker compose down` |
| View logs | `docker compose logs -f app` |
| Run migrations (Alembic) | `docker compose exec app alembic upgrade head` |
| Run locally without Docker | `uvicorn src.main:app --host 0.0.0.0 --port 8800 --reload` |
| Copy env | `cp .env.example .env` (fill `DB_PASSWORD`, `SECRET_KEY`) |

---

## Key Constraints

- **NO SSH to server** without explicit user instruction
- **`SECRET_KEY`** must be at least 32 random chars — never use the placeholder
- **`DB_PASSWORD`** must be changed from `change_me_strong_password` before deployment
- **JWT tokens**: access = 30 min, refresh = 7 days (configurable in `.env`)
- **Base path is `/cc-dashboard`** — all routes and SPA fallback are scoped to this prefix
- **Static files hot-reload** without rebuild: `src/static/` is bind-mounted in Docker
- **Overlap-union dedup**: session hours use interval union per day to prevent double-counting parallel sessions (see `_union_hours` in `dashboard.py`)
- **PostgreSQL 16 required** — uses `to_char` and `extract('dow')` PG-specific functions

<!-- END SCOPE: root -->