# romeoxii/hedraios architecture

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

- Interactive diagram: https://gitdiagram.com/romeoxii/hedraios
- Repository: https://github.com/romeoxii/hedraios

## Overview

Hedraios is an offline-first journal and faith-tracking PWA. A user signs in by email code, then uses Today, Notes, Prayers, or Readings to create and review records; reading details have a dedicated route, and records can be exported as JSON. Domain hooks write to local IndexedDB first and coordinate background Supabase synchronization, including reconnect handling. The README documents PWA installation and offline-shell behavior, but the service-worker implementation is not identifiable from the supplied tree and excerpts, so it is not mapped. Some view-to-hook wiring is inferred from documented feature ownership.

Main entry points: [`src/App.tsx`](https://github.com/romeoxii/hedraios/blob/main/src/App.tsx) (App Shell), [`src/lib/db.ts`](https://github.com/romeoxii/hedraios/blob/main/src/lib/db.ts) (IndexedDB), [`src/lib/sync.ts`](https://github.com/romeoxii/hedraios/blob/main/src/lib/sync.ts) (Sync Engine), [`src/lib/supabaseClient.ts`](https://github.com/romeoxii/hedraios/blob/main/src/lib/supabaseClient.ts) (Supabase Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_shell["App Shell<br/>[App.tsx]"]
  node_theme["Theme Preference<br/>[useTheme.ts]"]
  node_themecontrol["Theme Toggle<br/>[ThemeToggle.tsx]"]
end

subgraph group_identity["Identity"]
  node_authgate["Email Code Gate<br/>[AuthGate.tsx]"]
  node_authprovider["Session Provider<br/>[auth.tsx]"]
  node_authhook["Auth Hook<br/>[useAuth.ts]"]
end

subgraph group_tracking["Faith Tracking"]
  node_timeline["Today Timeline<br/>[Timeline.tsx]"]
  node_notes["Journal Notes<br/>[Notes.tsx]"]
  node_prayers["Prayer Tracker<br/>[Prayers.tsx]"]
  node_readings["Reading Log<br/>[Readings.tsx]"]
  node_reader["Reading Detail<br/>[ReaderRoute.tsx]"]
  node_entryhook["Entry Data Hook<br/>[useEntries.ts]"]
  node_prayerhook["Prayer Data Hook<br/>[usePrayers.ts]"]
  node_readinghook["Reading Data Hook<br/>[useReadings.ts]"]
  node_stats["Overview Stats<br/>[useStats.ts]"]
end

subgraph group_persistence["Data and Sync"]
  node_supabaseclient["Supabase Client<br/>[supabaseClient.ts]"]
  node_localdb[("IndexedDB<br/>[db.ts]")]
  node_sync["Sync Engine<br/>[sync.ts]"]
  node_supabase[("Supabase Backend<br/>[schema.sql]")]
  node_export["JSON Export<br/>[export.ts]"]
end

node_person(("User"))

node_person -->|"uses"| node_shell
node_shell -->|"opens sign-in"| node_authgate
node_shell -->|"provides session"| node_authprovider
node_shell -->|"checks identity"| node_authhook
node_authgate -->|"verifies code"| node_supabaseclient
node_authprovider -->|"loads session"| node_supabaseclient
node_shell -->|"routes Today"| node_timeline
node_shell -->|"routes Notes"| node_notes
node_shell -->|"routes Prayers"| node_prayers
node_shell -->|"routes Readings"| node_readings
node_shell -->|"routes detail"| node_reader
node_notes -->|"manages entries"| node_entryhook
node_prayers -->|"manages prayers"| node_prayerhook
node_readings -->|"manages readings"| node_readinghook
node_timeline -->|"shows overview"| node_stats
node_entryhook -->|"reads and writes"| node_localdb
node_entryhook -->|"requests sync"| node_sync
node_prayerhook -->|"reads and writes"| node_localdb
node_prayerhook -->|"requests sync"| node_sync
node_readinghook -->|"reads and writes"| node_localdb
node_readinghook -->|"requests sync"| node_sync
node_sync -->|"merges records"| node_localdb
node_sync -->|"transfers records"| node_supabaseclient
node_supabaseclient -->|"accesses backend"| node_supabase
node_stats -->|"counts records"| node_localdb
node_shell -->|"builds download"| node_export
node_export -->|"reads records"| node_localdb
node_themecontrol -->|"toggles preference"| node_theme

click node_shell "https://github.com/romeoxii/hedraios/blob/main/src/App.tsx"
click node_authgate "https://github.com/romeoxii/hedraios/blob/main/src/components/AuthGate.tsx"
click node_authprovider "https://github.com/romeoxii/hedraios/blob/main/src/lib/auth.tsx"
click node_authhook "https://github.com/romeoxii/hedraios/blob/main/src/hooks/useAuth.ts"
click node_supabaseclient "https://github.com/romeoxii/hedraios/blob/main/src/lib/supabaseClient.ts"
click node_timeline "https://github.com/romeoxii/hedraios/blob/main/src/components/Timeline.tsx"
click node_notes "https://github.com/romeoxii/hedraios/blob/main/src/components/Notes.tsx"
click node_prayers "https://github.com/romeoxii/hedraios/blob/main/src/components/Prayers.tsx"
click node_readings "https://github.com/romeoxii/hedraios/blob/main/src/components/Readings.tsx"
click node_reader "https://github.com/romeoxii/hedraios/blob/main/src/components/ReaderRoute.tsx"
click node_entryhook "https://github.com/romeoxii/hedraios/blob/main/src/hooks/useEntries.ts"
click node_prayerhook "https://github.com/romeoxii/hedraios/blob/main/src/hooks/usePrayers.ts"
click node_readinghook "https://github.com/romeoxii/hedraios/blob/main/src/hooks/useReadings.ts"
click node_stats "https://github.com/romeoxii/hedraios/blob/main/src/hooks/useStats.ts"
click node_localdb "https://github.com/romeoxii/hedraios/blob/main/src/lib/db.ts"
click node_sync "https://github.com/romeoxii/hedraios/blob/main/src/lib/sync.ts"
click node_supabase "https://github.com/romeoxii/hedraios/blob/main/supabase/schema.sql"
click node_export "https://github.com/romeoxii/hedraios/blob/main/src/lib/export.ts"
click node_theme "https://github.com/romeoxii/hedraios/blob/main/src/hooks/useTheme.ts"
click node_themecontrol "https://github.com/romeoxii/hedraios/blob/main/src/components/ThemeToggle.tsx"

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_shell,node_theme,node_themecontrol,node_person toneBlue
class node_authgate,node_authprovider,node_authhook toneAmber
class node_timeline,node_notes,node_prayers,node_readings,node_reader,node_entryhook,node_prayerhook,node_readinghook,node_stats toneMint
class node_supabaseclient,node_localdb,node_sync,node_supabase,node_export toneRose
```

## Components

### Application

- [App Shell](https://github.com/romeoxii/hedraios/blob/main/src/App.tsx): `src/App.tsx`
- [Theme Preference](https://github.com/romeoxii/hedraios/blob/main/src/hooks/useTheme.ts): `src/hooks/useTheme.ts`
- [Theme Toggle](https://github.com/romeoxii/hedraios/blob/main/src/components/ThemeToggle.tsx): `src/components/ThemeToggle.tsx`

### Identity

- [Email Code Gate](https://github.com/romeoxii/hedraios/blob/main/src/components/AuthGate.tsx): `src/components/AuthGate.tsx`
- [Session Provider](https://github.com/romeoxii/hedraios/blob/main/src/lib/auth.tsx): `src/lib/auth.tsx`
- [Auth Hook](https://github.com/romeoxii/hedraios/blob/main/src/hooks/useAuth.ts): `src/hooks/useAuth.ts`

### Faith Tracking

- [Today Timeline](https://github.com/romeoxii/hedraios/blob/main/src/components/Timeline.tsx): `src/components/Timeline.tsx`
- [Journal Notes](https://github.com/romeoxii/hedraios/blob/main/src/components/Notes.tsx): `src/components/Notes.tsx`
- [Prayer Tracker](https://github.com/romeoxii/hedraios/blob/main/src/components/Prayers.tsx): `src/components/Prayers.tsx`
- [Reading Log](https://github.com/romeoxii/hedraios/blob/main/src/components/Readings.tsx): `src/components/Readings.tsx`
- [Reading Detail](https://github.com/romeoxii/hedraios/blob/main/src/components/ReaderRoute.tsx): `src/components/ReaderRoute.tsx`
- [Entry Data Hook](https://github.com/romeoxii/hedraios/blob/main/src/hooks/useEntries.ts): `src/hooks/useEntries.ts`
- [Prayer Data Hook](https://github.com/romeoxii/hedraios/blob/main/src/hooks/usePrayers.ts): `src/hooks/usePrayers.ts`
- [Reading Data Hook](https://github.com/romeoxii/hedraios/blob/main/src/hooks/useReadings.ts): `src/hooks/useReadings.ts`
- [Overview Stats](https://github.com/romeoxii/hedraios/blob/main/src/hooks/useStats.ts): `src/hooks/useStats.ts`

### Data and Sync

- [Supabase Client](https://github.com/romeoxii/hedraios/blob/main/src/lib/supabaseClient.ts): `src/lib/supabaseClient.ts`
- [IndexedDB](https://github.com/romeoxii/hedraios/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Sync Engine](https://github.com/romeoxii/hedraios/blob/main/src/lib/sync.ts): `src/lib/sync.ts`
- [Supabase Backend](https://github.com/romeoxii/hedraios/blob/main/supabase/schema.sql): `supabase/schema.sql`
- [JSON Export](https://github.com/romeoxii/hedraios/blob/main/src/lib/export.ts): `src/lib/export.ts`

### Other components

- **User**

## Connections

- User → App Shell: uses
- App Shell → Email Code Gate: opens sign-in
- App Shell → Session Provider: provides session
- App Shell → Auth Hook: checks identity
- Email Code Gate → Supabase Client: verifies code
- Session Provider → Supabase Client: loads session
- App Shell → Today Timeline: routes Today
- App Shell → Journal Notes: routes Notes
- App Shell → Prayer Tracker: routes Prayers
- App Shell → Reading Log: routes Readings
- App Shell → Reading Detail: routes detail
- Journal Notes → Entry Data Hook: manages entries
- Prayer Tracker → Prayer Data Hook: manages prayers
- Reading Log → Reading Data Hook: manages readings
- Today Timeline → Overview Stats: shows overview
- Entry Data Hook → IndexedDB: reads and writes
- Entry Data Hook → Sync Engine: requests sync
- Prayer Data Hook → IndexedDB: reads and writes
- Prayer Data Hook → Sync Engine: requests sync
- Reading Data Hook → IndexedDB: reads and writes
- Reading Data Hook → Sync Engine: requests sync
- Sync Engine → IndexedDB: merges records
- Sync Engine → Supabase Client: transfers records
- Supabase Client → Supabase Backend: accesses backend
- Overview Stats → IndexedDB: counts records
- App Shell → JSON Export: builds download
- JSON Export → IndexedDB: reads records
- Theme Toggle → Theme Preference: toggles preference