# dombialcz/overrun-lite architecture

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

- Interactive diagram: https://gitdiagram.com/dombialcz/overrun-lite
- Repository: https://github.com/dombialcz/overrun-lite

## Overview

Overrun Lite is a local-first, AI-assisted daily planner. Users create and edit day tasks or backlog items, organize them on a calendar, and optionally submit brain dumps or task requests for AI proposals; proposals are reviewed and edited before application. Signed-in users can sync a revision-checked planner document through Supabase, while guests retain browser-local data. The graph reflects the documented product capabilities and sampled call paths; several UI and export/import responsibilities are assigned to app.js based on the README, without inferring their internal wiring.

Main entry points: [`app.js`](https://github.com/dombialcz/overrun-lite/blob/main/app.js) (Planner application), [`api/plan.js`](https://github.com/dombialcz/overrun-lite/blob/main/api/plan.js) (Hosted planner API), [`api/_supabase.js`](https://github.com/dombialcz/overrun-lite/blob/main/api/_supabase.js) (Supabase access), [`cloud.js`](https://github.com/dombialcz/overrun-lite/blob/main/cloud.js) (Cloud account and sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planner["Planner experience"]
  node_app["Planner application<br/>[app.js]"]
  node_task_edit["Task editor<br/>[app.js]"]
  node_calendar["Day calendar<br/>[app.js]"]
  node_backlog["Task backlog<br/>[app.js]"]
  node_local_state[("Browser planner state<br/>[app.js]")]
  node_theme["Theme preference<br/>[theme.js]"]
  node_browser_store[("Browser storage")]
end

subgraph group_ai["AI planning"]
  node_ai_review["Proposal review<br/>[app.js]"]
  node_ai_contract["AI request contract<br/>[aiContract.js]"]
  node_local_provider["Local AI endpoint"]
end

subgraph group_account["Accounts and sync"]
  node_cloud["Cloud account and sync<br/>[cloud.js]"]
  node_auth_link["Invite link handling<br/>[authLink.js]"]
end

subgraph group_services["Backend services"]
  node_hosted_api["Hosted planner API<br/>[plan.js]"]
  node_config_api["Configuration API<br/>[config.js]"]
  node_usage_api["AI usage API<br/>[ai-usage.js]"]
  node_hosted_provider["Hosted AI provider"]
  node_supabase_client["Supabase access<br/>[_supabase.js]"]
  node_supabase[("Supabase Auth and Postgres")]
end

node_user(("Planner user"))

node_user -->|"creates or edits"| node_task_edit
node_task_edit -->|"saves draft"| node_local_state
node_user -->|"organizes day"| node_calendar
node_calendar -->|"updates planner"| node_local_state
node_user -->|"manages tasks"| node_backlog
node_backlog -->|"updates planner"| node_local_state
node_app -->|"reads and writes"| node_local_state
node_app -->|"stores preferences"| node_browser_store
node_theme -->|"reads preference"| node_browser_store
node_user -->|"uses planner"| node_app
node_app -->|"builds AI request"| node_ai_contract
node_app -.->|"sends local request"| node_local_provider
node_app -->|"sends authenticated request"| node_hosted_api
node_hosted_api -->|"builds and validates payload"| node_ai_contract
node_hosted_api -->|"checks user and reserves quota"| node_supabase_client
node_hosted_api -->|"requests completion"| node_hosted_provider
node_hosted_provider -->|"returns completion"| node_hosted_api
node_hosted_api -->|"releases quota on failure"| node_supabase_client
node_app -->|"opens proposal review"| node_ai_review
node_ai_review -->|"applies approved changes"| node_local_state
node_app -->|"starts account and sync flows"| node_cloud
node_app -->|"loads capabilities"| node_config_api
node_app -->|"refreshes usage"| node_usage_api
node_cloud -->|"loads cloud config"| node_config_api
node_cloud -->|"validates invite links"| node_auth_link
node_cloud -->|"authenticates and syncs planner"| node_supabase
node_cloud -->|"caches account state"| node_browser_store
node_config_api -->|"checks auth configuration"| node_supabase_client
node_usage_api -->|"reads quota usage"| node_supabase_client
node_supabase_client -->|"validates users and accesses data"| node_supabase
node_supabase_client -->|"returns user context"| node_hosted_api
node_supabase_client -->|"returns usage data"| node_usage_api
node_user -->|"signs in or syncs"| node_cloud

click node_app "https://github.com/dombialcz/overrun-lite/blob/main/app.js"
click node_task_edit "https://github.com/dombialcz/overrun-lite/blob/main/app.js"
click node_calendar "https://github.com/dombialcz/overrun-lite/blob/main/app.js"
click node_backlog "https://github.com/dombialcz/overrun-lite/blob/main/app.js"
click node_local_state "https://github.com/dombialcz/overrun-lite/blob/main/app.js"
click node_theme "https://github.com/dombialcz/overrun-lite/blob/main/theme.js"
click node_ai_review "https://github.com/dombialcz/overrun-lite/blob/main/app.js"
click node_ai_contract "https://github.com/dombialcz/overrun-lite/blob/main/aiContract.js"
click node_hosted_api "https://github.com/dombialcz/overrun-lite/blob/main/api/plan.js"
click node_config_api "https://github.com/dombialcz/overrun-lite/blob/main/api/config.js"
click node_usage_api "https://github.com/dombialcz/overrun-lite/blob/main/api/ai-usage.js"
click node_cloud "https://github.com/dombialcz/overrun-lite/blob/main/cloud.js"
click node_auth_link "https://github.com/dombialcz/overrun-lite/blob/main/authLink.js"
click node_supabase_client "https://github.com/dombialcz/overrun-lite/blob/main/api/_supabase.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_task_edit,node_calendar,node_backlog,node_local_state,node_theme,node_browser_store,node_user toneBlue
class node_ai_review,node_ai_contract,node_local_provider toneAmber
class node_cloud,node_auth_link toneMint
class node_hosted_api,node_config_api,node_usage_api,node_hosted_provider,node_supabase_client,node_supabase toneRose
```

## Components

### Planner experience

- [Planner application](https://github.com/dombialcz/overrun-lite/blob/main/app.js): `app.js`
- [Task editor](https://github.com/dombialcz/overrun-lite/blob/main/app.js): `app.js`
- [Day calendar](https://github.com/dombialcz/overrun-lite/blob/main/app.js): `app.js`
- [Task backlog](https://github.com/dombialcz/overrun-lite/blob/main/app.js): `app.js`
- [Browser planner state](https://github.com/dombialcz/overrun-lite/blob/main/app.js): `app.js`
- [Theme preference](https://github.com/dombialcz/overrun-lite/blob/main/theme.js): `theme.js`
- **Browser storage**

### AI planning

- [Proposal review](https://github.com/dombialcz/overrun-lite/blob/main/app.js): `app.js`
- [AI request contract](https://github.com/dombialcz/overrun-lite/blob/main/aiContract.js): `aiContract.js`
- **Local AI endpoint**

### Accounts and sync

- [Cloud account and sync](https://github.com/dombialcz/overrun-lite/blob/main/cloud.js): `cloud.js`
- [Invite link handling](https://github.com/dombialcz/overrun-lite/blob/main/authLink.js): `authLink.js`

### Backend services

- [Hosted planner API](https://github.com/dombialcz/overrun-lite/blob/main/api/plan.js): `api/plan.js`
- [Configuration API](https://github.com/dombialcz/overrun-lite/blob/main/api/config.js): `api/config.js`
- [AI usage API](https://github.com/dombialcz/overrun-lite/blob/main/api/ai-usage.js): `api/ai-usage.js`
- **Hosted AI provider**
- [Supabase access](https://github.com/dombialcz/overrun-lite/blob/main/api/_supabase.js): `api/_supabase.js`
- **Supabase Auth and Postgres**

### Other components

- **Planner user**

## Connections

- Planner user → Task editor: creates or edits
- Task editor → Browser planner state: saves draft
- Planner user → Day calendar: organizes day
- Day calendar → Browser planner state: updates planner
- Planner user → Task backlog: manages tasks
- Task backlog → Browser planner state: updates planner
- Planner application → Browser planner state: reads and writes
- Planner application → Browser storage: stores preferences
- Theme preference → Browser storage: reads preference
- Planner user → Planner application: uses planner
- Planner application → AI request contract: builds AI request
- Planner application → Local AI endpoint: sends local request
- Planner application → Hosted planner API: sends authenticated request
- Hosted planner API → AI request contract: builds and validates payload
- Hosted planner API → Supabase access: checks user and reserves quota
- Hosted planner API → Hosted AI provider: requests completion
- Hosted AI provider → Hosted planner API: returns completion
- Hosted planner API → Supabase access: releases quota on failure
- Planner application → Proposal review: opens proposal review
- Proposal review → Browser planner state: applies approved changes
- Planner application → Cloud account and sync: starts account and sync flows
- Planner application → Configuration API: loads capabilities
- Planner application → AI usage API: refreshes usage
- Cloud account and sync → Configuration API: loads cloud config
- Cloud account and sync → Invite link handling: validates invite links
- Cloud account and sync → Supabase Auth and Postgres: authenticates and syncs planner
- Cloud account and sync → Browser storage: caches account state
- Configuration API → Supabase access: checks auth configuration
- AI usage API → Supabase access: reads quota usage
- Supabase access → Supabase Auth and Postgres: validates users and accesses data
- Supabase access → Hosted planner API: returns user context
- Supabase access → AI usage API: returns usage data
- Planner user → Cloud account and sync: signs in or syncs