# amerhanna/ameros architecture

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

- Interactive diagram: https://gitdiagram.com/amerhanna/ameros
- Repository: https://github.com/amerhanna/ameros

## Overview

AmerOS is a browser-based desktop simulation. A user enters through the Next.js page, opens applications from the desktop shell, and works with virtual files, registry settings, and app-scoped or shared databases. The shell’s window engine manages launches and window state; individual application families provide file management, productivity, media, and system tools. The README documents these system capabilities, while excerpts directly confirm window orchestration, registry-backed app services, and database-to-VFS persistence. Other application wiring is represented only at the documented capability level.

Main entry points: [`components/WindowManager/WindowManager.tsx`](https://github.com/amerhanna/ameros/blob/master/components/WindowManager/WindowManager.tsx) (Window manager), [`lib/vfs.ts`](https://github.com/amerhanna/ameros/blob/master/lib/vfs.ts) (Virtual filesystem), [`hooks/useWindowEngine.ts`](https://github.com/amerhanna/ameros/blob/master/hooks/useWindowEngine.ts) (Window engine), [`lib/registry.ts`](https://github.com/amerhanna/ameros/blob/master/lib/registry.ts) (System registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_page["Desktop entry<br/>[page.tsx]"]
  node_wm["Window manager<br/>[WindowManager.tsx]"]
  node_engine["Window engine<br/>[useWindowEngine.ts]"]
  node_windowview["Window frame<br/>[Window.tsx]"]
  node_startmenu["Start menu<br/>[StartMenu.tsx]"]
  node_taskbar["Taskbar<br/>[Taskbar.tsx]"]
end

subgraph group_system["OS services"]
  node_appservice["App services<br/>[app-service.ts]"]
  node_fileservice["File associations<br/>[file-service.ts]"]
  node_dialogs["System dialogs<br/>[OpenFileDialog.tsx]"]
  node_databasehooks["Database hooks<br/>[useDatabase.ts]"]
  node_database["Database service<br/>[database.ts]"]
end

subgraph group_apps["Applications"]
  node_files["File explorer<br/>[FileExplorer.tsx]"]
  node_productivity["Productivity apps<br/>[Notes.tsx]"]
  node_media["Media apps<br/>[MusicPlayer.tsx]"]
  node_systemapps["System tools<br/>[DBExplorer.tsx]"]
end

subgraph group_state["Persistent state"]
  node_registry["System registry<br/>[registry.ts]"]
  node_vfs[("Virtual filesystem<br/>[vfs.ts]")]
  node_windowstore[("Window state store<br/>[window-store.ts]")]
end

node_user(("Desktop user"))
node_browserstorage[("Browser storage")]

node_user -->|"opens"| node_page
node_page -->|"renders"| node_wm
node_wm -->|"orchestrates"| node_engine
node_engine -->|"launches apps"| node_appservice
node_engine -->|"updates state"| node_windowstore
node_engine -->|"persists preferences"| node_browserstorage
node_wm -->|"renders windows"| node_windowview
node_wm -->|"renders menu"| node_startmenu
node_wm -->|"renders taskbar"| node_taskbar
node_wm -->|"reads settings"| node_registry
node_wm -->|"reads wallpaper"| node_vfs
node_appservice -->|"manages app entries"| node_registry
node_fileservice -->|"resolves associations"| node_registry
node_dialogs -->|"selects files"| node_files
node_databasehooks -->|"queries"| node_database
node_database -->|"loads and saves"| node_vfs
node_files -->|"manages files"| node_vfs
node_productivity -.->|"uses files"| node_vfs
node_media -.->|"uses files"| node_vfs
node_systemapps -.->|"explores data"| node_databasehooks

click node_page "https://github.com/amerhanna/ameros/blob/master/app/page.tsx"
click node_wm "https://github.com/amerhanna/ameros/blob/master/components/WindowManager/WindowManager.tsx"
click node_engine "https://github.com/amerhanna/ameros/blob/master/hooks/useWindowEngine.ts"
click node_windowview "https://github.com/amerhanna/ameros/blob/master/components/WindowManager/Window.tsx"
click node_startmenu "https://github.com/amerhanna/ameros/blob/master/components/WindowManager/StartMenu.tsx"
click node_taskbar "https://github.com/amerhanna/ameros/blob/master/components/WindowManager/Taskbar.tsx"
click node_appservice "https://github.com/amerhanna/ameros/blob/master/lib/app-service.ts"
click node_fileservice "https://github.com/amerhanna/ameros/blob/master/lib/file-service.ts"
click node_dialogs "https://github.com/amerhanna/ameros/blob/master/components/SystemDialogs/OpenFileDialog.tsx"
click node_files "https://github.com/amerhanna/ameros/blob/master/Applications/FileExplorer/FileExplorer.tsx"
click node_productivity "https://github.com/amerhanna/ameros/blob/master/Applications/Notes/Notes.tsx"
click node_media "https://github.com/amerhanna/ameros/blob/master/Applications/MusicPlayer/MusicPlayer.tsx"
click node_systemapps "https://github.com/amerhanna/ameros/blob/master/Applications/DBExplorer/DBExplorer.tsx"
click node_databasehooks "https://github.com/amerhanna/ameros/blob/master/hooks/useDatabase.ts"
click node_database "https://github.com/amerhanna/ameros/blob/master/lib/database.ts"
click node_registry "https://github.com/amerhanna/ameros/blob/master/lib/registry.ts"
click node_vfs "https://github.com/amerhanna/ameros/blob/master/lib/vfs.ts"
click node_windowstore "https://github.com/amerhanna/ameros/blob/master/lib/window-store.ts"

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_page,node_wm,node_engine,node_windowview,node_startmenu,node_taskbar,node_user toneBlue
class node_appservice,node_fileservice,node_dialogs,node_databasehooks,node_database,node_browserstorage toneAmber
class node_files,node_productivity,node_media,node_systemapps toneMint
class node_registry,node_vfs,node_windowstore toneRose
```

## Components

### Desktop shell

- [Desktop entry](https://github.com/amerhanna/ameros/blob/master/app/page.tsx): `app/page.tsx`
- [Window manager](https://github.com/amerhanna/ameros/blob/master/components/WindowManager/WindowManager.tsx): `components/WindowManager/WindowManager.tsx`
- [Window engine](https://github.com/amerhanna/ameros/blob/master/hooks/useWindowEngine.ts): `hooks/useWindowEngine.ts`
- [Window frame](https://github.com/amerhanna/ameros/blob/master/components/WindowManager/Window.tsx): `components/WindowManager/Window.tsx`
- [Start menu](https://github.com/amerhanna/ameros/blob/master/components/WindowManager/StartMenu.tsx): `components/WindowManager/StartMenu.tsx`
- [Taskbar](https://github.com/amerhanna/ameros/blob/master/components/WindowManager/Taskbar.tsx): `components/WindowManager/Taskbar.tsx`

### OS services

- [App services](https://github.com/amerhanna/ameros/blob/master/lib/app-service.ts): `lib/app-service.ts`
- [File associations](https://github.com/amerhanna/ameros/blob/master/lib/file-service.ts): `lib/file-service.ts`
- [System dialogs](https://github.com/amerhanna/ameros/blob/master/components/SystemDialogs/OpenFileDialog.tsx): `components/SystemDialogs/OpenFileDialog.tsx`
- [Database hooks](https://github.com/amerhanna/ameros/blob/master/hooks/useDatabase.ts): `hooks/useDatabase.ts`
- [Database service](https://github.com/amerhanna/ameros/blob/master/lib/database.ts): `lib/database.ts`

### Applications

- [File explorer](https://github.com/amerhanna/ameros/blob/master/Applications/FileExplorer/FileExplorer.tsx): `Applications/FileExplorer/FileExplorer.tsx`
- [Productivity apps](https://github.com/amerhanna/ameros/blob/master/Applications/Notes/Notes.tsx): `Applications/Notes/Notes.tsx`
- [Media apps](https://github.com/amerhanna/ameros/blob/master/Applications/MusicPlayer/MusicPlayer.tsx): `Applications/MusicPlayer/MusicPlayer.tsx`
- [System tools](https://github.com/amerhanna/ameros/blob/master/Applications/DBExplorer/DBExplorer.tsx): `Applications/DBExplorer/DBExplorer.tsx`

### Persistent state

- [System registry](https://github.com/amerhanna/ameros/blob/master/lib/registry.ts): `lib/registry.ts`
- [Virtual filesystem](https://github.com/amerhanna/ameros/blob/master/lib/vfs.ts): `lib/vfs.ts`
- [Window state store](https://github.com/amerhanna/ameros/blob/master/lib/window-store.ts): `lib/window-store.ts`

### Other components

- **Desktop user**
- **Browser storage**

## Connections

- Desktop user → Desktop entry: opens
- Desktop entry → Window manager: renders
- Window manager → Window engine: orchestrates
- Window engine → App services: launches apps
- Window engine → Window state store: updates state
- Window engine → Browser storage: persists preferences
- Window manager → Window frame: renders windows
- Window manager → Start menu: renders menu
- Window manager → Taskbar: renders taskbar
- Window manager → System registry: reads settings
- Window manager → Virtual filesystem: reads wallpaper
- App services → System registry: manages app entries
- File associations → System registry: resolves associations
- System dialogs → File explorer: selects files
- Database hooks → Database service: queries
- Database service → Virtual filesystem: loads and saves
- File explorer → Virtual filesystem: manages files
- Productivity apps → Virtual filesystem: uses files
- Media apps → Virtual filesystem: uses files
- System tools → Database hooks: explores data