# mrtwister99-png/loyo-os architecture

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

- Interactive diagram: https://gitdiagram.com/mrtwister99-png/loyo-os
- Repository: https://github.com/mrtwister99-png/loyo-os

## Overview

LOYO OS is a locally run, manifest-driven agent workspace: users manage capabilities and personal work in a Tauri/React desktop app, while API orchestration routes commands to agents and local models and persists results as files. The graph preserves documented agent commands, capability builders, RAG/search, scheduling, MCP, and reporting branches. Source samples establish the UI-to-file path and orchestrator internals; many API routes and tool implementations were not sampled, so their internal wiring is intentionally left broad or unconnected.

Main entry points: [`apps/api/src/services/orchestrator.ts`](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/orchestrator.ts) (Agent orchestrator), [`apps/web/src/lib/dataPaths.ts`](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/lib/dataPaths.ts) (Notes and tasks), [`apps/web/src/App.tsx`](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/App.tsx) (Desktop UI), [`apps/web/src-tauri/src/main.rs`](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src-tauri/src/main.rs) (Desktop filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workspace"]
  node_desktop_ui["Desktop UI<br/>[App.tsx]"]
  node_task_page["Tasks editor<br/>[Tasks.tsx]"]
  node_file_list["File-backed lists"]
  node_tauri["Desktop filesystem<br/>[main.rs]"]
end

subgraph group_backend["API and agents"]
  node_api_entry["API service<br/>[index.ts]"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.ts]"]
  node_model_router["Model routing<br/>[modelRouter.ts]"]
  node_activity["Activity feed<br/>[activity.ts]"]
  node_run_logs["Run logging<br/>[runLogger.ts]"]
  node_scheduler["Scheduler<br/>[scheduler.ts]"]
  node_search_routes["Search routes<br/>[search.ts]"]
  node_rag_routes["RAG routes<br/>[rag.ts]"]
  node_cap_routes["Capability routes<br/>[capabilities.ts]"]
  node_mcp_routes["MCP routes<br/>[mcp.ts]"]
end

subgraph group_data["Manifest and data"]
  node_manifest_core["Manifest schema<br/>[schema.ts]"]
  node_manifest_loader["Manifest loader<br/>[loader.ts]"]
  node_file_data["Capability files<br/>[dataPaths.ts]"]
  node_personal_files["Notes and tasks<br/>[dataPaths.ts]"]
  node_fts[("Text search index<br/>[notesTasksFts.ts]")]
  node_leads_reports["Leads and reports<br/>[orchestrator.ts]"]
end

subgraph group_integrations["Model and tools"]
  node_mcp_server["MCP server<br/>[server.ts]"]
  node_mcp_tools["MCP tools<br/>[index.ts]"]
  node_ollama["Local Ollama"]
  node_web_search["Web research<br/>[web_search.ts]"]
  node_firm_cli["Company lookup CLI<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_desktop_ui
node_desktop_ui -->|"shows"| node_task_page
node_task_page -->|"invokes file commands"| node_tauri
node_file_list -->|"invokes file commands"| node_tauri
node_tauri -->|"reads and writes"| node_personal_files
node_desktop_ui -.->|"API requests"| node_api_entry
node_api_entry -->|"dispatches chat"| node_orchestrator
node_orchestrator -->|"selects model"| node_model_router
node_orchestrator -->|"generates replies"| node_ollama
node_orchestrator -->|"logs activity"| node_activity
node_orchestrator -->|"logs runs"| node_run_logs
node_orchestrator -->|"reads manifests"| node_file_data
node_orchestrator -->|"reads and writes"| node_personal_files
node_orchestrator -.->|"runs company lookup"| node_firm_cli
node_orchestrator -.->|"requests research"| node_web_search
node_orchestrator -->|"writes results"| node_leads_reports
node_scheduler -->|"persists notifications"| node_personal_files
node_search_routes -->|"searches notes/tasks"| node_fts
node_fts -->|"indexes files"| node_personal_files
node_rag_routes -->|"manages RAG manifests"| node_file_data
node_cap_routes -->|"loads capabilities"| node_manifest_loader
node_manifest_loader -->|"validates against"| node_manifest_core
node_mcp_server -->|"dispatches tool calls"| node_mcp_tools
node_mcp_routes -.->|"serves MCP"| node_mcp_server

click node_desktop_ui "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/App.tsx"
click node_task_page "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/pages/Tasks.tsx"
click node_file_list "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/hooks/useFileBackedList.ts"
click node_tauri "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src-tauri/src/main.rs"
click node_api_entry "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/index.ts"
click node_orchestrator "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/orchestrator.ts"
click node_model_router "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/modelRouter.ts"
click node_activity "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/activity.ts"
click node_run_logs "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/runLogger.ts"
click node_scheduler "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/scheduler.ts"
click node_search_routes "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/search.ts"
click node_rag_routes "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/rag.ts"
click node_cap_routes "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/capabilities.ts"
click node_mcp_routes "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/mcp.ts"
click node_mcp_server "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/mcp/src/server.ts"
click node_mcp_tools "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/mcp/src/tools/index.ts"
click node_manifest_core "https://github.com/mrtwister99-png/loyo-os/blob/main/packages/core/src/manifest/schema.ts"
click node_manifest_loader "https://github.com/mrtwister99-png/loyo-os/blob/main/packages/core/src/manifest/loader.ts"
click node_file_data "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/lib/dataPaths.ts"
click node_personal_files "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/lib/dataPaths.ts"
click node_fts "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/lib/notesTasksFts.ts"
click node_web_search "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/web_search.ts"
click node_firm_cli "https://github.com/mrtwister99-png/loyo-os/blob/main/tools/cli/firmy/index.ts"
click node_leads_reports "https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/orchestrator.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_desktop_ui,node_task_page,node_file_list,node_tauri,node_user toneBlue
class node_api_entry,node_orchestrator,node_model_router,node_activity,node_run_logs,node_scheduler,node_search_routes,node_rag_routes,node_cap_routes,node_mcp_routes toneAmber
class node_manifest_core,node_manifest_loader,node_file_data,node_personal_files,node_fts,node_leads_reports toneMint
class node_mcp_server,node_mcp_tools,node_ollama,node_web_search,node_firm_cli toneRose
```

## Components

### Desktop workspace

- [Desktop UI](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Tasks editor](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/pages/Tasks.tsx): `apps/web/src/pages/Tasks.tsx`
- [File-backed lists](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/hooks/useFileBackedList.ts): `apps/web/src/hooks/useFileBackedList.ts`
- [Desktop filesystem](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src-tauri/src/main.rs): `apps/web/src-tauri/src/main.rs`

### API and agents

- [API service](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Agent orchestrator](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/orchestrator.ts): `apps/api/src/services/orchestrator.ts`
- [Model routing](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/modelRouter.ts): `apps/api/src/services/modelRouter.ts`
- [Activity feed](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/activity.ts): `apps/api/src/routes/activity.ts`
- [Run logging](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/runLogger.ts): `apps/api/src/services/runLogger.ts`
- [Scheduler](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/scheduler.ts): `apps/api/src/services/scheduler.ts`
- [Search routes](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/search.ts): `apps/api/src/routes/search.ts`
- [RAG routes](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/rag.ts): `apps/api/src/routes/rag.ts`
- [Capability routes](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/capabilities.ts): `apps/api/src/routes/capabilities.ts`
- [MCP routes](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/routes/mcp.ts): `apps/api/src/routes/mcp.ts`

### Manifest and data

- [Manifest schema](https://github.com/mrtwister99-png/loyo-os/blob/main/packages/core/src/manifest/schema.ts): `packages/core/src/manifest/schema.ts`
- [Manifest loader](https://github.com/mrtwister99-png/loyo-os/blob/main/packages/core/src/manifest/loader.ts): `packages/core/src/manifest/loader.ts`
- [Capability files](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/lib/dataPaths.ts): `apps/api/src/lib/dataPaths.ts`
- [Notes and tasks](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/web/src/lib/dataPaths.ts): `apps/web/src/lib/dataPaths.ts`
- [Text search index](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/lib/notesTasksFts.ts): `apps/api/src/lib/notesTasksFts.ts`
- [Leads and reports](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/orchestrator.ts): `apps/api/src/services/orchestrator.ts`

### Model and tools

- [MCP server](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/mcp/src/server.ts): `apps/mcp/src/server.ts`
- [MCP tools](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/mcp/src/tools/index.ts): `apps/mcp/src/tools/index.ts`
- **Local Ollama**
- [Web research](https://github.com/mrtwister99-png/loyo-os/blob/main/apps/api/src/services/web_search.ts): `apps/api/src/services/web_search.ts`
- [Company lookup CLI](https://github.com/mrtwister99-png/loyo-os/blob/main/tools/cli/firmy/index.ts): `tools/cli/firmy/index.ts`

### Other components

- **User**

## Connections

- User → Desktop UI: uses
- Desktop UI → Tasks editor: shows
- Tasks editor → Desktop filesystem: invokes file commands
- File-backed lists → Desktop filesystem: invokes file commands
- Desktop filesystem → Notes and tasks: reads and writes
- Desktop UI → API service: API requests
- API service → Agent orchestrator: dispatches chat
- Agent orchestrator → Model routing: selects model
- Agent orchestrator → Local Ollama: generates replies
- Agent orchestrator → Activity feed: logs activity
- Agent orchestrator → Run logging: logs runs
- Agent orchestrator → Capability files: reads manifests
- Agent orchestrator → Notes and tasks: reads and writes
- Agent orchestrator → Company lookup CLI: runs company lookup
- Agent orchestrator → Web research: requests research
- Agent orchestrator → Leads and reports: writes results
- Scheduler → Notes and tasks: persists notifications
- Search routes → Text search index: searches notes/tasks
- Text search index → Notes and tasks: indexes files
- RAG routes → Capability files: manages RAG manifests
- Capability routes → Manifest loader: loads capabilities
- Manifest loader → Manifest schema: validates against
- MCP server → MCP tools: dispatches tool calls
- MCP routes → MCP server: serves MCP