token-analytics/ARCHITECTURE.md

Architecture

Stack

• Backend: ASP.NET (.NET 10), Minimal API
• Frontend: Vanilla HTML/CSS/JS (SPA, kein Framework)
• Datenbank: SQLite via Dapper (read) + better-sqlite3 (import)
• Port: 18684

Komponenten

Backend (Program.cs)

Minimal API mit Endpunkten für Kosten-Analyse:

• GET /api/cost-buckets - Zeitraum in N Buckets aggregiert
• GET /api/cost-entries - Einzelne Einträge mit Kosten
• GET /api/cost-chains - Konversations-Ketten nach Kosten sortiert
• GET /api/cost-summary - Gesamtkosten für Zeitraum
• GET /api/entry-chain/{id} - Volle Kette eines Eintrags (parentId vor/zurück)
• GET /api/entry-chains - Einträge mit chainId-Zuordnung
• GET /api/config - Dashboard-Konfiguration lesen
• PUT /api/config - Dashboard-Konfiguration speichern
• POST /api/sync - Triggert JSONL-Import via export.mjs

DB-Zugriff über Dapper + Microsoft.Data.Sqlite. Connection per Request via Factory.

Beim Start wird ein Index auf json_extract(data, '$.parentId') erstellt für schnelle Vorwärts-Ketten-Auflösung.

Konfiguration

Server-seitige Config als dashboard-config.json neben der DB. Einstellungen:

• weeklyBudget - Wochen-Budget in Dollar (Default: 500)
• anchorDay - Budget-Anker Wochentag (0=So, 6=Sa)
• anchorHour - Anker-Stunde (0-23)
• minBarWidth - Minimale Balkenbreite in Pixel (Default: 12)

JSONL Sync (jsonl-sync/export.mjs)

Node.js Script das OpenClaw Session-JSONL-Files in SQLite importiert:

1. Liest alle .jsonl aus dem Sessions-Verzeichnis
2. Parsed Einträge, speichert in entries Tabelle via INSERT OR IGNORE
3. Berechnet chainId durch parentId-Walk bis zum nächsten User-Message
4. Full-Scan bei jedem Lauf - robust gegen Session-Kompaktierung durch OpenClaw

Frontend (wwwroot/)

SPA mit Zoom-Navigation durch Zeiträume:

• Bucket-View: Balkendiagramm mit klickbarem Drill-Down (Monat → Woche → Tag)
• Entry-View: Einzelne API-Calls als Balken, farblich nach Konversations-Kette
• Chain-Blocks: Teuerste Konversationen als klickbare Blöcke
• Ketten-Modal: Konversations-Kontext mit User/Assistant Messages + Kosten
• Config-Modal: Budget, Anker, Balkenbreite - serverseitig gespeichert
• Dynamische Balkenanzahl: Viewport-Breite / minBarWidth, gerundet auf Vielfache von 28
• Automatisches Re-Render bei Resize
• State wird im URL-Hash gespeichert

Datenfluss

OpenClaw JSONL Files → export.mjs → SQLite (sessions.db) → .NET API → Frontend

Deployment

./deploy.sh

Baut Release, kopiert nach publish/, restartet den token-analytics systemd Service auf stein2.