# shogo-labs/shogo-ai architecture

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

- Interactive diagram: https://gitdiagram.com/shogo-labs/shogo-ai
- Repository: https://github.com/shogo-labs/shogo-ai

## Overview

Shogo is a platform for building and operating AI agents, combining client apps, a Hono API, agent and project runtimes, and an SDK. A typical workflow starts in a client, reaches the API for platform orchestration, then runs agent work and project code in separate runtime layers. The repository also includes bare-metal VM execution, real-time sync, and SDK memory search. The README supports the platform-level links; sampled source supports runtime configuration and sync-client behavior. Unsampled route and service internals limit finer-grained call links.

Main entry points: [`apps/api/src/server.ts`](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/server.ts) (Hono API), [`apps/api/src/lib/runtime/manager.ts`](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/manager.ts) (Workspace runtime), [`apps/mobile/app/(app)/index.tsx`](https://github.com/shogo-labs/shogo-ai/blob/main/apps/mobile/app/(app)/index.tsx) (Mobile client), [`apps/desktop/src/main.ts`](https://github.com/shogo-labs/shogo-ai/blob/main/apps/desktop/src/main.ts) (Desktop client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_mobile["Mobile client<br/>[index.tsx]"]
  node_desktop["Desktop client<br/>[main.ts]"]
end

subgraph group_control["Platform control"]
  node_api["Hono API<br/>[server.ts]"]
  node_api_auth["Authentication<br/>[auth.ts]"]
  node_api_routes["API routes"]
  node_prisma[("Database adapter<br/>[prisma.ts]")]
  node_project_settings["Project settings"]
  node_agent_defaults["Agent model defaults"]
  node_federation["Cloud federation"]
end

subgraph group_execution["Runtime execution"]
  node_agent_runtime["Agent runtime<br/>[index-engine.ts]"]
  node_preview_runtime["Preview manager<br/>[preview-manager.ts]"]
  node_workspace_runtime["Workspace runtime<br/>[manager.ts]"]
  node_workspace_env["Workspace environment"]
  node_remote_ssh["Remote SSH<br/>[remote-runtime.ts]"]
  node_metal_vm["Metal VM manager"]
end

subgraph group_storage["Sync and data"]
  node_sync_hook["Sync hook<br/>[useSyncClient.ts]"]
  node_sync_client["Sync client<br/>[sync-client.ts]"]
end

subgraph group_developer["Developer SDK"]
  node_memory_search["Memory search<br/>[engine.ts]"]
  node_sdk_routes["Route generator"]
end

node_user(("Platform user"))
node_integrations{{"External integrations"}}

node_user -->|"uses"| node_mobile
node_user -->|"uses"| node_desktop
node_mobile -.->|"API requests"| node_api
node_desktop -.->|"API requests"| node_api
node_api -.->|"authenticates"| node_api_auth
node_api -.->|"routes requests"| node_api_routes
node_api -.->|"persists data"| node_prisma
node_api -->|"orchestrates"| node_workspace_runtime
node_api -->|"runs agents"| node_agent_runtime
node_workspace_runtime -->|"builds environment"| node_workspace_env
node_workspace_runtime -->|"resolves defaults"| node_agent_defaults
node_agent_defaults -->|"fetches defaults"| node_federation
node_agent_runtime -->|"uses tools"| node_integrations
node_workspace_runtime -->|"manages remote"| node_remote_ssh
node_integrations -.->|"runs on"| node_metal_vm
node_sync_hook -->|"creates and connects"| node_sync_client
node_memory_search -.->|"searches memory"| node_integrations
node_sdk_routes -.->|"supports integration"| node_api

click node_mobile "https://github.com/shogo-labs/shogo-ai/blob/main/apps/mobile/app/(app)/index.tsx"
click node_desktop "https://github.com/shogo-labs/shogo-ai/blob/main/apps/desktop/src/main.ts"
click node_api "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/server.ts"
click node_api_auth "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/auth.ts"
click node_api_routes "https://github.com/shogo-labs/shogo-ai/tree/main/apps/api/src/routes"
click node_prisma "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/prisma.ts"
click node_project_settings "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/project-settings.ts"
click node_agent_defaults "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/agent-model-defaults.ts"
click node_federation "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/federated-upstream.ts"
click node_agent_runtime "https://github.com/shogo-labs/shogo-ai/blob/main/packages/agent-runtime/src/index-engine.ts"
click node_preview_runtime "https://github.com/shogo-labs/shogo-ai/blob/main/packages/agent-runtime/src/preview-manager.ts"
click node_workspace_runtime "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/manager.ts"
click node_workspace_env "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/build-workspace-env.ts"
click node_remote_ssh "https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/remote-ssh/remote-runtime.ts"
click node_metal_vm "https://github.com/shogo-labs/shogo-ai/blob/main/apps/metal-agent/src/firecracker-vm-manager.ts"
click node_sync_hook "https://github.com/shogo-labs/shogo-ai/blob/main/packages/shared-app/src/hooks/useSyncClient.ts"
click node_sync_client "https://github.com/shogo-labs/shogo-ai/blob/main/packages/shared-app/src/services/sync-client.ts"
click node_memory_search "https://github.com/shogo-labs/shogo-ai/blob/main/packages/sdk/src/memory/engine.ts"
click node_sdk_routes "https://github.com/shogo-labs/shogo-ai/blob/main/packages/sdk/src/generators/routes-generator.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_mobile,node_desktop,node_user toneBlue
class node_api,node_api_auth,node_api_routes,node_prisma,node_project_settings,node_agent_defaults,node_federation toneAmber
class node_agent_runtime,node_preview_runtime,node_workspace_runtime,node_workspace_env,node_remote_ssh,node_metal_vm toneMint
class node_sync_hook,node_sync_client toneRose
class node_memory_search,node_sdk_routes,node_integrations toneIndigo
```

## Components

### Client apps

- [Mobile client](https://github.com/shogo-labs/shogo-ai/blob/main/apps/mobile/app/(app)/index.tsx): `apps/mobile/app/(app)/index.tsx`
- [Desktop client](https://github.com/shogo-labs/shogo-ai/blob/main/apps/desktop/src/main.ts): `apps/desktop/src/main.ts`

### Platform control

- [Hono API](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/server.ts): `apps/api/src/server.ts`
- [Authentication](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/auth.ts): `apps/api/src/auth.ts`
- [API routes](https://github.com/shogo-labs/shogo-ai/tree/main/apps/api/src/routes): `apps/api/src/routes`
- [Database adapter](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/prisma.ts): `apps/api/src/lib/prisma.ts`
- [Project settings](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/project-settings.ts): `apps/api/src/lib/project-settings.ts`
- [Agent model defaults](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/agent-model-defaults.ts): `apps/api/src/lib/runtime/agent-model-defaults.ts`
- [Cloud federation](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/federated-upstream.ts): `apps/api/src/lib/federated-upstream.ts`

### Runtime execution

- [Agent runtime](https://github.com/shogo-labs/shogo-ai/blob/main/packages/agent-runtime/src/index-engine.ts): `packages/agent-runtime/src/index-engine.ts`
- [Preview manager](https://github.com/shogo-labs/shogo-ai/blob/main/packages/agent-runtime/src/preview-manager.ts): `packages/agent-runtime/src/preview-manager.ts`
- [Workspace runtime](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/manager.ts): `apps/api/src/lib/runtime/manager.ts`
- [Workspace environment](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/runtime/build-workspace-env.ts): `apps/api/src/lib/runtime/build-workspace-env.ts`
- [Remote SSH](https://github.com/shogo-labs/shogo-ai/blob/main/apps/api/src/lib/remote-ssh/remote-runtime.ts): `apps/api/src/lib/remote-ssh/remote-runtime.ts`
- [Metal VM manager](https://github.com/shogo-labs/shogo-ai/blob/main/apps/metal-agent/src/firecracker-vm-manager.ts): `apps/metal-agent/src/firecracker-vm-manager.ts`

### Sync and data

- [Sync hook](https://github.com/shogo-labs/shogo-ai/blob/main/packages/shared-app/src/hooks/useSyncClient.ts): `packages/shared-app/src/hooks/useSyncClient.ts`
- [Sync client](https://github.com/shogo-labs/shogo-ai/blob/main/packages/shared-app/src/services/sync-client.ts): `packages/shared-app/src/services/sync-client.ts`

### Developer SDK

- [Memory search](https://github.com/shogo-labs/shogo-ai/blob/main/packages/sdk/src/memory/engine.ts): `packages/sdk/src/memory/engine.ts`
- [Route generator](https://github.com/shogo-labs/shogo-ai/blob/main/packages/sdk/src/generators/routes-generator.ts): `packages/sdk/src/generators/routes-generator.ts`

### Other components

- **Platform user**
- **External integrations**

## Connections

- Platform user → Mobile client: uses (evidence: `README.md`)
- Platform user → Desktop client: uses (evidence: `README.md`)
- Mobile client → Hono API: API requests
- Desktop client → Hono API: API requests
- Hono API → Authentication: authenticates
- Hono API → API routes: routes requests
- Hono API → Database adapter: persists data
- Hono API → Workspace runtime: orchestrates (evidence: `README.md`)
- Hono API → Agent runtime: runs agents (evidence: `README.md`)
- Workspace runtime → Workspace environment: builds environment (evidence: `apps/api/src/lib/runtime/manager.ts`)
- Workspace runtime → Agent model defaults: resolves defaults (evidence: `apps/api/src/lib/runtime/manager.ts`)
- Agent model defaults → Cloud federation: fetches defaults (evidence: `apps/api/src/lib/runtime/agent-model-defaults.ts`)
- Agent runtime → External integrations: uses tools (evidence: `README.md`)
- Workspace runtime → Remote SSH: manages remote (evidence: `apps/api/src/lib/runtime/manager.ts`)
- External integrations → Metal VM manager: runs on
- Sync hook → Sync client: creates and connects (evidence: `packages/shared-app/src/hooks/useSyncClient.ts`)
- Memory search → External integrations: searches memory
- Route generator → Hono API: supports integration
