thanksmors/os-shell

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.