How dustinbrett/daedalos works
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: index.tsx Desktop · index.ts File system ctx · _app.tsx App bootstrap · Program Files Program files
Components 26
Runtime
Next.js/React shell bootstrap and page boundary
- Home page · Entry page that mounts the desktop environment
pages/index.tsx - App bootstrap · Global app wrapper, providers, and shared page setup
pages/_app.tsx
Shell UI
Desktop environment and windowing chrome
- Desktop · Renders wallpaper and the root desktop workspace
components/system/Desktop/index.tsx - Taskbar · Handles window switching, search, clock, and AI entrypoints
components/system/Taskbar/index.tsx - Start menu · App launchers and system shortcuts
components/system/StartMenu/index.tsx - Window chrome · Movable, resizable window container and titlebar actions
components/system/Window/index.tsx - System dialogs · Properties, run, open-with, transfer, and screensaver dialogs
components/system/Dialogs - Search · Searches apps, files, and recent targets from the taskbar
components/system/Taskbar/Search/index.tsx - Wallpapers · Wallpaper modes, worker-backed rendering, and desktop visuals
components/system/Desktop/Wallpapers
Apps
Launcher bridge and isolated applications
- Apps bridge · Resolves app ids and mounts app components with loading/error handling
components/system/Apps/AppContainer.tsx - File Explorer · Primary file browsing and file-launch gateway
components/apps/FileExplorer/index.tsx - Terminal · Command interpreter and runtime bridge for shell operations
components/apps/Terminal/index.tsx - Browser · Web browsing wrapper with history, proxy, and bookmarks
components/apps/Browser/index.tsx - Editors · Text, code, markdown, PDF, paint, photo, video, and media tools
- Emulators · Wrappers around embedded emulator and game runtimes
- Comms tools · Chat, IRC, devtools, and other interactive utilities
State
Cross-cutting React contexts and coordination
- File system ctx · Virtual file system access and async FS plumbing
contexts/fileSystem/index.ts - Process ctx · Tracks open processes, windows, and app lifecycle
contexts/process/index.ts - Session ctx · Persisted session state across reloads
contexts/session/index.ts - Menu ctx · Context-menu coordination state
contexts/menu/index.tsx - Viewport ctx · Screen and windowing layout state
contexts/viewport/index.ts
File System
Virtual file system and file-centric flows
- FS core · BrowserFS-backed virtual filesystem core and configuration
contexts/fileSystem/core.ts - File manager · Selection, sorting, drag-drop, keyboard shortcuts, and folder navigation
components/system/Files/FileManager/index.tsx - File entry · File rows/icons, rename flow, metadata, and context actions
components/system/Files/FileEntry/index.tsx
Payloads
Bundled runtime assets and static programs
- Program files · Bundled wasm, vendor JS, emulator cores, and app resources
public/Program Files - System payloads · Shared system assets, icons, wasm tools, and shell resources
public/System
Connections 31
- 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