# gultar/aether-web architecture

> Architecture diagram of the GitHub repository gultar/aether-web, 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/gultar/aether-web
- Repository: https://github.com/gultar/aether-web

## Overview

Aether-Web is a local-first, browser-based desktop workspace. A user works through its desktop shell and application windows; the shell exposes productivity tools, system features, and a separate OS agent, while local Node.js and optional Python services provide integrations and AI. The graph preserves the documented capabilities even where their implementations were not sampled. Some subsystem connections are based on README descriptions rather than inspected call sites; those edges cite the README.

Main entry points: [`js/dashboard/init.js`](https://github.com/gultar/aether-web/blob/main/js/dashboard/init.js) (Desktop shell), [`private/tiny-web-agent/web_main.py`](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/web_main.py) (Agent service), [`server.js`](https://github.com/gultar/aether-web/blob/main/server.js) (Local Node service), [`js/terminal/terminal.js`](https://github.com/gultar/aether-web/blob/main/js/terminal/terminal.js) (Terminal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_shell["Desktop shell<br/>[init.js]"]
  node_windows["Window manager<br/>[create-window.js]"]
  node_desktop_config["Appearance and layout<br/>[appearance.js]"]
  node_desktop_dock["Dock and launcher<br/>[dock.js]"]
  node_system_ui["System monitor<br/>[system.js]"]
  node_terminal["Terminal<br/>[terminal.js]"]
end

subgraph group_productivity["Productivity apps"]
  node_scheduler_ui["Scheduled tasks UI<br/>[cron.js]"]
  node_calendar["Outlook calendar<br/>[outlook_ics.js]"]
  node_geomancy["Geomancy app<br/>[geomancy-app.js]"]
end

subgraph group_agent["AI agents"]
  node_agent_ui["Tiny Agent UI<br/>[app.js]"]
  node_os_agent_ui["OS agent UI<br/>[os-agent.js]"]
  node_skills["Skills routing<br/>[skill_manager.py]"]
  node_agent_api["Agent service<br/>[web_main.py]"]
  node_agent_runtime["Conversation runtime<br/>[web_agent.py]"]
  node_tool_registry["Tool registry<br/>[tool_registry.py]"]
  node_research["Research pipeline"]
  node_attachments["Document attachments<br/>[attachments.py]"]
end

subgraph group_services["Local services"]
  node_scheduler[("Persistent scheduler<br/>[cron_scheduler.js]")]
  node_node_service["Local Node service<br/>[server.js]"]
  node_voice_worker["Voice transcription<br/>[whisper_worker.py]"]
end

node_user(("User"))
node_local_model["Local LLM"]
node_outlook_feed["Published Outlook feed"]

node_user -->|"uses"| node_shell
node_shell -->|"opens windows"| node_windows
node_shell -->|"configures"| node_desktop_config
node_shell -->|"launches apps"| node_desktop_dock
node_shell -->|"offers monitoring"| node_system_ui
node_shell -->|"opens"| node_terminal
node_shell -->|"opens"| node_agent_ui
node_shell -->|"opens"| node_os_agent_ui
node_shell -->|"opens"| node_scheduler_ui
node_shell -->|"launches"| node_geomancy
node_agent_ui -->|"sends chat requests"| node_agent_api
node_os_agent_ui -->|"sends OS requests"| node_agent_api
node_agent_api -->|"routes skills"| node_skills
node_agent_api -->|"runs agent turn"| node_agent_runtime
node_agent_runtime -->|"loads tools"| node_tool_registry
node_agent_api -->|"uses research"| node_research
node_agent_api -->|"handles attachments"| node_attachments
node_agent_runtime -.->|"runs inference"| node_local_model
node_scheduler_ui -.->|"manages tasks"| node_node_service
node_node_service -->|"schedules and stores"| node_scheduler
node_node_service -->|"serves calendar data"| node_calendar
node_calendar -->|"reads ICS feed"| node_outlook_feed
node_terminal -.->|"uses local services"| node_node_service
node_terminal -->|"sends audio"| node_voice_worker

click node_shell "https://github.com/gultar/aether-web/blob/main/js/dashboard/init.js"
click node_windows "https://github.com/gultar/aether-web/blob/main/js/window-manager/create-window.js"
click node_desktop_config "https://github.com/gultar/aether-web/blob/main/js/dashboard/appearance.js"
click node_desktop_dock "https://github.com/gultar/aether-web/blob/main/js/dashboard/dock.js"
click node_system_ui "https://github.com/gultar/aether-web/blob/main/js/dashboard/system.js"
click node_terminal "https://github.com/gultar/aether-web/blob/main/js/terminal/terminal.js"
click node_agent_ui "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/static/app.js"
click node_os_agent_ui "https://github.com/gultar/aether-web/blob/main/js/dashboard/os-agent.js"
click node_skills "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/skill_manager.py"
click node_agent_api "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/web_main.py"
click node_agent_runtime "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/web_agent.py"
click node_tool_registry "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/tools/tool_registry.py"
click node_research "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/research_pipeline.py"
click node_attachments "https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/tools/attachments.py"
click node_scheduler_ui "https://github.com/gultar/aether-web/blob/main/js/dashboard/cron.js"
click node_scheduler "https://github.com/gultar/aether-web/blob/main/private/cron/cron_scheduler.js"
click node_calendar "https://github.com/gultar/aether-web/blob/main/private/calendar/outlook_ics.js"
click node_geomancy "https://github.com/gultar/aether-web/blob/main/apps/geomancy/geomancy-app.js"
click node_node_service "https://github.com/gultar/aether-web/blob/main/server.js"
click node_voice_worker "https://github.com/gultar/aether-web/blob/main/private/voice/whisper_worker.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_shell,node_windows,node_desktop_config,node_desktop_dock,node_system_ui,node_terminal,node_user toneBlue
class node_scheduler_ui,node_calendar,node_geomancy toneAmber
class node_agent_ui,node_os_agent_ui,node_skills,node_agent_api,node_agent_runtime,node_tool_registry,node_research,node_attachments toneMint
class node_scheduler,node_node_service,node_voice_worker toneRose
class node_local_model,node_outlook_feed toneIndigo
```

## Components

### Desktop shell

- [Desktop shell](https://github.com/gultar/aether-web/blob/main/js/dashboard/init.js): `js/dashboard/init.js`
- [Window manager](https://github.com/gultar/aether-web/blob/main/js/window-manager/create-window.js): `js/window-manager/create-window.js`
- [Appearance and layout](https://github.com/gultar/aether-web/blob/main/js/dashboard/appearance.js): `js/dashboard/appearance.js`
- [Dock and launcher](https://github.com/gultar/aether-web/blob/main/js/dashboard/dock.js): `js/dashboard/dock.js`
- [System monitor](https://github.com/gultar/aether-web/blob/main/js/dashboard/system.js): `js/dashboard/system.js`
- [Terminal](https://github.com/gultar/aether-web/blob/main/js/terminal/terminal.js): `js/terminal/terminal.js`

### Productivity apps

- [Scheduled tasks UI](https://github.com/gultar/aether-web/blob/main/js/dashboard/cron.js): `js/dashboard/cron.js`
- [Outlook calendar](https://github.com/gultar/aether-web/blob/main/private/calendar/outlook_ics.js): `private/calendar/outlook_ics.js`
- [Geomancy app](https://github.com/gultar/aether-web/blob/main/apps/geomancy/geomancy-app.js): `apps/geomancy/geomancy-app.js`

### AI agents

- [Tiny Agent UI](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/static/app.js): `private/tiny-web-agent/static/app.js`
- [OS agent UI](https://github.com/gultar/aether-web/blob/main/js/dashboard/os-agent.js): `js/dashboard/os-agent.js`
- [Skills routing](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/skill_manager.py): `private/tiny-web-agent/skill_manager.py`
- [Agent service](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/web_main.py): `private/tiny-web-agent/web_main.py`
- [Conversation runtime](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/web_agent.py): `private/tiny-web-agent/web_agent.py`
- [Tool registry](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/tools/tool_registry.py): `private/tiny-web-agent/tools/tool_registry.py`
- [Research pipeline](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/research_pipeline.py): `private/tiny-web-agent/research_pipeline.py`
- [Document attachments](https://github.com/gultar/aether-web/blob/main/private/tiny-web-agent/tools/attachments.py): `private/tiny-web-agent/tools/attachments.py`

### Local services

- [Persistent scheduler](https://github.com/gultar/aether-web/blob/main/private/cron/cron_scheduler.js): `private/cron/cron_scheduler.js`
- [Local Node service](https://github.com/gultar/aether-web/blob/main/server.js): `server.js`
- [Voice transcription](https://github.com/gultar/aether-web/blob/main/private/voice/whisper_worker.py): `private/voice/whisper_worker.py`

### Other components

- **User**
- **Local LLM**
- **Published Outlook feed**

## Connections

- User → Desktop shell: uses
- Desktop shell → Window manager: opens windows
- Desktop shell → Appearance and layout: configures
- Desktop shell → Dock and launcher: launches apps
- Desktop shell → System monitor: offers monitoring
- Desktop shell → Terminal: opens
- Desktop shell → Tiny Agent UI: opens
- Desktop shell → OS agent UI: opens
- Desktop shell → Scheduled tasks UI: opens
- Desktop shell → Geomancy app: launches
- Tiny Agent UI → Agent service: sends chat requests
- OS agent UI → Agent service: sends OS requests (evidence: `private/tiny-web-agent/web_main.py`)
- Agent service → Skills routing: routes skills (evidence: `private/tiny-web-agent/web_main.py`)
- Agent service → Conversation runtime: runs agent turn (evidence: `private/tiny-web-agent/web_main.py`)
- Conversation runtime → Tool registry: loads tools (evidence: `private/tiny-web-agent/web_agent.py`)
- Agent service → Research pipeline: uses research (evidence: `private/tiny-web-agent/web_main.py`)
- Agent service → Document attachments: handles attachments (evidence: `private/tiny-web-agent/web_main.py`)
- Conversation runtime → Local LLM: runs inference
- Scheduled tasks UI → Local Node service: manages tasks
- Local Node service → Persistent scheduler: schedules and stores (evidence: `server.js`)
- Local Node service → Outlook calendar: serves calendar data (evidence: `server.js`)
- Outlook calendar → Published Outlook feed: reads ICS feed
- Terminal → Local Node service: uses local services
- Terminal → Voice transcription: sends audio
