# truthfool30/hearth architecture

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

- Interactive diagram: https://gitdiagram.com/truthfool30/hearth
- Repository: https://github.com/truthfool30/hearth

## Overview

Hearth is a self-hosted family hub. A member signs in, selects or joins a family, then uses the app’s feature modules; requests reach the server’s authenticated family APIs and persistent SQLite data, with live updates shared across devices. The product’s major branches cover the home wall, calendar, lists, chat, photos, meals, budget, locator, and vault. The README documents these capabilities; several feature implementations were not sampled, so their client-to-server links are left unverified rather than inferred.

Main entry points: [`client/src/modules/registry.tsx`](https://github.com/truthfool30/hearth/blob/main/client/src/modules/registry.tsx) (Feature registry), [`server/src/modules/index.js`](https://github.com/truthfool30/hearth/blob/main/server/src/modules/index.js) (API module router), [`client/src/App.tsx`](https://github.com/truthfool30/hearth/blob/main/client/src/App.tsx) (App routing), [`server/src/app.js`](https://github.com/truthfool30/hearth/blob/main/server/src/app.js) (HTTP application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_shell["App shell<br/>[AppShell.tsx]"]
  node_registry["Feature registry<br/>[registry.tsx]"]
end

subgraph group_core["Identity and platform"]
  node_clientauth["Client auth<br/>[auth.tsx]"]
  node_clientapi["API client<br/>[api.ts]"]
  node_serverapp["HTTP application<br/>[app.js]"]
  node_serverauth["Auth and families<br/>[auth.js]"]
  node_moduleindex["API module router<br/>[index.js]"]
  node_database[("SQLite data<br/>[db.js]")]
end

subgraph group_family["Family features"]
  node_wall["Home wall"]
  node_calendar["Calendar"]
  node_lists["Lists and tasks"]
  node_messages["Messages"]
  node_photos["Shared photos"]
  node_meals["Meals and recipes"]
end

subgraph group_personal["Household tools"]
  node_budget["Budget<br/>[budget.js]"]
  node_locator["Locator"]
  node_vault["Contacts and vault<br/>[vault.js]"]
end

node_member(("Family member"))

node_member -->|"uses"| node_app
node_app -->|"checks session"| node_clientauth
node_app -->|"renders"| node_shell
node_app -->|"routes features"| node_registry
node_clientauth -->|"requests identity"| node_clientapi
node_clientauth -.->|"uses API"| node_serverapp
node_serverapp -->|"mounts auth routes"| node_serverauth
node_serverapp -->|"mounts feature routes"| node_moduleindex
node_serverapp -.->|"receives database"| node_database
node_serverauth -.->|"reads and writes"| node_database
node_registry -->|"registers"| node_wall
node_registry -->|"registers"| node_calendar
node_registry -->|"registers"| node_lists
node_registry -->|"registers"| node_messages
node_registry -->|"registers"| node_photos
node_registry -->|"registers"| node_meals
node_registry -->|"registers"| node_budget
node_registry -->|"registers"| node_locator
node_registry -->|"registers"| node_vault
node_wall -.->|"uses feature API"| node_moduleindex
node_calendar -.->|"uses feature API"| node_moduleindex
node_lists -.->|"uses feature API"| node_moduleindex
node_messages -.->|"uses feature API"| node_moduleindex
node_photos -.->|"uses feature API"| node_moduleindex
node_meals -.->|"uses feature API"| node_moduleindex
node_budget -.->|"registered by"| node_moduleindex
node_locator -.->|"uses feature API"| node_moduleindex
node_vault -.->|"registered by"| node_moduleindex

click node_app "https://github.com/truthfool30/hearth/blob/main/client/src/App.tsx"
click node_shell "https://github.com/truthfool30/hearth/blob/main/client/src/layout/AppShell.tsx"
click node_registry "https://github.com/truthfool30/hearth/blob/main/client/src/modules/registry.tsx"
click node_clientauth "https://github.com/truthfool30/hearth/blob/main/client/src/lib/auth.tsx"
click node_clientapi "https://github.com/truthfool30/hearth/blob/main/client/src/lib/api.ts"
click node_serverapp "https://github.com/truthfool30/hearth/blob/main/server/src/app.js"
click node_serverauth "https://github.com/truthfool30/hearth/blob/main/server/src/core/auth.js"
click node_moduleindex "https://github.com/truthfool30/hearth/blob/main/server/src/modules/index.js"
click node_database "https://github.com/truthfool30/hearth/blob/main/server/src/db.js"
click node_wall "https://github.com/truthfool30/hearth/tree/main/client/src/modules/wall"
click node_calendar "https://github.com/truthfool30/hearth/tree/main/client/src/modules/calendar"
click node_lists "https://github.com/truthfool30/hearth/tree/main/client/src/modules/lists"
click node_messages "https://github.com/truthfool30/hearth/tree/main/client/src/modules/messages"
click node_photos "https://github.com/truthfool30/hearth/tree/main/client/src/modules/photos"
click node_meals "https://github.com/truthfool30/hearth/tree/main/client/src/modules/meals"
click node_budget "https://github.com/truthfool30/hearth/blob/main/server/src/modules/budget.js"
click node_locator "https://github.com/truthfool30/hearth/tree/main/client/src/modules/locator"
click node_vault "https://github.com/truthfool30/hearth/blob/main/server/src/modules/vault.js"

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_shell,node_registry toneBlue
class node_clientauth,node_clientapi,node_serverapp,node_serverauth,node_moduleindex,node_database toneAmber
class node_wall,node_calendar,node_lists,node_messages,node_photos,node_meals toneMint
class node_budget,node_locator,node_vault toneRose
class node_member toneIndigo
```

## Components

### Client experience

- [App routing](https://github.com/truthfool30/hearth/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [App shell](https://github.com/truthfool30/hearth/blob/main/client/src/layout/AppShell.tsx): `client/src/layout/AppShell.tsx`
- [Feature registry](https://github.com/truthfool30/hearth/blob/main/client/src/modules/registry.tsx): `client/src/modules/registry.tsx`

### Identity and platform

- [Client auth](https://github.com/truthfool30/hearth/blob/main/client/src/lib/auth.tsx): `client/src/lib/auth.tsx`
- [API client](https://github.com/truthfool30/hearth/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`
- [HTTP application](https://github.com/truthfool30/hearth/blob/main/server/src/app.js): `server/src/app.js`
- [Auth and families](https://github.com/truthfool30/hearth/blob/main/server/src/core/auth.js): `server/src/core/auth.js`
- [API module router](https://github.com/truthfool30/hearth/blob/main/server/src/modules/index.js): `server/src/modules/index.js`
- [SQLite data](https://github.com/truthfool30/hearth/blob/main/server/src/db.js): `server/src/db.js`

### Family features

- [Home wall](https://github.com/truthfool30/hearth/tree/main/client/src/modules/wall): `client/src/modules/wall`
- [Calendar](https://github.com/truthfool30/hearth/tree/main/client/src/modules/calendar): `client/src/modules/calendar`
- [Lists and tasks](https://github.com/truthfool30/hearth/tree/main/client/src/modules/lists): `client/src/modules/lists`
- [Messages](https://github.com/truthfool30/hearth/tree/main/client/src/modules/messages): `client/src/modules/messages`
- [Shared photos](https://github.com/truthfool30/hearth/tree/main/client/src/modules/photos): `client/src/modules/photos`
- [Meals and recipes](https://github.com/truthfool30/hearth/tree/main/client/src/modules/meals): `client/src/modules/meals`

### Household tools

- [Budget](https://github.com/truthfool30/hearth/blob/main/server/src/modules/budget.js): `server/src/modules/budget.js`
- [Locator](https://github.com/truthfool30/hearth/tree/main/client/src/modules/locator): `client/src/modules/locator`
- [Contacts and vault](https://github.com/truthfool30/hearth/blob/main/server/src/modules/vault.js): `server/src/modules/vault.js`

### Other components

- **Family member**

## Connections

- Family member → App routing: uses (evidence: `README.md`)
- App routing → Client auth: checks session (evidence: `client/src/App.tsx`)
- App routing → App shell: renders (evidence: `client/src/App.tsx`)
- App routing → Feature registry: routes features (evidence: `client/src/App.tsx`)
- Client auth → API client: requests identity (evidence: `client/src/lib/auth.tsx`)
- Client auth → HTTP application: uses API
- HTTP application → Auth and families: mounts auth routes (evidence: `server/src/app.js`)
- HTTP application → API module router: mounts feature routes (evidence: `server/src/app.js`)
- HTTP application → SQLite data: receives database (evidence: `server/src/app.js`)
- Auth and families → SQLite data: reads and writes
- Feature registry → Home wall: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Calendar: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Lists and tasks: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Messages: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Shared photos: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Meals and recipes: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Budget: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Locator: registers (evidence: `client/src/modules/registry.tsx`)
- Feature registry → Contacts and vault: registers (evidence: `client/src/modules/registry.tsx`)
- Home wall → API module router: uses feature API
- Calendar → API module router: uses feature API
- Lists and tasks → API module router: uses feature API
- Messages → API module router: uses feature API
- Shared photos → API module router: uses feature API
- Meals and recipes → API module router: uses feature API
- Budget → API module router: registered by (evidence: `server/src/modules/budget.js`)
- Locator → API module router: uses feature API
- Contacts and vault → API module router: registered by (evidence: `server/src/modules/index.js`)
