# malasadongegg/trackhour architecture

> Architecture diagram of the GitHub repository malasadongegg/trackhour, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/malasadongegg/trackhour
- Repository: https://github.com/malasadongegg/trackhour

## Overview

TrackHour imports AI-chat exports locally, estimates usage sessions, and presents statistics or downloadable SVG cards. Optional account features save aggregate data for hosted cards; the browser extension and Claude Code hook provide additional measured-session inputs. The principal flow is documented in the README and partly visible in App.tsx; several component and endpoint relationships are documented but their implementation was not sampled.

Main entry points: [`web/src/App.tsx`](https://github.com/malasadongegg/trackhour/blob/main/web/src/App.tsx) (App workflow), [`card/src/handler.ts`](https://github.com/malasadongegg/trackhour/blob/main/card/src/handler.ts) (Card request handler), [`web/src/pages/AccountPage.tsx`](https://github.com/malasadongegg/trackhour/blob/main/web/src/pages/AccountPage.tsx) (Account page), [`web/src/components/card/CardControls.tsx`](https://github.com/malasadongegg/trackhour/blob/main/web/src/components/card/CardControls.tsx) (Card designer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_app["App workflow<br/>[App.tsx]"]
  node_zip["Export intake<br/>[Dropzone.tsx]"]
  node_preview["Import preview<br/>[ImportPreview.tsx]"]
  node_db["Browser library<br/>[db.ts]"]
  node_browserdb[("IndexedDB")]
  node_dashboard["Dashboard views<br/>[Heatmap.tsx]"]
  node_account["Account page<br/>[AccountPage.tsx]"]
  node_auth["Authentication<br/>[useAuth.ts]"]
  node_carddesigner["Card designer<br/>[CardControls.tsx]"]
  node_cardpreview["Card preview<br/>[CardPreview.tsx]"]
end

subgraph group_core["Usage core"]
  node_parsers["Export parsers"]
  node_importing["Import reconciliation<br/>[importing.ts]"]
  node_sessions["Session estimation<br/>[sessionize.ts]"]
  node_stats["Usage statistics<br/>[stats.ts]"]
  node_dates["Date utilities<br/>[dates.ts]"]
  node_heat["Heatmap intensity<br/>[heat.ts]"]
  node_renderer["SVG renderer<br/>[render.ts]"]
end

subgraph group_hosted["Hosted cards"]
  node_hostedapi["Card API adapter<br/>[card.ts]"]
  node_handler["Card request handler<br/>[handler.ts]"]
  node_ratelimit["Rate limiter<br/>[ratelimit.ts]"]
  node_profile["Profile store<br/>[supabase.ts]"]
end

subgraph group_capture["Measured capture"]
  node_extension["Browser tracker<br/>[content-tracker.js]"]
  node_extensionworker["Extension worker<br/>[background.js]"]
  node_extensionstate["Session tracking<br/>[sessions.js]"]
  node_hook["Claude Code hook<br/>[hook.mjs]"]
end

node_person(("Visitor"))
node_supabase[("Supabase")]

node_person -->|"selects export"| node_zip
node_zip -->|"submits file"| node_app
node_app -->|"parses locally"| node_parsers
node_app -->|"shows preview"| node_preview
node_app -->|"reconciles records"| node_importing
node_app -->|"loads and saves"| node_db
node_db -->|"persists locally"| node_browserdb
node_app -->|"derives sessions"| node_sessions
node_app -->|"derives statistics"| node_stats
node_app -->|"renders dashboard"| node_dashboard
node_stats -->|"uses date helpers"| node_dates
node_dashboard -.->|"uses intensity"| node_heat
node_person -->|"configures card"| node_carddesigner
node_app -->|"hosts designer"| node_carddesigner
node_carddesigner -->|"updates preview"| node_cardpreview
node_cardpreview -->|"renders SVG"| node_renderer
node_person -->|"opens account"| node_account
node_account -->|"uses authentication"| node_auth
node_auth -->|"authenticates"| node_supabase
node_account -->|"saves aggregates"| node_supabase
node_person -->|"requests hosted card"| node_hostedapi
node_hostedapi -->|"adapts request"| node_handler
node_handler -->|"checks limits"| node_ratelimit
node_handler -->|"loads public profile"| node_profile
node_handler -->|"renders card"| node_renderer
node_extension -.->|"reports activity"| node_extensionworker
node_extensionworker -->|"records beats"| node_extensionstate
node_extension -->|"imports session log"| node_app
node_hook -.->|"imports session log"| node_app

click node_app "https://github.com/malasadongegg/trackhour/blob/main/web/src/App.tsx"
click node_zip "https://github.com/malasadongegg/trackhour/blob/main/web/src/components/Dropzone.tsx"
click node_preview "https://github.com/malasadongegg/trackhour/blob/main/web/src/components/ImportPreview.tsx"
click node_db "https://github.com/malasadongegg/trackhour/blob/main/web/src/lib/db.ts"
click node_dashboard "https://github.com/malasadongegg/trackhour/blob/main/web/src/components/Heatmap.tsx"
click node_account "https://github.com/malasadongegg/trackhour/blob/main/web/src/pages/AccountPage.tsx"
click node_auth "https://github.com/malasadongegg/trackhour/blob/main/web/src/lib/useAuth.ts"
click node_parsers "https://github.com/malasadongegg/trackhour/tree/main/core/src/parse"
click node_importing "https://github.com/malasadongegg/trackhour/blob/main/core/src/importing.ts"
click node_sessions "https://github.com/malasadongegg/trackhour/blob/main/core/src/sessionize.ts"
click node_stats "https://github.com/malasadongegg/trackhour/blob/main/core/src/stats.ts"
click node_dates "https://github.com/malasadongegg/trackhour/blob/main/core/src/dates.ts"
click node_heat "https://github.com/malasadongegg/trackhour/blob/main/core/src/heat.ts"
click node_carddesigner "https://github.com/malasadongegg/trackhour/blob/main/web/src/components/card/CardControls.tsx"
click node_cardpreview "https://github.com/malasadongegg/trackhour/blob/main/web/src/components/card/CardPreview.tsx"
click node_renderer "https://github.com/malasadongegg/trackhour/blob/main/core/src/card/render.ts"
click node_hostedapi "https://github.com/malasadongegg/trackhour/blob/main/web/api/card.ts"
click node_handler "https://github.com/malasadongegg/trackhour/blob/main/card/src/handler.ts"
click node_ratelimit "https://github.com/malasadongegg/trackhour/blob/main/card/src/ratelimit.ts"
click node_profile "https://github.com/malasadongegg/trackhour/blob/main/card/src/supabase.ts"
click node_extension "https://github.com/malasadongegg/trackhour/blob/main/extension/src/content-tracker.js"
click node_extensionworker "https://github.com/malasadongegg/trackhour/blob/main/extension/src/background.js"
click node_extensionstate "https://github.com/malasadongegg/trackhour/blob/main/extension/src/sessions.js"
click node_hook "https://github.com/malasadongegg/trackhour/blob/main/claude-code-hook/hook.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_zip,node_preview,node_db,node_browserdb,node_dashboard,node_account,node_auth,node_carddesigner,node_cardpreview toneBlue
class node_parsers,node_importing,node_sessions,node_stats,node_dates,node_heat,node_renderer,node_supabase toneAmber
class node_hostedapi,node_handler,node_ratelimit,node_profile toneMint
class node_extension,node_extensionworker,node_extensionstate,node_hook toneRose
class node_person toneIndigo
```

## Components

### Web app

- [App workflow](https://github.com/malasadongegg/trackhour/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Export intake](https://github.com/malasadongegg/trackhour/blob/main/web/src/components/Dropzone.tsx): `web/src/components/Dropzone.tsx`
- [Import preview](https://github.com/malasadongegg/trackhour/blob/main/web/src/components/ImportPreview.tsx): `web/src/components/ImportPreview.tsx`
- [Browser library](https://github.com/malasadongegg/trackhour/blob/main/web/src/lib/db.ts): `web/src/lib/db.ts`
- **IndexedDB**
- [Dashboard views](https://github.com/malasadongegg/trackhour/blob/main/web/src/components/Heatmap.tsx): `web/src/components/Heatmap.tsx`
- [Account page](https://github.com/malasadongegg/trackhour/blob/main/web/src/pages/AccountPage.tsx): `web/src/pages/AccountPage.tsx`
- [Authentication](https://github.com/malasadongegg/trackhour/blob/main/web/src/lib/useAuth.ts): `web/src/lib/useAuth.ts`
- [Card designer](https://github.com/malasadongegg/trackhour/blob/main/web/src/components/card/CardControls.tsx): `web/src/components/card/CardControls.tsx`
- [Card preview](https://github.com/malasadongegg/trackhour/blob/main/web/src/components/card/CardPreview.tsx): `web/src/components/card/CardPreview.tsx`

### Usage core

- [Export parsers](https://github.com/malasadongegg/trackhour/tree/main/core/src/parse): `core/src/parse`
- [Import reconciliation](https://github.com/malasadongegg/trackhour/blob/main/core/src/importing.ts): `core/src/importing.ts`
- [Session estimation](https://github.com/malasadongegg/trackhour/blob/main/core/src/sessionize.ts): `core/src/sessionize.ts`
- [Usage statistics](https://github.com/malasadongegg/trackhour/blob/main/core/src/stats.ts): `core/src/stats.ts`
- [Date utilities](https://github.com/malasadongegg/trackhour/blob/main/core/src/dates.ts): `core/src/dates.ts`
- [Heatmap intensity](https://github.com/malasadongegg/trackhour/blob/main/core/src/heat.ts): `core/src/heat.ts`
- [SVG renderer](https://github.com/malasadongegg/trackhour/blob/main/core/src/card/render.ts): `core/src/card/render.ts`

### Hosted cards

- [Card API adapter](https://github.com/malasadongegg/trackhour/blob/main/web/api/card.ts): `web/api/card.ts`
- [Card request handler](https://github.com/malasadongegg/trackhour/blob/main/card/src/handler.ts): `card/src/handler.ts`
- [Rate limiter](https://github.com/malasadongegg/trackhour/blob/main/card/src/ratelimit.ts): `card/src/ratelimit.ts`
- [Profile store](https://github.com/malasadongegg/trackhour/blob/main/card/src/supabase.ts): `card/src/supabase.ts`

### Measured capture

- [Browser tracker](https://github.com/malasadongegg/trackhour/blob/main/extension/src/content-tracker.js): `extension/src/content-tracker.js`
- [Extension worker](https://github.com/malasadongegg/trackhour/blob/main/extension/src/background.js): `extension/src/background.js`
- [Session tracking](https://github.com/malasadongegg/trackhour/blob/main/extension/src/sessions.js): `extension/src/sessions.js`
- [Claude Code hook](https://github.com/malasadongegg/trackhour/blob/main/claude-code-hook/hook.mjs): `claude-code-hook/hook.mjs`

### Other components

- **Visitor**
- **Supabase**

## Connections

- Visitor → Export intake: selects export (evidence: `README.md`)
- Export intake → App workflow: submits file (evidence: `README.md`)
- App workflow → Export parsers: parses locally (evidence: `README.md`)
- App workflow → Import preview: shows preview (evidence: `README.md`)
- App workflow → Import reconciliation: reconciles records (evidence: `README.md`)
- App workflow → Browser library: loads and saves (evidence: `web/src/App.tsx`)
- Browser library → IndexedDB: persists locally (evidence: `README.md`)
- App workflow → Session estimation: derives sessions (evidence: `README.md`)
- App workflow → Usage statistics: derives statistics (evidence: `README.md`)
- App workflow → Dashboard views: renders dashboard (evidence: `web/src/App.tsx`)
- Usage statistics → Date utilities: uses date helpers (evidence: `core/src/stats.ts`)
- Dashboard views → Heatmap intensity: uses intensity
- Visitor → Card designer: configures card (evidence: `README.md`)
- App workflow → Card designer: hosts designer (evidence: `web/src/App.tsx`)
- Card designer → Card preview: updates preview (evidence: `README.md`)
- Card preview → SVG renderer: renders SVG (evidence: `README.md`)
- Visitor → Account page: opens account (evidence: `README.md`)
- Account page → Authentication: uses authentication (evidence: `web/src/pages/AccountPage.tsx`)
- Authentication → Supabase: authenticates (evidence: `web/src/lib/useAuth.ts`)
- Account page → Supabase: saves aggregates (evidence: `README.md`)
- Visitor → Card API adapter: requests hosted card (evidence: `README.md`)
- Card API adapter → Card request handler: adapts request (evidence: `README.md`)
- Card request handler → Rate limiter: checks limits (evidence: `card/src/handler.ts`)
- Card request handler → Profile store: loads public profile (evidence: `card/src/handler.ts`)
- Card request handler → SVG renderer: renders card (evidence: `card/src/handler.ts`)
- Browser tracker → Extension worker: reports activity
- Extension worker → Session tracking: records beats (evidence: `extension/src/background.js`)
- Browser tracker → App workflow: imports session log (evidence: `web/src/App.tsx`)
- Claude Code hook → App workflow: imports session log
