# Run 1 — 14 Feb 2026

## Goal

Build a developer analytics dashboard that makes a VP of Engineering say "oh fuck what!" — then make developers feel the same way about their own behavior.

## Directory Structure

Two directories, separated by concern:

```
analysis-14022026/              ← PROJECT FILES (scripts, app, data)
├── docker-compose.yml          # Local Postgres container
├── scripts/                    # Analysis Python scripts
│   ├── setup_local_db.py       # Replicates prod → local Postgres
│   └── (analysis scripts created by agents)
├── output/                     # JSON data produced by analysis agent
└── dashboard/                  # Vite + React + Tailwind app
    ├── public/data/            # JSON copied here for the app
    └── src/                    # React components

docs/run1-14022026/             ← DOCUMENTATION (logs, state, changelog)
├── README.md                   # This file
├── run_agents.sh               # Orchestration script
├── state/
│   ├── AGENT_STATE.md          # Shared state between agents
│   ├── CHANGELOG.md            # Per-iteration documentation by each agent
│   └── REVIEW_FEEDBACK.md      # Reviewer feedback per iteration
└── logs/                       # Per-iteration logs for each agent
    ├── iter-1-analysis.log
    ├── iter-1-frontend.log
    └── iter-1-reviewer.log
```

## Architecture

### Local Data Replica

```
Prod PostgreSQL (Azure) → setup_local_db.py → Local Docker Postgres (port 15432)
```

- **Container**: `qctrace-local` (postgres:16-alpine)
- **DSN**: `postgresql://localdev:localdev@localhost:15432/qc_trace`
- **Env file**: `.local.env` (drop-in replacement for `.prod.env`)

### 3-Agent System

| Agent | Job | Reads | Writes to |
|-------|-----|-------|-----------|
| **Analysis** | Query DB, compute metrics, find insights | AGENT_STATE.md, CONTEXT.md, local DB | `analysis-14022026/scripts/`, `analysis-14022026/output/` |
| **Frontend** | Build Vite+React dashboard from JSON | AGENT_STATE.md, JSON files | `analysis-14022026/dashboard/` |
| **Reviewer** | Verify quality, score, give feedback | dashboard app, JSON files, AGENT_STATE.md | `docs/run1-14022026/state/` |

### Data Flow

```
Local Postgres
    ↓ (SQL queries via analysis scripts)
Analysis Agent → analysis-14022026/output/*.json
    ↓ (copied to dashboard/public/data/)
Frontend Agent → analysis-14022026/dashboard/ (Vite dev server on :5173)
    ↓
Reviewer Agent → docs/run1-14022026/state/ (feedback, changelog, verdict)
    ↓
(loops back with updated AGENT_STATE.md)
```

## How to Run

```bash
# 1. Start local Postgres
docker compose -f analysis-14022026/docker-compose.yml up -d

# 2. Load prod data (one-time)
.venv/bin/python analysis-14022026/scripts/setup_local_db.py

# 3. Run the agents
./docs/run1-14022026/run_agents.sh 100

# Watch logs in real time (separate terminals)
tail -f docs/run1-14022026/logs/iter-*-analysis.log
tail -f docs/run1-14022026/logs/iter-*-frontend.log
tail -f docs/run1-14022026/logs/iter-*-reviewer.log

# Dashboard always live at
open http://localhost:5173
```

## Data Snapshot

| Table | Rows |
|-------|------|
| sessions | 877 |
| messages | 175,563 |
| token_usage | 39,142 |
| tool_calls | 40,420 |
| tool_results | 41,224 |
