# thanksmors/os-shell architecture

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

- Interactive diagram: https://gitdiagram.com/thanksmors/os-shell
- Repository: https://github.com/thanksmors/os-shell

## Overview

1. **Overall shape**
   This repo is a browser-based desktop OS shell. The main runtime is the frontend in `index.html`, `shell/`, and `modules/`, with an optional backend in `codehooks/` for auth, workspaces, and persisted data.

2. **Frontend shell as the orchestration layer**
   The `shell/` directory is the core OS layer: it owns global app state, window management, keyboard shortcuts, launcher behavior, notifications, theming, and the desktop/workspace frame. The README’s `Alpine.store('os')` is the single source of truth for window lifecycle and layout.

3. **Module system boundary**
   Each app under `modules/` is a Web Component registered via `customElements.define()`. Modules are isolated with Shadow DOM and load lazily when launched. This creates a hard boundary between “OS shell” concerns and “app” concerns.

4. **How shell and modules interact**
   The shell passes a small API object into each module instance (`windowId`, mode, theme state, title updates, notifications, close requests, and access to the shared store). That API is the main integration seam; modules should not directly manage global OS state.

5. **Built-in app set**
   The shipped apps are `notepad`, `files`, `about`, and `settings`, with additional modules for `gantt`, `kanban`, `list`, `rocks`, and `boilerplate`. `settings/tabs/` suggests settings is itself internally modular, with separate tabs for workspace, appearance, and about.

6. **Data-centric module path**
   `modules/data/` stands out because it contains an `api.js`, which likely bridges the frontend shell to the backend data layer. This is the most likely path for persistent user/workspace content, while the other apps appear mostly client-side UI modules.

7. **Backend service boundary**
   `codehooks/` is a separate Node-style service with route handlers for `auth`, `data`, `invites`, `members`, and `workspaces`, plus shared libs for DB access, sessions, config, and change tracking. Architecturally, this is a multi-tenant collaboration backend rather than a generic app server.

8. **Persistence and collaboration model**
   The backend route layout implies workspace-scoped data, membership management, and invitation-based access control. `lib/changes.js` suggests change logs or sync/patch semantics, so persisted state is probably tracked as workspace updates rather than just static CRUD records.

9. **Styling and runtime constraints**
   The UI uses Alpine.js v3, Tailwind CSS, and Constructable Stylesheets/adopted stylesheets (`shadow-tailwind.js`) to share styling into shadow roots. Because imports are root-absolute ES modules, the app must be served over HTTP, not opened from `file://`.

10. **State and interaction flows**
   Typical flow is: browser loads `index.html` → shell initializes global OS store → launcher/window manager opens a module → module renders in its shadow root → module uses the injected API to update window title, request notifications, or close itself. If a module needs persistence, it routes through the backend API, likely via `modules/data`.

11. **Deployment and hosting**
   `netlify.toml` suggests the frontend is intended for static hosting, while `codehooks/` is deployed separately as the server/API layer. `registry.json` likely supports module discovery/launch metadata in the shell, and `build/` contains Tailwind build inputs for future or optional CSS generation.

