# dustinbrett/daedalos architecture

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

- Interactive diagram: https://gitdiagram.com/dustinbrett/daedalos
- Repository: https://github.com/dustinbrett/daedalos

## Overview

1. **Product shape**
   - This repository is a browser-based desktop environment, not a traditional site.
   - The top-level experience is a shell with a desktop, taskbar, start menu, windows, and a file system, with apps launched inside the shell.

2. **Framework and runtime boundary**
   - The app is a **Next.js + React + TypeScript** frontend.
   - Pages are thin: `pages/index.tsx` and `_app.tsx` mostly bootstrap the UI, while most behavior lives under `components/`, `contexts/`, and `hooks/`.
   - The deployment target is a static/browser runtime plus optional Docker/Node hosting.

3. **Core shell hierarchy**
   - `components/system/` contains the desktop OS-like shell:
     - `Desktop` renders wallpapers and the desktop surface.
     - `Taskbar` handles active windows, search, clock, start button, and AI chat.
     - `StartMenu` exposes app launchers and system shortcuts.
     - `Window` provides the movable/resizable window chrome and focus handling.
     - `Dialogs` contains modal system UI such as properties, run, open-with, and transfer dialogs.
   - These are the main architectural boundaries for the diagram.

4. **App container and launcher model**
   - `components/system/Apps` is the bridge between the shell and individual applications.
   - `AppsLoader`, `AppContainer`, and `RenderComponent` resolve an app identifier into a mounted React component, then wrap it with loading/error handling.
   - Most applications live under `components/apps/<AppName>` and are isolated feature modules rather than sharing a common app framework.

5. **State and coordination contexts**
   - Cross-cutting state is managed through React contexts in `contexts/`:
     - `fileSystem` manages the virtual file system abstraction and async FS access.
     - `process` tracks open processes/windows and app lifecycle.
     - `session` stores persisted session state.
     - `menu` coordinates context-menu state.
     - `viewport` tracks screen/windowing layout state.
   - These contexts are the main coordination layer between shell, apps, and file operations.

6. **Virtual file system as a central data plane**
   - The file system is a core subsystem, backed by **BrowserFS** with persistence via **IndexedDB**.
   - Files and folders flow through the file explorer, context menus, app open handlers, drag-and-drop, and terminal commands.
   - File-related UI lives under `components/system/Files/`, while `contexts/fileSystem/` holds the actual file-system plumbing.
   - This is the main shared data boundary across the whole repo.

7. **File-oriented app integration**
   - File Explorer is a first-class shell app and also the gateway for launching other apps against files.
   - `components/system/Files/FileManager` handles selection, sorting, drag/drop, keyboard shortcuts, mounting, and folder navigation.
   - `FileEntry` and `Views/*` render files in list/icon/detail modes.
   - Right-click actions and “Open with” dialogs connect file types to specific apps.

8. **Application categories and external engines**
   - Apps are mostly specialized wrappers around external JavaScript/WebAssembly projects:
     - Emulators and runtimes: BoxedWine, js-dos, EmulatorJS, v86, Ruffle, TIC-80, Quake 3, Space Cadet, ClassiCube.
     - Editors/viewers: Monaco Editor, Vim, TinyMCE, Marked, PDF, Photos, Video Player, Webamp, Paint.
     - Communication/tools: Browser, IRC, Messenger, DevTools, Terminal.
   - Many of these load prebuilt assets from `public/Program Files/` and are isolated behind app-specific hooks and config files.

9. **Worker-heavy and sandboxed features**
   - Several subsystems offload work to Web Workers or canvas-backed rendering:
     - Clock, wallpapers, Stable Diffusion, AI chat, and some media/process helpers.
     - Wallpaper renderers use `OffscreenCanvas`/worker pairs.
     - Stable Diffusion and other heavy tools run through WebGPU/WebAssembly assets.
   - This creates a clear boundary between UI orchestration and compute-heavy execution.

10. **Taskbar utilities and search**
   - The taskbar is more than navigation; it aggregates system utilities:
     - app/window switching,
     - hover peek previews,
     - system clock/calendar,
     - search across apps/files,
     - AI chat entrypoint.
   - Search is tied to file-system data, recent items, and app launch targets, so it acts as a secondary access path into the shell state.

