From 4371a0d6e68ae92ff37feb38e8b674e74cfb2eea Mon Sep 17 00:00:00 2001 From: David Kiania Date: Sun, 19 Apr 2026 00:27:59 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20CLAUDE.md=20audit=20=E2=80=94=20add=20c?= =?UTF-8?q?ommands=20section,=20fix=20stale=20DB=20access=20note?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add §0 Commands (uv, pytest, ruff, mypy, docker exec query pattern). Fix §3 DB access: DATABASE_URL is internal-only since fix 152fce8. Add docs/superpowers/ to codebase map. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index bae46ed..7cbd487 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,29 @@ # CLAUDE.md — Fireside Communications · Tracksolid Fleet Intelligence +## 0. Commands + +**Package manager:** `uv` (not pip/poetry) + +```bash +uv sync # Install / sync dependencies +pytest tests/ # Run test suite +ruff check . # Lint +mypy . # Type check +``` + +**Run a query via Docker (DATABASE_URL is internal-only):** +```bash +DB=$(docker ps --filter name=timescale_db --format "{{.Names}}" | head -1) +docker exec $DB psql -U postgres -d tracksolid_db -c "SELECT COUNT(*) FROM tracksolid.devices;" +``` + +**Run a migration file:** +```bash +docker exec -i $DB psql -U postgres -d tracksolid_db < 07_your_migration.sql +``` + +--- + ## 1. What This Project Is Fleet telematics ingestion and analytics stack for a **telco first-line support client** operating in Nairobi, Mombasa, and Kampala. The client dispatches field technicians to install, repair, and maintain home and business broadband, handle LOS signal faults, service migrations, and maintain outside plant infrastructure. The fleet is ~80 vehicles across three cities, all tracked via Tracksolid Pro (Jimi IoT API). @@ -33,7 +57,7 @@ See `docs/CONNECTIONS.md` for the full shape. Summary: - **DB name:** `tracksolid_db` · **DB user:** `postgres` (internal) · `tracksolid_owner` (app) · `grafana_ro` (read-only) - **DB schema:** `tracksolid_2` (current live data, legacy stack) · `tracksolid` (new stack target, currently empty) · `infrastructure` · `dwh_gold` (aggregates) - **⚠ Schema split:** new ingestion code targets `tracksolid`; all live rows are in `tracksolid_2` until the new stack is deployed and `sync_driver_audit.py` has run. -- **DB direct access:** `DATABASE_URL` in `.env` points to `31.97.44.246:5888` — queries can be run locally via psql without SSH. Note: value has a leading space, strip it. +- **DB access:** `DATABASE_URL` points to `timescale_db:5432` (internal Docker network — not reachable locally). Use `docker exec` pattern above. See `docs/CONNECTIONS.md` for full reference. - **Container naming:** Coolify appends a random suffix. Always resolve with: ```bash docker ps --filter name= --format "{{.Names}}" | head -1 @@ -58,6 +82,7 @@ docker-compose.yaml # Services: timescale_db, ingest_movement, ingest_ev grafana/ # Grafana provisioning (baked into image) n8n-workflows/ # n8n workflow exports docs/ # Reference docs (connections, API, KPIs, project context) +docs/superpowers/ # Pitch specs and implementation plans (not deployed code) 02_tracksolid_full_schema_rev.sql # Full schema bootstrap 03..06_*.sql # Incremental migrations (06 adds assigned_city, dispatch_log, ops.*) 01_BusinessAnalytics.md # SQL analytics library — read before writing queries