# brahimaann/sanktuary-os architecture

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

- Interactive diagram: https://gitdiagram.com/brahimaann/sanktuary-os
- Repository: https://github.com/brahimaann/sanktuary-os

## Overview

Sanktuary combines a public-facing Twin Cities arts and music hub with an invitation-only, Windows 98-style member desktop. The member workflow runs from sign-in and desktop launch through shared files, previews, and collaboration; the desktop also hosts creative and utility apps. The README documents music, community stories, apparel, and shared workspaces, while the sampled source gives firmer evidence for desktop, file, API, and live-event wiring. Several public-content and desktop-app branches are represented by their exact enclosing directories because their implementations were not sampled.

Main entry points: [`src/components/Desktop.tsx`](https://github.com/brahimaann/sanktuary-os/blob/main/src/components/Desktop.tsx) (Desktop), [`src/utils/api.ts`](https://github.com/brahimaann/sanktuary-os/blob/main/src/utils/api.ts) (API Client), [`src/apps/FilePreview.tsx`](https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/FilePreview.tsx) (File Preview), [`src/apps/TeamFiles.tsx`](https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/TeamFiles.tsx) (Team Files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public Hub"]
  node_public_content["Arts &amp; Music"]
  node_cities["CITIES Journal"]
  node_shop["Shop"]
end

subgraph group_shell["Member Desktop"]
  node_app["Sanktuary App<br/>[App.tsx]"]
  node_desktop["Desktop<br/>[Desktop.tsx]"]
  node_window_manager["Window Manager<br/>[manager.ts]"]
end

subgraph group_work["Creative Workspaces"]
  node_team_files["Team Files<br/>[TeamFiles.tsx]"]
  node_file_preview["File Preview<br/>[FilePreview.tsx]"]
  node_boards["Moodboards<br/>[Boards.tsx]"]
  node_planner_chat["Planner &amp; Chat"]
  node_creative_apps["Creative Apps"]
  node_paint["JS Paint<br/>[app.js]"]
end

subgraph group_platform["Platform Services"]
  node_api["API Client<br/>[api.ts]"]
  node_live["Live Events<br/>[live.ts]"]
  node_vfs[("Virtual Filesystem<br/>[fs.ts]")]
  node_server["Node Server<br/>[index.mjs]"]
  node_clerk["Clerk Sign-in"]
end

node_visitor(("Visitor"))
node_member(("Member"))

node_visitor -->|"explores"| node_public_content
node_visitor -->|"reads"| node_cities
node_visitor -->|"shops"| node_shop
node_member -->|"signs in"| node_clerk
node_member -->|"works in"| node_desktop
node_clerk -.->|"provides session"| node_api
node_app -->|"reads windows"| node_window_manager
node_app -->|"renders"| node_desktop
node_desktop -->|"opens windows"| node_window_manager
node_desktop -->|"fetches member data"| node_api
node_desktop -->|"starts connection"| node_live
node_desktop -->|"syncs notes"| node_vfs
node_team_files -->|"fetches files"| node_api
node_team_files -->|"opens preview"| node_file_preview
node_file_preview -->|"gets file URL"| node_team_files
node_file_preview -->|"fetches metadata"| node_api
node_api -->|"sends API requests"| node_server
node_live -->|"receives events"| node_server
node_member -->|"creates moodboards"| node_boards
node_member -->|"collaborates"| node_planner_chat
node_member -.->|"uses apps"| node_creative_apps
node_creative_apps -.->|"includes"| node_paint

click node_public_content "https://github.com/brahimaann/sanktuary-os/tree/main/src/apps"
click node_cities "https://github.com/brahimaann/sanktuary-os/tree/main/ops/nodes"
click node_shop "https://github.com/brahimaann/sanktuary-os/tree/main/src/apps"
click node_app "https://github.com/brahimaann/sanktuary-os/blob/main/src/App.tsx"
click node_desktop "https://github.com/brahimaann/sanktuary-os/blob/main/src/components/Desktop.tsx"
click node_window_manager "https://github.com/brahimaann/sanktuary-os/blob/main/src/wm/manager.ts"
click node_team_files "https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/TeamFiles.tsx"
click node_file_preview "https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/FilePreview.tsx"
click node_boards "https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/Boards.tsx"
click node_planner_chat "https://github.com/brahimaann/sanktuary-os/tree/main/src/apps"
click node_creative_apps "https://github.com/brahimaann/sanktuary-os/tree/main/src/apps"
click node_paint "https://github.com/brahimaann/sanktuary-os/blob/main/public/programs/jspaint/src/app.js"
click node_api "https://github.com/brahimaann/sanktuary-os/blob/main/src/utils/api.ts"
click node_live "https://github.com/brahimaann/sanktuary-os/blob/main/src/utils/live.ts"
click node_vfs "https://github.com/brahimaann/sanktuary-os/blob/main/src/vfs/fs.ts"
click node_server "https://github.com/brahimaann/sanktuary-os/blob/main/server/index.mjs"

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_public_content,node_cities,node_shop toneBlue
class node_app,node_desktop,node_window_manager toneAmber
class node_team_files,node_file_preview,node_boards,node_planner_chat,node_creative_apps,node_paint toneMint
class node_api,node_live,node_vfs,node_server,node_clerk toneRose
class node_visitor,node_member toneIndigo
```

## Components

### Public Hub

- [Arts & Music](https://github.com/brahimaann/sanktuary-os/tree/main/src/apps): `src/apps`
- [CITIES Journal](https://github.com/brahimaann/sanktuary-os/tree/main/ops/nodes): `ops/nodes`
- [Shop](https://github.com/brahimaann/sanktuary-os/tree/main/src/apps): `src/apps`

### Member Desktop

- [Sanktuary App](https://github.com/brahimaann/sanktuary-os/blob/main/src/App.tsx): `src/App.tsx`
- [Desktop](https://github.com/brahimaann/sanktuary-os/blob/main/src/components/Desktop.tsx): `src/components/Desktop.tsx`
- [Window Manager](https://github.com/brahimaann/sanktuary-os/blob/main/src/wm/manager.ts): `src/wm/manager.ts`

### Creative Workspaces

- [Team Files](https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/TeamFiles.tsx): `src/apps/TeamFiles.tsx`
- [File Preview](https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/FilePreview.tsx): `src/apps/FilePreview.tsx`
- [Moodboards](https://github.com/brahimaann/sanktuary-os/blob/main/src/apps/Boards.tsx): `src/apps/Boards.tsx`
- [Planner & Chat](https://github.com/brahimaann/sanktuary-os/tree/main/src/apps): `src/apps`
- [Creative Apps](https://github.com/brahimaann/sanktuary-os/tree/main/src/apps): `src/apps`
- [JS Paint](https://github.com/brahimaann/sanktuary-os/blob/main/public/programs/jspaint/src/app.js): `public/programs/jspaint/src/app.js`

### Platform Services

- [API Client](https://github.com/brahimaann/sanktuary-os/blob/main/src/utils/api.ts): `src/utils/api.ts`
- [Live Events](https://github.com/brahimaann/sanktuary-os/blob/main/src/utils/live.ts): `src/utils/live.ts`
- [Virtual Filesystem](https://github.com/brahimaann/sanktuary-os/blob/main/src/vfs/fs.ts): `src/vfs/fs.ts`
- [Node Server](https://github.com/brahimaann/sanktuary-os/blob/main/server/index.mjs): `server/index.mjs`
- **Clerk Sign-in**

### Other components

- **Visitor**
- **Member**

## Connections

- Visitor → Arts & Music: explores
- Visitor → CITIES Journal: reads
- Visitor → Shop: shops
- Member → Clerk Sign-in: signs in
- Member → Desktop: works in
- Clerk Sign-in → API Client: provides session
- Sanktuary App → Window Manager: reads windows (evidence: `src/App.tsx`)
- Sanktuary App → Desktop: renders (evidence: `src/App.tsx`)
- Desktop → Window Manager: opens windows (evidence: `src/components/Desktop.tsx`)
- Desktop → API Client: fetches member data (evidence: `src/components/Desktop.tsx`)
- Desktop → Live Events: starts connection (evidence: `src/components/Desktop.tsx`)
- Desktop → Virtual Filesystem: syncs notes (evidence: `src/components/Desktop.tsx`)
- Team Files → API Client: fetches files (evidence: `src/apps/TeamFiles.tsx`)
- Team Files → File Preview: opens preview (evidence: `src/apps/TeamFiles.tsx`)
- File Preview → Team Files: gets file URL (evidence: `src/apps/FilePreview.tsx`)
- File Preview → API Client: fetches metadata (evidence: `src/apps/FilePreview.tsx`)
- API Client → Node Server: sends API requests (evidence: `src/utils/api.ts`)
- Live Events → Node Server: receives events (evidence: `src/utils/live.ts`)
- Member → Moodboards: creates moodboards
- Member → Planner & Chat: collaborates
- Member → Creative Apps: uses apps
- Creative Apps → JS Paint: includes