11. **Assets, static program payloads, and scripts**
   - `public/Program Files/` and `public/System/` contain the runtime payloads: wasm binaries, vendor JS, emulator cores, fonts, icons, and bundled app resources.
   - `public/Users/Public/` provides the default user-visible directory structure and shortcuts.
   - `scripts/` contains build-time generation utilities such as icon preprocessing, search indexing, and static asset generation.
   - `styles/` provides theme/global shell styling, while `utils/` holds shared helpers for media conversion, ZIP handling, FFmpeg/ImageMagick wrappers, search, and process helpers.

12. **Testing and validation**
   - The repo has unit tests under `__tests__/` and end-to-end coverage under `e2e/`.
   - Playwright-style E2E tests validate core shell flows such as desktop, start menu, taskbar, window behavior, search, metadata, and representative apps.
   - This reinforces that the architecture is centered on integrated shell behavior rather than isolated page rendering.

Main entry points: [`components/system/Desktop/index.tsx`](https://github.com/dustinbrett/daedalos/blob/main/components/system/Desktop/index.tsx) (Desktop), [`contexts/fileSystem/index.ts`](https://github.com/dustinbrett/daedalos/blob/main/contexts/fileSystem/index.ts) (File system ctx), [`pages/_app.tsx`](https://github.com/dustinbrett/daedalos/blob/main/pages/_app.tsx) (App bootstrap), [`public/Program Files`](https://github.com/dustinbrett/daedalos/tree/HEAD/public/Program%20Files) (Program files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_pages_index["Home page<br/>next page<br/>[index.tsx]"]
  node_pages_app["App bootstrap<br/>next app<br/>[_app.tsx]"]
end

subgraph group_shell["Shell UI"]
  node_desktop["Desktop<br/>shell surface<br/>[index.tsx]"]
  node_taskbar["Taskbar<br/>shell bar<br/>[index.tsx]"]
  node_startmenu["Start menu<br/>launcher menu<br/>[index.tsx]"]
  node_window["Window chrome<br/>window manager<br/>[index.tsx]"]
  node_dialogs["System dialogs<br/>modal ui"]
  node_search_taskbar["Search<br/>[index.tsx]"]
  node_wallpapers["Wallpapers<br/>background engine"]
end

subgraph group_apps["Apps"]
  node_apps_bridge["Apps bridge<br/>app host<br/>[AppContainer.tsx]"]
  node_file_explorer["File Explorer<br/>shell app<br/>[index.tsx]"]
  node_terminal["Terminal<br/>shell app<br/>[index.tsx]"]
  node_browser_app["Browser<br/>shell app<br/>[index.tsx]"]
  node_editor_suite["Editors<br/>app cluster"]
  node_emulators["Emulators<br/>app cluster"]
  node_messaging_tools["Comms tools<br/>app cluster"]
end

subgraph group_state["State"]
  node_file_system_ctx[("File system ctx<br/>context<br/>[index.ts]")]
  node_process_ctx[("Process ctx<br/>context<br/>[index.ts]")]
  node_session_ctx[("Session ctx<br/>context<br/>[index.ts]")]
  node_menu_ctx[("Menu ctx<br/>context<br/>[index.tsx]")]
  node_viewport_ctx[("Viewport ctx<br/>context<br/>[index.ts]")]
end

subgraph group_filesystem["File System"]
  node_fs_core[("FS core<br/>browserfs layer<br/>[core.ts]")]
  node_file_manager["File manager<br/>file shell<br/>[index.tsx]"]
  node_file_entry["File entry<br/>file item<br/>[index.tsx]"]
end

subgraph group_assets["Payloads"]
  node_payloads[("Program files<br/>static payloads")]
  node_system_payloads[("System payloads<br/>static payloads")]
end

node_pages_app -->|"provides"| node_file_system_ctx
node_pages_app -->|"provides"| node_process_ctx
node_pages_app -->|"provides"| node_session_ctx
node_pages_app -->|"provides"| node_menu_ctx
node_pages_app -->|"provides"| node_viewport_ctx
node_pages_index -->|"mounts"| node_desktop
node_desktop -->|"uses"| node_wallpapers
node_desktop -->|"contains"| node_taskbar
node_desktop -->|"opens"| node_startmenu
node_desktop -->|"hosts"| node_window
node_desktop -->|"shows"| node_dialogs
node_taskbar -->|"contains"| node_search_taskbar
node_taskbar -->|"reads"| node_process_ctx
node_taskbar -->|"reads"| node_session_ctx
node_startmenu -->|"launches"| node_apps_bridge
node_apps_bridge -->|"wraps"| node_window
node_apps_bridge -->|"loads"| node_payloads
node_file_explorer -->|"uses"| node_file_manager
node_file_manager -->|"renders"| node_file_entry
node_file_explorer -->|"reads"| node_file_system_ctx
node_file_explorer -->|"opens"| node_dialogs
node_terminal -->|"uses"| node_file_system_ctx
node_terminal -->|"loads"| node_system_payloads
node_browser_app -->|"loads"| node_payloads
node_editor_suite -->|"loads"| node_payloads
node_emulators -->|"loads"| node_payloads
node_messaging_tools -->|"loads"| node_payloads
node_file_system_ctx -->|"backed by"| node_fs_core
node_menu_ctx -->|"coordinates"| node_file_system_ctx
node_search_taskbar -->|"searches"| node_file_system_ctx
node_wallpapers -->|"loads"| node_system_payloads

click node_pages_index "https://github.com/dustinbrett/daedalos/blob/main/pages/index.tsx"
click node_pages_app "https://github.com/dustinbrett/daedalos/blob/main/pages/_app.tsx"
click node_desktop "https://github.com/dustinbrett/daedalos/blob/main/components/system/Desktop/index.tsx"
click node_taskbar "https://github.com/dustinbrett/daedalos/blob/main/components/system/Taskbar/index.tsx"
click node_startmenu "https://github.com/dustinbrett/daedalos/blob/main/components/system/StartMenu/index.tsx"
click node_window "https://github.com/dustinbrett/daedalos/blob/main/components/system/Window/index.tsx"
click node_dialogs "https://github.com/dustinbrett/daedalos/tree/main/components/system/Dialogs"
click node_apps_bridge "https://github.com/dustinbrett/daedalos/blob/main/components/system/Apps/AppContainer.tsx"
click node_file_explorer "https://github.com/dustinbrett/daedalos/blob/main/components/apps/FileExplorer/index.tsx"
click node_terminal "https://github.com/dustinbrett/daedalos/blob/main/components/apps/Terminal/index.tsx"
click node_browser_app "https://github.com/dustinbrett/daedalos/blob/main/components/apps/Browser/index.tsx"
click node_file_system_ctx "https://github.com/dustinbrett/daedalos/blob/main/contexts/fileSystem/index.ts"
click node_process_ctx "https://github.com/dustinbrett/daedalos/blob/main/contexts/process/index.ts"
click node_session_ctx "https://github.com/dustinbrett/daedalos/blob/main/contexts/session/index.ts"
click node_menu_ctx "https://github.com/dustinbrett/daedalos/blob/main/contexts/menu/index.tsx"
click node_viewport_ctx "https://github.com/dustinbrett/daedalos/blob/main/contexts/viewport/index.ts"
click node_fs_core "https://github.com/dustinbrett/daedalos/blob/main/contexts/fileSystem/core.ts"
click node_file_manager "https://github.com/dustinbrett/daedalos/blob/main/components/system/Files/FileManager/index.tsx"
click node_file_entry "https://github.com/dustinbrett/daedalos/blob/main/components/system/Files/FileEntry/index.tsx"
click node_search_taskbar "https://github.com/dustinbrett/daedalos/blob/main/components/system/Taskbar/Search/index.tsx"
click node_wallpapers "https://github.com/dustinbrett/daedalos/tree/main/components/system/Desktop/Wallpapers"
click node_payloads "https://github.com/dustinbrett/daedalos/tree/main/public/Program Files"
click node_system_payloads "https://github.com/dustinbrett/daedalos/tree/main/public/System"

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_pages_index,node_pages_app toneBlue
class node_desktop,node_taskbar,node_startmenu,node_window,node_dialogs,node_search_taskbar,node_wallpapers toneAmber
class node_apps_bridge,node_file_explorer,node_terminal,node_browser_app,node_editor_suite,node_emulators,node_messaging_tools toneMint
class node_file_system_ctx,node_process_ctx,node_session_ctx,node_menu_ctx,node_viewport_ctx toneRose
class node_fs_core,node_file_manager,node_file_entry toneIndigo
class node_payloads,node_system_payloads toneTeal
```

## Components

### Runtime

Next.js/React shell bootstrap and page boundary

- [Home page](https://github.com/dustinbrett/daedalos/blob/main/pages/index.tsx): next page · Entry page that mounts the desktop environment · `pages/index.tsx`
- [App bootstrap](https://github.com/dustinbrett/daedalos/blob/main/pages/_app.tsx): next app · Global app wrapper, providers, and shared page setup · `pages/_app.tsx`

### Shell UI

Desktop environment and windowing chrome

- [Desktop](https://github.com/dustinbrett/daedalos/blob/main/components/system/Desktop/index.tsx): shell surface · Renders wallpaper and the root desktop workspace · `components/system/Desktop/index.tsx`
- [Taskbar](https://github.com/dustinbrett/daedalos/blob/main/components/system/Taskbar/index.tsx): shell bar · Handles window switching, search, clock, and AI entrypoints · `components/system/Taskbar/index.tsx`
- [Start menu](https://github.com/dustinbrett/daedalos/blob/main/components/system/StartMenu/index.tsx): launcher menu · App launchers and system shortcuts · `components/system/StartMenu/index.tsx`
- [Window chrome](https://github.com/dustinbrett/daedalos/blob/main/components/system/Window/index.tsx): window manager · Movable, resizable window container and titlebar actions · `components/system/Window/index.tsx`
- [System dialogs](https://github.com/dustinbrett/daedalos/tree/main/components/system/Dialogs): modal ui · Properties, run, open-with, transfer, and screensaver dialogs · `components/system/Dialogs`
- [Search](https://github.com/dustinbrett/daedalos/blob/main/components/system/Taskbar/Search/index.tsx): shell search · Searches apps, files, and recent targets from the taskbar · `components/system/Taskbar/Search/index.tsx`
- [Wallpapers](https://github.com/dustinbrett/daedalos/tree/main/components/system/Desktop/Wallpapers): background engine · Wallpaper modes, worker-backed rendering, and desktop visuals · `components/system/Desktop/Wallpapers`

### Apps

Launcher bridge and isolated applications

- [Apps bridge](https://github.com/dustinbrett/daedalos/blob/main/components/system/Apps/AppContainer.tsx): app host · Resolves app ids and mounts app components with loading/error handling · `components/system/Apps/AppContainer.tsx`
- [File Explorer](https://github.com/dustinbrett/daedalos/blob/main/components/apps/FileExplorer/index.tsx): shell app · Primary file browsing and file-launch gateway · `components/apps/FileExplorer/index.tsx`
- [Terminal](https://github.com/dustinbrett/daedalos/blob/main/components/apps/Terminal/index.tsx): shell app · Command interpreter and runtime bridge for shell operations · `components/apps/Terminal/index.tsx`
- [Browser](https://github.com/dustinbrett/daedalos/blob/main/components/apps/Browser/index.tsx): shell app · Web browsing wrapper with history, proxy, and bookmarks · `components/apps/Browser/index.tsx`
- **Editors**: app cluster · Text, code, markdown, PDF, paint, photo, video, and media tools
- **Emulators**: app cluster · Wrappers around embedded emulator and game runtimes
- **Comms tools**: app cluster · Chat, IRC, devtools, and other interactive utilities

### State

Cross-cutting React contexts and coordination

- [File system ctx](https://github.com/dustinbrett/daedalos/blob/main/contexts/fileSystem/index.ts): context · Virtual file system access and async FS plumbing · `contexts/fileSystem/index.ts`
- [Process ctx](https://github.com/dustinbrett/daedalos/blob/main/contexts/process/index.ts): context · Tracks open processes, windows, and app lifecycle · `contexts/process/index.ts`
- [Session ctx](https://github.com/dustinbrett/daedalos/blob/main/contexts/session/index.ts): context · Persisted session state across reloads · `contexts/session/index.ts`
- [Menu ctx](https://github.com/dustinbrett/daedalos/blob/main/contexts/menu/index.tsx): context · Context-menu coordination state · `contexts/menu/index.tsx`
- [Viewport ctx](https://github.com/dustinbrett/daedalos/blob/main/contexts/viewport/index.ts): context · Screen and windowing layout state · `contexts/viewport/index.ts`

### File System

Virtual file system and file-centric flows

- [FS core](https://github.com/dustinbrett/daedalos/blob/main/contexts/fileSystem/core.ts): browserfs layer · BrowserFS-backed virtual filesystem core and configuration · `contexts/fileSystem/core.ts`
- [File manager](https://github.com/dustinbrett/daedalos/blob/main/components/system/Files/FileManager/index.tsx): file shell · Selection, sorting, drag-drop, keyboard shortcuts, and folder navigation · `components/system/Files/FileManager/index.tsx`
- [File entry](https://github.com/dustinbrett/daedalos/blob/main/components/system/Files/FileEntry/index.tsx): file item · File rows/icons, rename flow, metadata, and context actions · `components/system/Files/FileEntry/index.tsx`

### Payloads

Bundled runtime assets and static programs

- [Program files](https://github.com/dustinbrett/daedalos/tree/HEAD/public/Program%20Files): static payloads · Bundled wasm, vendor JS, emulator cores, and app resources · `public/Program Files`
- [System payloads](https://github.com/dustinbrett/daedalos/tree/main/public/System): static payloads · Shared system assets, icons, wasm tools, and shell resources · `public/System`

## Connections

- App bootstrap → File system ctx: provides · App bootstrap wires global shell state providers
- App bootstrap → Process ctx: provides · App bootstrap shares process/window lifecycle state
- App bootstrap → Session ctx: provides · App bootstrap restores persisted session state
- App bootstrap → Menu ctx: provides · App bootstrap enables menu coordination
- App bootstrap → Viewport ctx: provides · App bootstrap shares viewport state
- Home page → Desktop: mounts · Home page renders the desktop shell
- Desktop → Wallpapers: uses · Desktop background and wallpaper rendering
- Desktop → Taskbar: contains · Desktop includes the taskbar surface
- Desktop → Start menu: opens · Desktop shell exposes the start menu
- Desktop → Window chrome: hosts · Desktop hosts application windows
- Desktop → System dialogs: shows · Desktop shows modal system dialogs
- Taskbar → Search: contains · Taskbar embeds shell search
- Taskbar → Process ctx: reads · Taskbar reflects active windows and processes
- Taskbar → Session ctx: reads · Taskbar uses persisted shell state and recents
- Start menu → Apps bridge: launches · Start menu launches apps through the app host
- Apps bridge → Window chrome: wraps · Mounted apps are wrapped inside shell windows
- Apps bridge → Program files: loads · App host resolves apps against bundled program files
- File Explorer → File manager: uses · File explorer is built on the shared file manager
- File manager → File entry: renders · File manager delegates item rendering and actions
- File Explorer → File system ctx: reads · File explorer navigates the virtual filesystem
- File Explorer → System dialogs: opens · File actions open system dialogs such as properties and open-with
- Terminal → File system ctx: uses · Terminal executes file-oriented commands against the virtual FS
- Terminal → System payloads: loads · Terminal depends on bundled runtime tools and wasm helpers
- Browser → Program files: loads · Browser app wraps packaged browser payloads
- Editors → Program files: loads · Editors and viewers are mostly wrappers around bundled engines
- Emulators → Program files: loads · Emulator apps attach to prebuilt cores and assets
- Comms tools → Program files: loads · Communication and utility apps rely on packaged runtimes
- File system ctx → FS core: backed by · File system context is implemented on BrowserFS and persistence
- Menu ctx → File system ctx: coordinates · Menus depend on file and item state for actions
- Search → File system ctx: searches · Search indexes file-system content and recent items
- Wallpapers → System payloads: loads · Wallpaper modes use shared system assets and worker code
