# mirkp/jarful architecture

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

- Interactive diagram: https://gitdiagram.com/mirkp/jarful
- Repository: https://github.com/mirkp/jarful

## Overview

Jarful is a personal time-tracking app: a user starts or switches an activity timer, optionally tags it with a sub-category, and reviews time in daily history and weekly summaries. Separate workflows track sleep and create period-based goals visualized as filling vessels. The tracker context coordinates optimistic updates and loads data through a store interface, backed by either browser demo data or Supabase. The README and source index support the main routes and integrations; several UI-to-provider and storage details are documented rather than fully excerpted.

Main entry points: [`src/lib/tracker-context.tsx`](https://github.com/mirkp/jarful/blob/main/src/lib/tracker-context.tsx) (Tracker context), [`src/app/(app)/page.tsx`](https://github.com/mirkp/jarful/blob/main/src/app/(app)/page.tsx) (Today tracking), [`src/app/(app)/goals/page.tsx`](https://github.com/mirkp/jarful/blob/main/src/app/(app)/goals/page.tsx) (Goal management), [`src/app/(app)/sleep/page.tsx`](https://github.com/mirkp/jarful/blob/main/src/app/(app)/sleep/page.tsx) (Sleep tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and navigation"]
  node_login["Login<br/>[page.tsx]"]
  node_appnav["App shell<br/>[layout.tsx]"]
  node_settings["Settings<br/>[page.tsx]"]
end

subgraph group_tracking["Time and sleep tracking"]
  node_today["Today tracking<br/>[page.tsx]"]
  node_activityform["Activity editor<br/>[ActivityForm.tsx]"]
  node_entryform["Manual entries<br/>[TimeEntryForm.tsx]"]
  node_history["Entry history<br/>[EntryHistory.tsx]"]
  node_timer["Active timer<br/>[ActiveTimer.tsx]"]
  node_sleep["Sleep tracking<br/>[page.tsx]"]
  node_sleepform["Sleep editor<br/>[SleepForm.tsx]"]
  node_sleepcalc["Sleep summaries<br/>[sleep.ts]"]
end

subgraph group_insights["Goals and insights"]
  node_week["Weekly summary<br/>[page.tsx]"]
  node_weekchart["Weekly chart<br/>[WeeklyChart.tsx]"]
  node_stats["Time statistics<br/>[stats.ts]"]
  node_goals["Goal management<br/>[page.tsx]"]
  node_goalform["Goal editor<br/>[GoalForm.tsx]"]
  node_vessel["Vessel display<br/>[Bottle.tsx]"]
  node_goalcalc["Goal calculations<br/>[goals.ts]"]
end

subgraph group_state["Application state"]
  node_auth["Auth context<br/>[auth-context.tsx]"]
  node_tracker["Tracker context"]
  node_datatypes["Domain records<br/>[database.ts]"]
end

subgraph group_storage["Data storage"]
  node_storeapi["Store interface<br/>[store.ts]"]
  node_demostore[("Demo store<br/>[demo-store.ts]")]
  node_supastore[("Supabase store<br/>[supabase-store.ts]")]
  node_supaclient["Supabase client<br/>[client.ts]"]
end

node_person(("User"))
node_supabase[("Supabase service")]

node_person -->|"signs in"| node_login
node_login -->|"authenticates"| node_auth
node_person -->|"tracks time"| node_today
node_today -->|"shows timer"| node_timer
node_today -->|"edits activities"| node_activityform
node_today -->|"adds entries"| node_entryform
node_today -->|"shows history"| node_history
node_today -->|"reads and updates"| node_tracker
node_activityform -->|"saves activity"| node_tracker
node_entryform -->|"saves entry"| node_tracker
node_timer -->|"shows elapsed time"| node_person
node_person -->|"logs sleep"| node_sleep
node_sleep -->|"opens editor"| node_sleepform
node_sleep -->|"summarizes nights"| node_sleepcalc
node_sleep -->|"reads and updates"| node_tracker
node_person -->|"reviews week"| node_week
node_week -->|"renders chart"| node_weekchart
node_week -->|"computes totals"| node_stats
node_week -->|"reads entries"| node_tracker
node_person -->|"sets goals"| node_goals
node_goals -->|"edits goals"| node_goalform
node_goals -->|"renders progress"| node_vessel
node_goals -->|"calculates progress"| node_goalcalc
node_goals -->|"reads goals"| node_tracker
node_goalform -->|"saves goals"| node_tracker
node_goalcalc -->|"uses time totals"| node_stats
node_person -->|"manages settings"| node_settings
node_settings -->|"manages activities"| node_tracker
node_appnav -->|"checks session"| node_auth
node_appnav -->|"provides tracker"| node_tracker
node_auth -->|"uses client"| node_supaclient
node_tracker -->|"persists changes"| node_storeapi
node_storeapi -->|"implemented by"| node_demostore
node_storeapi -->|"implemented by"| node_supastore
node_supastore -->|"queries through"| node_supaclient
node_supaclient -->|"connects to"| node_supabase
node_demostore -->|"stores in browser"| node_person
node_tracker -->|"manages records"| node_datatypes

click node_login "https://github.com/mirkp/jarful/blob/main/src/app/login/page.tsx"
click node_appnav "https://github.com/mirkp/jarful/blob/main/src/app/(app)/layout.tsx"
click node_today "https://github.com/mirkp/jarful/blob/main/src/app/(app)/page.tsx"
click node_activityform "https://github.com/mirkp/jarful/blob/main/src/components/ActivityForm.tsx"
click node_entryform "https://github.com/mirkp/jarful/blob/main/src/components/TimeEntryForm.tsx"
click node_history "https://github.com/mirkp/jarful/blob/main/src/components/EntryHistory.tsx"
click node_timer "https://github.com/mirkp/jarful/blob/main/src/components/ActiveTimer.tsx"
click node_sleep "https://github.com/mirkp/jarful/blob/main/src/app/(app)/sleep/page.tsx"
click node_sleepform "https://github.com/mirkp/jarful/blob/main/src/components/SleepForm.tsx"
click node_sleepcalc "https://github.com/mirkp/jarful/blob/main/src/lib/sleep.ts"
click node_week "https://github.com/mirkp/jarful/blob/main/src/app/(app)/week/page.tsx"
click node_weekchart "https://github.com/mirkp/jarful/blob/main/src/components/WeeklyChart.tsx"
click node_stats "https://github.com/mirkp/jarful/blob/main/src/lib/stats.ts"
click node_goals "https://github.com/mirkp/jarful/blob/main/src/app/(app)/goals/page.tsx"
click node_goalform "https://github.com/mirkp/jarful/blob/main/src/components/GoalForm.tsx"
click node_vessel "https://github.com/mirkp/jarful/blob/main/src/components/Bottle.tsx"
click node_goalcalc "https://github.com/mirkp/jarful/blob/main/src/lib/goals.ts"
click node_settings "https://github.com/mirkp/jarful/blob/main/src/app/(app)/settings/page.tsx"
click node_auth "https://github.com/mirkp/jarful/blob/main/src/lib/auth-context.tsx"
click node_tracker "https://github.com/mirkp/jarful/blob/main/src/lib/tracker-context.tsx"
click node_storeapi "https://github.com/mirkp/jarful/blob/main/src/lib/data/store.ts"
click node_demostore "https://github.com/mirkp/jarful/blob/main/src/lib/data/demo-store.ts"
click node_supastore "https://github.com/mirkp/jarful/blob/main/src/lib/data/supabase-store.ts"
click node_supaclient "https://github.com/mirkp/jarful/blob/main/src/lib/supabase/client.ts"
click node_datatypes "https://github.com/mirkp/jarful/blob/main/src/types/database.ts"

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_login,node_appnav,node_settings,node_person toneBlue
class node_today,node_activityform,node_entryform,node_history,node_timer,node_sleep,node_sleepform,node_sleepcalc,node_supabase toneAmber
class node_week,node_weekchart,node_stats,node_goals,node_goalform,node_vessel,node_goalcalc toneMint
class node_auth,node_tracker,node_datatypes toneRose
class node_storeapi,node_demostore,node_supastore,node_supaclient toneIndigo
```

## Components

### Access and navigation

- [Login](https://github.com/mirkp/jarful/blob/main/src/app/login/page.tsx): `src/app/login/page.tsx`
- [App shell](https://github.com/mirkp/jarful/blob/main/src/app/(app)/layout.tsx): `src/app/(app)/layout.tsx`
- [Settings](https://github.com/mirkp/jarful/blob/main/src/app/(app)/settings/page.tsx): `src/app/(app)/settings/page.tsx`

### Time and sleep tracking

- [Today tracking](https://github.com/mirkp/jarful/blob/main/src/app/(app)/page.tsx): `src/app/(app)/page.tsx`
- [Activity editor](https://github.com/mirkp/jarful/blob/main/src/components/ActivityForm.tsx): `src/components/ActivityForm.tsx`
- [Manual entries](https://github.com/mirkp/jarful/blob/main/src/components/TimeEntryForm.tsx): `src/components/TimeEntryForm.tsx`
- [Entry history](https://github.com/mirkp/jarful/blob/main/src/components/EntryHistory.tsx): `src/components/EntryHistory.tsx`
- [Active timer](https://github.com/mirkp/jarful/blob/main/src/components/ActiveTimer.tsx): `src/components/ActiveTimer.tsx`
- [Sleep tracking](https://github.com/mirkp/jarful/blob/main/src/app/(app)/sleep/page.tsx): `src/app/(app)/sleep/page.tsx`
- [Sleep editor](https://github.com/mirkp/jarful/blob/main/src/components/SleepForm.tsx): `src/components/SleepForm.tsx`
- [Sleep summaries](https://github.com/mirkp/jarful/blob/main/src/lib/sleep.ts): `src/lib/sleep.ts`

### Goals and insights

- [Weekly summary](https://github.com/mirkp/jarful/blob/main/src/app/(app)/week/page.tsx): `src/app/(app)/week/page.tsx`
- [Weekly chart](https://github.com/mirkp/jarful/blob/main/src/components/WeeklyChart.tsx): `src/components/WeeklyChart.tsx`
- [Time statistics](https://github.com/mirkp/jarful/blob/main/src/lib/stats.ts): `src/lib/stats.ts`
- [Goal management](https://github.com/mirkp/jarful/blob/main/src/app/(app)/goals/page.tsx): `src/app/(app)/goals/page.tsx`
- [Goal editor](https://github.com/mirkp/jarful/blob/main/src/components/GoalForm.tsx): `src/components/GoalForm.tsx`
- [Vessel display](https://github.com/mirkp/jarful/blob/main/src/components/Bottle.tsx): `src/components/Bottle.tsx`
- [Goal calculations](https://github.com/mirkp/jarful/blob/main/src/lib/goals.ts): `src/lib/goals.ts`

### Application state

- [Auth context](https://github.com/mirkp/jarful/blob/main/src/lib/auth-context.tsx): `src/lib/auth-context.tsx`
- [Tracker context](https://github.com/mirkp/jarful/blob/main/src/lib/tracker-context.tsx): `src/lib/tracker-context.tsx`
- [Domain records](https://github.com/mirkp/jarful/blob/main/src/types/database.ts): `src/types/database.ts`

### Data storage

- [Store interface](https://github.com/mirkp/jarful/blob/main/src/lib/data/store.ts): `src/lib/data/store.ts`
- [Demo store](https://github.com/mirkp/jarful/blob/main/src/lib/data/demo-store.ts): `src/lib/data/demo-store.ts`
- [Supabase store](https://github.com/mirkp/jarful/blob/main/src/lib/data/supabase-store.ts): `src/lib/data/supabase-store.ts`
- [Supabase client](https://github.com/mirkp/jarful/blob/main/src/lib/supabase/client.ts): `src/lib/supabase/client.ts`

### Other components

- **User**
- **Supabase service**

## Connections

- User → Login: signs in
- Login → Auth context: authenticates (evidence: `src/app/login/page.tsx`)
- User → Today tracking: tracks time (evidence: `README.md`)
- Today tracking → Active timer: shows timer (evidence: `src/app/(app)/page.tsx`)
- Today tracking → Activity editor: edits activities (evidence: `src/app/(app)/page.tsx`)
- Today tracking → Manual entries: adds entries (evidence: `src/app/(app)/page.tsx`)
- Today tracking → Entry history: shows history (evidence: `src/app/(app)/page.tsx`)
- Today tracking → Tracker context: reads and updates (evidence: `src/app/(app)/page.tsx`)
- Activity editor → Tracker context: saves activity (evidence: `src/components/ActivityForm.tsx`)
- Manual entries → Tracker context: saves entry (evidence: `src/components/TimeEntryForm.tsx`)
- Active timer → User: shows elapsed time (evidence: `README.md`)
- User → Sleep tracking: logs sleep (evidence: `README.md`)
- Sleep tracking → Sleep editor: opens editor (evidence: `src/app/(app)/sleep/page.tsx`)
- Sleep tracking → Sleep summaries: summarizes nights (evidence: `src/app/(app)/sleep/page.tsx`)
- Sleep tracking → Tracker context: reads and updates (evidence: `src/app/(app)/sleep/page.tsx`)
- User → Weekly summary: reviews week (evidence: `README.md`)
- Weekly summary → Weekly chart: renders chart (evidence: `src/app/(app)/week/page.tsx`)
- Weekly summary → Time statistics: computes totals (evidence: `src/app/(app)/week/page.tsx`)
- Weekly summary → Tracker context: reads entries (evidence: `src/app/(app)/week/page.tsx`)
- User → Goal management: sets goals (evidence: `README.md`)
- Goal management → Goal editor: edits goals (evidence: `src/app/(app)/goals/page.tsx`)
- Goal management → Vessel display: renders progress (evidence: `src/app/(app)/goals/page.tsx`)
- Goal management → Goal calculations: calculates progress (evidence: `src/app/(app)/goals/page.tsx`)
- Goal management → Tracker context: reads goals (evidence: `src/app/(app)/goals/page.tsx`)
- Goal editor → Tracker context: saves goals (evidence: `src/components/GoalForm.tsx`)
- Goal calculations → Time statistics: uses time totals (evidence: `src/lib/goals.ts`)
- User → Settings: manages settings (evidence: `README.md`)
- Settings → Tracker context: manages activities (evidence: `src/app/(app)/settings/page.tsx`)
- App shell → Auth context: checks session (evidence: `src/app/(app)/layout.tsx`)
- App shell → Tracker context: provides tracker (evidence: `src/app/(app)/layout.tsx`)
- Auth context → Supabase client: uses client (evidence: `src/lib/auth-context.tsx`)
- Tracker context → Store interface: persists changes (evidence: `src/lib/tracker-context.tsx`)
- Store interface → Demo store: implemented by (evidence: `README.md`)
- Store interface → Supabase store: implemented by (evidence: `README.md`)
- Supabase store → Supabase client: queries through (evidence: `src/lib/data/supabase-store.ts`)
- Supabase client → Supabase service: connects to (evidence: `README.md`)
- Demo store → User: stores in browser (evidence: `README.md`)
- Tracker context → Domain records: manages records (evidence: `src/lib/tracker-context.tsx`)
