# danialkhilji/homeos architecture

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

- Interactive diagram: https://gitdiagram.com/danialkhilji/homeos
- Repository: https://github.com/danialkhilji/homeos

## Overview

HomeOS is a shared household dashboard for a kitchen touchscreen. A family member uses the React pages to manage tasks, shopping, notes, members, birthdays, and settings; the frontend’s API layer communicates with FastAPI, which exposes domain routes and persists household data in SQLite. The dashboard also presents calendar, prayer-time, and weather information. The source excerpts establish application routing, task interactions, and several backend service relationships; some feature wiring is documented only by the README or source index, so those connections are shown as unverified.

Main entry points: [`backend/app/api/v1/router.py`](https://github.com/danialkhilji/homeos/blob/main/backend/app/api/v1/router.py) (Versioned API), [`frontend/src/App.tsx`](https://github.com/danialkhilji/homeos/blob/main/frontend/src/App.tsx) (Page routing), [`backend/app/main.py`](https://github.com/danialkhilji/homeos/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/modules/members/service.py`](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/members/service.py) (Member operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Touchscreen app"]
  node_app["Page routing<br/>[App.tsx]"]
  node_dashboard["Dashboard"]
  node_taskspage["Task page<br/>[TasksPage.tsx]"]
  node_taskhooks["Task queries<br/>[useTasks.ts]"]
  node_taskapi["Task API client<br/>[tasks.ts]"]
  node_shoppingui["Shopping pages"]
  node_notesui["Notes pages"]
  node_settingsui["Settings pages"]
  node_calendarui["Calendar pages"]
  node_httpclient["HTTP client<br/>[client.ts]"]
end

subgraph group_backend["API runtime"]
  node_runtime["FastAPI application<br/>[main.py]"]
  node_v1["Versioned API<br/>[router.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_database[("SQLite session<br/>[database.py]")]
  node_scheduler["Background scheduler<br/>[scheduler.py]"]
  node_errors["Error handling<br/>[exceptions.py]"]
  node_cleanup["Data cleanup<br/>[service.py]"]
end

subgraph group_household["Household management"]
  node_tasks["Task domain"]
  node_taskservice["Task operations<br/>[service.py]"]
  node_taskmodel[("Task records<br/>[models.py]")]
  node_members["Member management"]
  node_memberservice["Member operations<br/>[service.py]"]
  node_membermodel[("Member records<br/>[models.py]")]
  node_shopping["Shopping lists"]
  node_notes["Household notes"]
end

subgraph group_information["Dashboard information"]
  node_calendar["Calendar and birthdays"]
  node_weather["Weather service<br/>[service.py]"]
  node_prayer["Prayer times"]
end

node_family(("Family member"))
node_openmeteo["Open-Meteo"]

node_family -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_taskspage
node_app -->|"routes to"| node_shoppingui
node_app -->|"routes to"| node_notesui
node_app -->|"routes to"| node_settingsui
node_taskspage -->|"uses"| node_taskhooks
node_taskhooks -->|"calls"| node_taskapi
node_taskapi -->|"uses"| node_httpclient
node_httpclient -.->|"requests"| node_v1
node_runtime -->|"mounts"| node_v1
node_runtime -->|"reads"| node_config
node_runtime -->|"disposes"| node_database
node_runtime -->|"starts and stops"| node_scheduler
node_runtime -->|"registers"| node_errors
node_v1 -->|"registers"| node_tasks
node_v1 -->|"registers"| node_members
node_v1 -->|"registers"| node_shopping
node_v1 -->|"registers"| node_notes
node_v1 -->|"registers"| node_calendar
node_v1 -->|"registers"| node_weather
node_v1 -->|"registers"| node_prayer
node_tasks -->|"delegates"| node_taskservice
node_taskservice -->|"queries"| node_taskmodel
node_taskservice -->|"verifies member"| node_memberservice
node_members -->|"delegates"| node_memberservice
node_memberservice -->|"queries"| node_membermodel
node_memberservice -->|"unassigns"| node_taskmodel
node_memberservice -->|"clears authors"| node_notes
node_taskmodel -->|"uses"| node_database
node_membermodel -->|"uses"| node_database
node_weather -->|"fetches forecast"| node_openmeteo
node_weather -->|"reads settings"| node_config
node_dashboard -.->|"displays"| node_weather
node_dashboard -.->|"displays"| node_prayer
node_dashboard -.->|"displays"| node_calendarui
node_shoppingui -.->|"requests data"| node_shopping
node_notesui -.->|"requests data"| node_notes
node_settingsui -.->|"manages"| node_members
node_calendarui -.->|"requests data"| node_calendar
node_cleanup -->|"cleans"| node_taskmodel
node_cleanup -->|"cleans"| node_notes
node_cleanup -->|"cleans"| node_shopping

click node_app "https://github.com/danialkhilji/homeos/blob/main/frontend/src/App.tsx"
click node_dashboard "https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/dashboard"
click node_taskspage "https://github.com/danialkhilji/homeos/blob/main/frontend/src/features/tasks/TasksPage.tsx"
click node_taskhooks "https://github.com/danialkhilji/homeos/blob/main/frontend/src/hooks/useTasks.ts"
click node_taskapi "https://github.com/danialkhilji/homeos/blob/main/frontend/src/api/tasks.ts"
click node_shoppingui "https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/shopping"
click node_notesui "https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/notes"
click node_settingsui "https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/settings"
click node_calendarui "https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/calendar"
click node_httpclient "https://github.com/danialkhilji/homeos/blob/main/frontend/src/api/client.ts"
click node_runtime "https://github.com/danialkhilji/homeos/blob/main/backend/app/main.py"
click node_v1 "https://github.com/danialkhilji/homeos/blob/main/backend/app/api/v1/router.py"
click node_config "https://github.com/danialkhilji/homeos/blob/main/backend/app/core/config.py"
click node_database "https://github.com/danialkhilji/homeos/blob/main/backend/app/core/database.py"
click node_scheduler "https://github.com/danialkhilji/homeos/blob/main/backend/app/core/scheduler.py"
click node_errors "https://github.com/danialkhilji/homeos/blob/main/backend/app/core/exceptions.py"
click node_tasks "https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/tasks"
click node_taskservice "https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/tasks/service.py"
click node_taskmodel "https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/tasks/models.py"
click node_members "https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/members"
click node_memberservice "https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/members/service.py"
click node_membermodel "https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/members/models.py"
click node_shopping "https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/shopping"
click node_notes "https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/notes"
click node_calendar "https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/calendar"
click node_weather "https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/weather/service.py"
click node_prayer "https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/prayer"
click node_cleanup "https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/cleanup/service.py"

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_dashboard,node_taskspage,node_taskhooks,node_taskapi,node_shoppingui,node_notesui,node_settingsui,node_calendarui,node_httpclient toneBlue
class node_runtime,node_v1,node_config,node_database,node_scheduler,node_errors,node_cleanup toneAmber
class node_tasks,node_taskservice,node_taskmodel,node_members,node_memberservice,node_membermodel,node_shopping,node_notes toneMint
class node_calendar,node_weather,node_prayer toneRose
class node_family,node_openmeteo toneIndigo
```

## Components

### Touchscreen app

- [Page routing](https://github.com/danialkhilji/homeos/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Dashboard](https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/dashboard): `frontend/src/features/dashboard`
- [Task page](https://github.com/danialkhilji/homeos/blob/main/frontend/src/features/tasks/TasksPage.tsx): `frontend/src/features/tasks/TasksPage.tsx`
- [Task queries](https://github.com/danialkhilji/homeos/blob/main/frontend/src/hooks/useTasks.ts): `frontend/src/hooks/useTasks.ts`
- [Task API client](https://github.com/danialkhilji/homeos/blob/main/frontend/src/api/tasks.ts): `frontend/src/api/tasks.ts`
- [Shopping pages](https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/shopping): `frontend/src/features/shopping`
- [Notes pages](https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/notes): `frontend/src/features/notes`
- [Settings pages](https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/settings): `frontend/src/features/settings`
- [Calendar pages](https://github.com/danialkhilji/homeos/tree/main/frontend/src/features/calendar): `frontend/src/features/calendar`
- [HTTP client](https://github.com/danialkhilji/homeos/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API runtime

- [FastAPI application](https://github.com/danialkhilji/homeos/blob/main/backend/app/main.py): `backend/app/main.py`
- [Versioned API](https://github.com/danialkhilji/homeos/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Configuration](https://github.com/danialkhilji/homeos/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [SQLite session](https://github.com/danialkhilji/homeos/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Background scheduler](https://github.com/danialkhilji/homeos/blob/main/backend/app/core/scheduler.py): `backend/app/core/scheduler.py`
- [Error handling](https://github.com/danialkhilji/homeos/blob/main/backend/app/core/exceptions.py): `backend/app/core/exceptions.py`
- [Data cleanup](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/cleanup/service.py): `backend/app/modules/cleanup/service.py`

### Household management

- [Task domain](https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/tasks): `backend/app/modules/tasks`
- [Task operations](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/tasks/service.py): `backend/app/modules/tasks/service.py`
- [Task records](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/tasks/models.py): `backend/app/modules/tasks/models.py`
- [Member management](https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/members): `backend/app/modules/members`
- [Member operations](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/members/service.py): `backend/app/modules/members/service.py`
- [Member records](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/members/models.py): `backend/app/modules/members/models.py`
- [Shopping lists](https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/shopping): `backend/app/modules/shopping`
- [Household notes](https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/notes): `backend/app/modules/notes`

### Dashboard information

- [Calendar and birthdays](https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/calendar): `backend/app/modules/calendar`
- [Weather service](https://github.com/danialkhilji/homeos/blob/main/backend/app/modules/weather/service.py): `backend/app/modules/weather/service.py`
- [Prayer times](https://github.com/danialkhilji/homeos/tree/main/backend/app/modules/prayer): `backend/app/modules/prayer`

### Other components

- **Family member**
- **Open-Meteo**

## Connections

- Family member → Page routing: uses (evidence: `README.md`)
- Page routing → Dashboard: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Task page: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Shopping pages: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Notes pages: routes to (evidence: `frontend/src/App.tsx`)
- Page routing → Settings pages: routes to (evidence: `frontend/src/App.tsx`)
- Task page → Task queries: uses (evidence: `frontend/src/features/tasks/TasksPage.tsx`)
- Task queries → Task API client: calls (evidence: `frontend/src/hooks/useTasks.ts`)
- Task API client → HTTP client: uses (evidence: `frontend/src/api/tasks.ts`)
- HTTP client → Versioned API: requests
- FastAPI application → Versioned API: mounts (evidence: `backend/app/main.py`)
- FastAPI application → Configuration: reads (evidence: `backend/app/main.py`)
- FastAPI application → SQLite session: disposes (evidence: `backend/app/main.py`)
- FastAPI application → Background scheduler: starts and stops (evidence: `backend/app/main.py`)
- FastAPI application → Error handling: registers (evidence: `backend/app/main.py`)
- Versioned API → Task domain: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Member management: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Shopping lists: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Household notes: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Calendar and birthdays: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Weather service: registers (evidence: `backend/app/api/v1/router.py`)
- Versioned API → Prayer times: registers (evidence: `backend/app/api/v1/router.py`)
- Task domain → Task operations: delegates (evidence: `backend/app/modules/tasks/router.py`)
- Task operations → Task records: queries (evidence: `backend/app/modules/tasks/service.py`)
- Task operations → Member operations: verifies member (evidence: `backend/app/modules/tasks/service.py`)
- Member management → Member operations: delegates (evidence: `backend/app/modules/members/router.py`)
- Member operations → Member records: queries (evidence: `backend/app/modules/members/service.py`)
- Member operations → Task records: unassigns (evidence: `backend/app/modules/members/service.py`)
- Member operations → Household notes: clears authors (evidence: `backend/app/modules/members/service.py`)
- Task records → SQLite session: uses (evidence: `backend/app/modules/tasks/models.py`)
- Member records → SQLite session: uses
- Weather service → Open-Meteo: fetches forecast (evidence: `backend/app/modules/weather/service.py`)
- Weather service → Configuration: reads settings (evidence: `backend/app/modules/weather/service.py`)
- Dashboard → Weather service: displays
- Dashboard → Prayer times: displays
- Dashboard → Calendar pages: displays
- Shopping pages → Shopping lists: requests data
- Notes pages → Household notes: requests data
- Settings pages → Member management: manages
- Calendar pages → Calendar and birthdays: requests data
- Data cleanup → Task records: cleans (evidence: `backend/app/modules/cleanup/service.py`)
- Data cleanup → Household notes: cleans (evidence: `backend/app/modules/cleanup/service.py`)
- Data cleanup → Shopping lists: cleans (evidence: `backend/app/modules/cleanup/service.py`)
