# yugienugraha/ruang architecture

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

- Interactive diagram: https://gitdiagram.com/yugienugraha/ruang
- Repository: https://github.com/yugienugraha/ruang

## Overview

Ruang is a read-only mission-control web app for local Hermes agents and optional OpenCode. The main workflow is to open the office dashboard, which presents crew and work state, then inspect agents, tasks, schedules, usage, activity, memory, folders, or logs. Server-side collectors read local CLI and file data; the browser presents it through pages and a 2D/3D office. Access and profile locks protect private views. The source index identifies the principal modules, but most server routing and collector call paths were not excerpted, so those links are limited to documented relationships.

Main entry points: [`src/App.tsx`](https://github.com/yugienugraha/ruang/blob/main/src/App.tsx) (App shell), [`src/pages/Office.tsx`](https://github.com/yugienugraha/ruang/blob/main/src/pages/Office.tsx) (Office dashboard), [`server/index.ts`](https://github.com/yugienugraha/ruang/blob/main/server/index.ts) (HTTP server), [`src/pages/Office3D.tsx`](https://github.com/yugienugraha/ruang/blob/main/src/pages/Office3D.tsx) (3D office view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_officepage["Office dashboard<br/>[Office.tsx]"]
  node_agents["Agents page<br/>[Agents.tsx]"]
  node_tasks["Task board<br/>[TaskBoard.tsx]"]
  node_calendar["Cron calendar<br/>[Calendar.tsx]"]
  node_activity["Activity page<br/>[Activity.tsx]"]
  node_usage["Usage views<br/>[TokenUsage.tsx]"]
  node_memory["Memory browser<br/>[Memory.tsx]"]
  node_folders["Folder browser<br/>[Folders.tsx]"]
  node_logs["Logs page<br/>[Logs.tsx]"]
end

subgraph group_office["Office visualization"]
  node_office3d["3D office view<br/>[Office3D.tsx]"]
  node_layout["Office layout<br/>[office3d-layout.ts]"]
  node_environment["Scene environment<br/>[environment.tsx]"]
  node_props["Scene props<br/>[props.tsx]"]
  node_textures["Procedural textures<br/>[textures.ts]"]
end

subgraph group_collect["Read-only collection"]
  node_server["HTTP server<br/>[index.ts]"]
  node_mission["Mission data<br/>[mission-control.ts]"]
  node_folderdata["Folder reads<br/>[folders.ts]"]
  node_memorydata["Memory reads<br/>[memory.ts]"]
end

subgraph group_privacy["Privacy controls"]
  node_access["Access codes<br/>[access.ts]"]
  node_profilelock["Profile locks<br/>[profile-lock.ts]"]
  node_privacydata["Privacy policy<br/>[privacy.ts]"]
  node_clientaccess["Access UI<br/>[access.ts]"]
  node_clientlock["Profile lock UI<br/>[ProfileLock.tsx]"]
end

node_user(("Operator"))
node_hermes{{"Hermes CLI"}}

node_user -->|"opens"| node_app
node_app -->|"renders"| node_officepage
node_app -->|"renders"| node_agents
node_app -->|"renders"| node_tasks
node_app -->|"renders"| node_calendar
node_app -->|"renders"| node_activity
node_app -->|"renders"| node_memory
node_app -->|"renders"| node_folders
node_app -->|"renders"| node_logs
node_officepage -->|"embeds"| node_tasks
node_officepage -->|"embeds"| node_calendar
node_officepage -->|"embeds"| node_usage
node_officepage -->|"opens"| node_memory
node_officepage -->|"opens"| node_folders
node_officepage -->|"shows"| node_office3d
node_office3d -->|"uses"| node_layout
node_office3d -->|"renders"| node_environment
node_environment -->|"renders"| node_props
node_environment -->|"uses"| node_textures
node_props -->|"uses"| node_textures
node_server -.->|"serves reads"| node_mission
node_server -.->|"serves reads"| node_folderdata
node_server -.->|"serves reads"| node_memorydata
node_mission -->|"reads CLI"| node_hermes
node_folderdata -.->|"reads files"| node_hermes
node_memorydata -.->|"reads files"| node_hermes
node_server -.->|"provides access"| node_access
node_server -.->|"provides locks"| node_profilelock
node_privacydata -.->|"protects"| node_memorydata
node_clientaccess -->|"requests access"| node_access
node_clientlock -.->|"controls locks"| node_profilelock

click node_app "https://github.com/yugienugraha/ruang/blob/main/src/App.tsx"
click node_officepage "https://github.com/yugienugraha/ruang/blob/main/src/pages/Office.tsx"
click node_agents "https://github.com/yugienugraha/ruang/blob/main/src/pages/Agents.tsx"
click node_tasks "https://github.com/yugienugraha/ruang/blob/main/src/pages/TaskBoard.tsx"
click node_calendar "https://github.com/yugienugraha/ruang/blob/main/src/pages/Calendar.tsx"
click node_activity "https://github.com/yugienugraha/ruang/blob/main/src/pages/Activity.tsx"
click node_usage "https://github.com/yugienugraha/ruang/blob/main/src/pages/TokenUsage.tsx"
click node_memory "https://github.com/yugienugraha/ruang/blob/main/src/pages/Memory.tsx"
click node_folders "https://github.com/yugienugraha/ruang/blob/main/src/pages/Folders.tsx"
click node_logs "https://github.com/yugienugraha/ruang/blob/main/src/pages/Logs.tsx"
click node_office3d "https://github.com/yugienugraha/ruang/blob/main/src/pages/Office3D.tsx"
click node_layout "https://github.com/yugienugraha/ruang/blob/main/src/office3d-layout.ts"
click node_environment "https://github.com/yugienugraha/ruang/blob/main/src/scene3d/environment.tsx"
click node_props "https://github.com/yugienugraha/ruang/blob/main/src/scene3d/props.tsx"
click node_textures "https://github.com/yugienugraha/ruang/blob/main/src/scene3d/textures.ts"
click node_server "https://github.com/yugienugraha/ruang/blob/main/server/index.ts"
click node_mission "https://github.com/yugienugraha/ruang/blob/main/server/mission-control.ts"
click node_folderdata "https://github.com/yugienugraha/ruang/blob/main/server/folders.ts"
click node_memorydata "https://github.com/yugienugraha/ruang/blob/main/server/memory.ts"
click node_access "https://github.com/yugienugraha/ruang/blob/main/server/access.ts"
click node_profilelock "https://github.com/yugienugraha/ruang/blob/main/server/profile-lock.ts"
click node_privacydata "https://github.com/yugienugraha/ruang/blob/main/server/privacy.ts"
click node_clientaccess "https://github.com/yugienugraha/ruang/blob/main/src/access.ts"
click node_clientlock "https://github.com/yugienugraha/ruang/blob/main/src/ProfileLock.tsx"

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_app,node_officepage,node_agents,node_tasks,node_calendar,node_activity,node_usage,node_memory,node_folders,node_logs toneBlue
class node_office3d,node_layout,node_environment,node_props,node_textures toneAmber
class node_server,node_mission,node_folderdata,node_memorydata toneMint
class node_access,node_profilelock,node_privacydata,node_clientaccess,node_clientlock toneRose
class node_user,node_hermes toneIndigo
```

## Components

### Web experience

- [App shell](https://github.com/yugienugraha/ruang/blob/main/src/App.tsx): `src/App.tsx`
- [Office dashboard](https://github.com/yugienugraha/ruang/blob/main/src/pages/Office.tsx): `src/pages/Office.tsx`
- [Agents page](https://github.com/yugienugraha/ruang/blob/main/src/pages/Agents.tsx): `src/pages/Agents.tsx`
- [Task board](https://github.com/yugienugraha/ruang/blob/main/src/pages/TaskBoard.tsx): `src/pages/TaskBoard.tsx`
- [Cron calendar](https://github.com/yugienugraha/ruang/blob/main/src/pages/Calendar.tsx): `src/pages/Calendar.tsx`
- [Activity page](https://github.com/yugienugraha/ruang/blob/main/src/pages/Activity.tsx): `src/pages/Activity.tsx`
- [Usage views](https://github.com/yugienugraha/ruang/blob/main/src/pages/TokenUsage.tsx): `src/pages/TokenUsage.tsx`
- [Memory browser](https://github.com/yugienugraha/ruang/blob/main/src/pages/Memory.tsx): `src/pages/Memory.tsx`
- [Folder browser](https://github.com/yugienugraha/ruang/blob/main/src/pages/Folders.tsx): `src/pages/Folders.tsx`
- [Logs page](https://github.com/yugienugraha/ruang/blob/main/src/pages/Logs.tsx): `src/pages/Logs.tsx`

### Office visualization

- [3D office view](https://github.com/yugienugraha/ruang/blob/main/src/pages/Office3D.tsx): `src/pages/Office3D.tsx`
- [Office layout](https://github.com/yugienugraha/ruang/blob/main/src/office3d-layout.ts): `src/office3d-layout.ts`
- [Scene environment](https://github.com/yugienugraha/ruang/blob/main/src/scene3d/environment.tsx): `src/scene3d/environment.tsx`
- [Scene props](https://github.com/yugienugraha/ruang/blob/main/src/scene3d/props.tsx): `src/scene3d/props.tsx`
- [Procedural textures](https://github.com/yugienugraha/ruang/blob/main/src/scene3d/textures.ts): `src/scene3d/textures.ts`

### Read-only collection

- [HTTP server](https://github.com/yugienugraha/ruang/blob/main/server/index.ts): `server/index.ts`
- [Mission data](https://github.com/yugienugraha/ruang/blob/main/server/mission-control.ts): `server/mission-control.ts`
- [Folder reads](https://github.com/yugienugraha/ruang/blob/main/server/folders.ts): `server/folders.ts`
- [Memory reads](https://github.com/yugienugraha/ruang/blob/main/server/memory.ts): `server/memory.ts`

### Privacy controls

- [Access codes](https://github.com/yugienugraha/ruang/blob/main/server/access.ts): `server/access.ts`
- [Profile locks](https://github.com/yugienugraha/ruang/blob/main/server/profile-lock.ts): `server/profile-lock.ts`
- [Privacy policy](https://github.com/yugienugraha/ruang/blob/main/server/privacy.ts): `server/privacy.ts`
- [Access UI](https://github.com/yugienugraha/ruang/blob/main/src/access.ts): `src/access.ts`
- [Profile lock UI](https://github.com/yugienugraha/ruang/blob/main/src/ProfileLock.tsx): `src/ProfileLock.tsx`

### Other components

- **Operator**
- **Hermes CLI**

## Connections

- Operator → App shell: opens (evidence: `README.md`)
- App shell → Office dashboard: renders (evidence: `src/App.tsx`)
- App shell → Agents page: renders (evidence: `src/App.tsx`)
- App shell → Task board: renders (evidence: `src/App.tsx`)
- App shell → Cron calendar: renders (evidence: `src/App.tsx`)
- App shell → Activity page: renders (evidence: `src/App.tsx`)
- App shell → Memory browser: renders (evidence: `src/App.tsx`)
- App shell → Folder browser: renders (evidence: `src/App.tsx`)
- App shell → Logs page: renders (evidence: `src/App.tsx`)
- Office dashboard → Task board: embeds (evidence: `src/pages/Office.tsx`)
- Office dashboard → Cron calendar: embeds (evidence: `src/pages/Office.tsx`)
- Office dashboard → Usage views: embeds (evidence: `src/pages/Office.tsx`)
- Office dashboard → Memory browser: opens (evidence: `src/pages/Office.tsx`)
- Office dashboard → Folder browser: opens (evidence: `src/pages/Office.tsx`)
- Office dashboard → 3D office view: shows (evidence: `src/pages/Office.tsx`)
- 3D office view → Office layout: uses (evidence: `src/pages/Office3D.tsx`)
- 3D office view → Scene environment: renders (evidence: `src/pages/Office3D.tsx`)
- Scene environment → Scene props: renders (evidence: `src/scene3d/environment.tsx`)
- Scene environment → Procedural textures: uses (evidence: `src/scene3d/environment.tsx`)
- Scene props → Procedural textures: uses (evidence: `src/scene3d/props.tsx`)
- HTTP server → Mission data: serves reads (evidence: `server/index.ts`)
- HTTP server → Folder reads: serves reads (evidence: `server/index.ts`)
- HTTP server → Memory reads: serves reads (evidence: `server/index.ts`)
- Mission data → Hermes CLI: reads CLI (evidence: `README.md`)
- Folder reads → Hermes CLI: reads files
- Memory reads → Hermes CLI: reads files
- HTTP server → Access codes: provides access (evidence: `server/index.ts`)
- HTTP server → Profile locks: provides locks (evidence: `server/index.ts`)
- Privacy policy → Memory reads: protects (evidence: `server/privacy.ts`)
- Access UI → Access codes: requests access (evidence: `src/access.ts`)
- Profile lock UI → Profile locks: controls locks