Main entry points: [`registry.json`](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/registry.json) (Registry), [`codehooks/index.js`](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/index.js) (Backend Entry), [`shell/workspace.js`](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/workspace.js) (Workspace UI), [`shell/api.js`](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/api.js) (Shell API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend Shell"]
  node_index_html["index.html<br/>entrypoint<br/>[index.html]"]
  node_shell_store[("OS Store<br/>state core<br/>[store-os.js]")]
  node_shell_window_manager["Window Manager<br/>windowing<br/>[window-manager.js]"]
  node_shell_api["Shell API<br/>integration api<br/>[api.js]"]
  node_shell_workspace["Workspace UI<br/>workspace frame<br/>[workspace.js]"]
  node_shell_shortcuts["Shortcuts<br/>input handling<br/>[shortcuts.js]"]
  node_shell_auth_store[("Auth State<br/>session state<br/>[store-auth.js]")]
  node_shell_shadow_tailwind["Shadow CSS<br/>style bridge<br/>[shadow-tailwind.js]"]
end

subgraph group_apps["Modules"]
  node_modules_registry["Registry<br/>module manifest<br/>[registry.json]"]
  node_module_data_api["Data API<br/>data bridge<br/>[api.js]"]
  node_module_notepad["Notepad<br/>app module<br/>[index.js]"]
  node_module_files["Files<br/>app module<br/>[index.js]"]
  node_module_settings["Settings<br/>app module<br/>[index.js]"]
  node_module_about["About<br/>app module<br/>[index.js]"]
  node_module_boilerplate["Boilerplate<br/>starter module<br/>[index.js]"]
end

subgraph group_backend["Codehooks Backend"]
  node_backend_entry["Backend Entry<br/>service entry<br/>[index.js]"]
  node_backend_auth["Auth Route<br/>http route<br/>[auth.js]"]
  node_backend_data["Data Route<br/>http route<br/>[data.js]"]
  node_backend_workspaces["Workspaces<br/>workspace route<br/>[workspaces.js]"]
  node_backend_members["Members<br/>[members.js]"]
  node_backend_invites["Invites<br/>invitation route<br/>[invites.js]"]
  node_backend_db[("DB Layer<br/>persistence<br/>[db.js]")]
  node_backend_session[("Session<br/>[session.js]")]
  node_backend_changes["Change Log<br/>sync log<br/>[changes.js]"]
end

subgraph group_ops["Build & Deploy"]
  node_build_tailwind["Tailwind Config<br/>build config<br/>[tailwind.config.js]"]
  node_netlify_config["Netlify<br/>hosting config<br/>[netlify.toml]"]
end

node_index_html -->|"boot"| node_shell_store
node_index_html -->|"start"| node_shell_workspace
node_shell_workspace -->|"coordinate"| node_shell_window_manager
node_shell_window_manager -->|"read/write"| node_shell_store
node_shell_workspace -->|"bind"| node_shell_shortcuts
node_shell_workspace -->|"session"| node_shell_auth_store
node_shell_api -->|"access"| node_shell_store
node_shell_api -->|"control"| node_shell_window_manager
node_shell_shadow_tailwind -.->|"style"| node_module_notepad
node_modules_registry -->|"launches"| node_module_notepad
node_modules_registry -->|"launches"| node_module_files
node_modules_registry -->|"launches"| node_module_settings
node_modules_registry -->|"launches"| node_module_about
node_modules_registry -->|"launches"| node_module_boilerplate
node_module_settings -->|"uses"| node_shell_api
node_module_notepad -->|"uses"| node_shell_api
node_module_files -->|"persistence"| node_module_data_api
node_module_data_api -->|"http"| node_backend_data
node_backend_entry -->|"registers"| node_backend_auth
node_backend_entry -->|"registers"| node_backend_data
node_backend_entry -->|"registers"| node_backend_workspaces
node_backend_entry -->|"registers"| node_backend_members
node_backend_entry -->|"registers"| node_backend_invites
node_backend_auth -->|"session"| node_backend_session
node_backend_data -->|"persist"| node_backend_db
node_backend_data -->|"track"| node_backend_changes
node_backend_workspaces -->|"persist"| node_backend_db
node_backend_members -->|"persist"| node_backend_db
node_backend_invites -->|"persist"| node_backend_db
node_build_tailwind -->|"feeds"| node_shell_shadow_tailwind
node_netlify_config -->|"deploys"| node_index_html

click node_index_html "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/index.html"
click node_shell_store "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/store-os.js"
click node_shell_window_manager "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/window-manager.js"
click node_shell_api "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/api.js"
click node_shell_workspace "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/workspace.js"
click node_shell_shortcuts "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/shortcuts.js"
click node_shell_auth_store "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/store-auth.js"
click node_shell_shadow_tailwind "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/shadow-tailwind.js"
click node_modules_registry "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/registry.json"
click node_module_data_api "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/data/api.js"
click node_module_notepad "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/notepad/index.js"
click node_module_files "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/files/index.js"
click node_module_settings "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/settings/index.js"
click node_module_about "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/about/index.js"
click node_module_boilerplate "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/boilerplate/index.js"
click node_backend_entry "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/index.js"
click node_backend_auth "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/auth.js"
click node_backend_data "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/data.js"
click node_backend_workspaces "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/workspaces.js"
click node_backend_members "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/members.js"
click node_backend_invites "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/invites.js"
click node_backend_db "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/lib/db.js"
click node_backend_session "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/lib/session.js"
click node_backend_changes "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/lib/changes.js"
click node_build_tailwind "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/build/tailwind.config.js"
click node_netlify_config "https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/netlify.toml"

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_index_html,node_shell_store,node_shell_window_manager,node_shell_api,node_shell_workspace,node_shell_shortcuts,node_shell_auth_store,node_shell_shadow_tailwind toneBlue
class node_modules_registry,node_module_data_api,node_module_notepad,node_module_files,node_module_settings,node_module_about,node_module_boilerplate toneAmber
class node_backend_entry,node_backend_auth,node_backend_data,node_backend_workspaces,node_backend_members,node_backend_invites,node_backend_db,node_backend_session,node_backend_changes toneMint
class node_build_tailwind,node_netlify_config toneRose
```

## Components

### Frontend Shell

Browser-loaded OS shell, windowing, shared state, and UI runtime.

- [index.html](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/index.html): entrypoint · Browser entry that boots the shell and loads the frontend runtime. · `index.html`
- [OS Store](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/store-os.js): state core · Single source of truth for windows, layout, theme, and desktop state. · `shell/store-os.js`
- [Window Manager](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/window-manager.js): windowing · Opens, tracks, and arranges app windows and their lifecycle. · `shell/window-manager.js`
- [Shell API](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/api.js): integration api · Shared interface passed into modules for title, close, notifications, and state access. · `shell/api.js`
- [Workspace UI](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/workspace.js): workspace frame · Desktop/workspace orchestration and shell-level framing. · `shell/workspace.js`
- [Shortcuts](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/shortcuts.js): input handling · Keyboard shortcuts and global interaction bindings. · `shell/shortcuts.js`
- [Auth State](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/store-auth.js): session state · Authentication and user/session state used by the shell. · `shell/store-auth.js`
- [Shadow CSS](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/shell/shadow-tailwind.js): style bridge · Constructable stylesheet bridge for sharing Tailwind styles into shadow roots. · `shell/shadow-tailwind.js`

### Modules

Lazy-loaded desktop apps implemented as Web Components.

- [Registry](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/registry.json): module manifest · Launch metadata for discovering and registering available modules. · `registry.json`
- [Data API](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/data/api.js): data bridge · Frontend bridge for persistent workspace and content operations. · `modules/data/api.js`
- [Notepad](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/notepad/index.js): app module · Text note editor module. · `modules/notepad/index.js`
- [Files](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/files/index.js): app module · File browsing and workspace content module. · `modules/files/index.js`
- [Settings](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/settings/index.js): app module · System settings module with internal tabs for workspace, appearance, and about. · `modules/settings/index.js`
- [About](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/about/index.js): app module · Application/about information module. · `modules/about/index.js`
- [Boilerplate](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/modules/boilerplate/index.js): starter module · Template module used as a starting point for new apps. · `modules/boilerplate/index.js`

### Codehooks Backend

Workspace/auth/data service for multi-tenant persistence and collaboration.

- [Backend Entry](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/index.js): service entry · Codehooks service bootstrap and route registration. · `codehooks/index.js`
- [Auth Route](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/auth.js): http route · Authentication endpoints for the collaboration service. · `codehooks/routes/auth.js`
- [Data Route](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/data.js): http route · Workspace-scoped data endpoints for persisted content. · `codehooks/routes/data.js`
- [Workspaces](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/workspaces.js): workspace route · Workspace lifecycle and tenancy endpoints. · `codehooks/routes/workspaces.js`
- [Members](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/members.js): membership route · Workspace membership management endpoints. · `codehooks/routes/members.js`
- [Invites](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/routes/invites.js): invitation route · Invitation and access-sharing endpoints. · `codehooks/routes/invites.js`
- [DB Layer](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/lib/db.js): persistence · Database access layer for stored workspace data. · `codehooks/lib/db.js`
- [Session](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/lib/session.js): session · Session handling and auth persistence helpers. · `codehooks/lib/session.js`
- [Change Log](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/codehooks/lib/changes.js): sync log · Change tracking and patch semantics for persisted workspace state. · `codehooks/lib/changes.js`

### Build & Deploy

Static hosting and build inputs for the browser shell.

- [Tailwind Config](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/build/tailwind.config.js): build config · Tailwind build configuration and CSS input for generated styles. · `build/tailwind.config.js`
- [Netlify](https://github.com/thanksmors/os-shell/blob/claude/friendly-brown-ilby6/netlify.toml): hosting config · Static hosting configuration for the frontend shell. · `netlify.toml`

## Connections

- index.html → OS Store: boot · Initializes the global OS state when the browser loads.
- index.html → Workspace UI: start · Loads the shell workspace and desktop frame.
- Workspace UI → Window Manager: coordinate · Uses the window manager to create and arrange app windows.
- Window Manager → OS Store: read/write · Consumes the shared OS store for window lifecycle and layout.
- Workspace UI → Shortcuts: bind · Attaches global keyboard shortcuts to shell actions.
- Workspace UI → Auth State: session · Uses auth state to reflect signed-in workspace context.
- Shell API → OS Store: access · Exposes selected shared state to launched modules.
- Shell API → Window Manager: control · Lets modules request window title updates and close actions.
- Shadow CSS → Notepad: style · Shares styles into module shadow roots.
- Registry → Notepad: launches · Describes an available module for the shell launcher.
- Registry → Files: launches · Describes an available module for the shell launcher.
- Registry → Settings: launches · Describes an available module for the shell launcher.
- Registry → About: launches · Describes an available module for the shell launcher.
- Registry → Boilerplate: launches · Describes an available module for the shell launcher.
- Settings → Shell API: uses · Settings uses the injected shell API for title and state interactions.
- Notepad → Shell API: uses · Notepad uses the injected shell API for window and notification actions.
- Files → Data API: persistence · Files routes workspace content operations through the data bridge.
- Data API → Data Route: http · Frontend persistence bridge calls the backend data route.
- Backend Entry → Auth Route: registers · Bootstraps auth endpoints.
- Backend Entry → Data Route: registers · Bootstraps data endpoints.
- Backend Entry → Workspaces: registers · Bootstraps workspace endpoints.
- Backend Entry → Members: registers · Bootstraps membership endpoints.
- Backend Entry → Invites: registers · Bootstraps invitation endpoints.
- Auth Route → Session: session · Uses session helpers for authentication state.
- Data Route → DB Layer: persist · Reads and writes stored workspace data.
- Data Route → Change Log: track · Tracks changes for sync or patch semantics.
- Workspaces → DB Layer: persist · Stores workspace records and tenancy data.
- Members → DB Layer: persist · Stores workspace membership records.
- Invites → DB Layer: persist · Stores invitation records and access links.
- Tailwind Config → Shadow CSS: feeds · Build inputs support the shared shadow DOM styling layer.
- Netlify → index.html: deploys · Static hosting serves the browser entry and frontend assets.