# sleuth-io/sx architecture

> Architecture diagram of the GitHub repository sleuth-io/sx, 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/sleuth-io/sx
- Repository: https://github.com/sleuth-io/sx

## Overview

sx is a shared library for capturing, versioning, governing, and distributing AI assets—skills, rules, agents, commands, hooks, MCP servers, and plugins—to AI clients. Users enter through either the desktop app or CLI. The central workflow adds assets to a vault, then installs them to selected scopes and clients; governance, team/bot management, usage reporting, and cloud MCP access are additional branches. Relationships below rely on the README and SOURCE INDEX references; several implementation details were not sampled, so those links are omitted.

Main entry points: [`internal/vault/repository.go`](https://github.com/sleuth-io/sx/blob/main/internal/vault/repository.go) (Vault storage), [`internal/commands/install_context.go`](https://github.com/sleuth-io/sx/blob/main/internal/commands/install_context.go) (Install workflow), [`app/main.go`](https://github.com/sleuth-io/sx/blob/main/app/main.go) (Desktop app), [`internal/commands/add.go`](https://github.com/sleuth-io/sx/blob/main/internal/commands/add.go) (Add assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontdoors["User interfaces"]
  node_desktop["Desktop app<br/>[main.go]"]
  node_library_ui["Library workspace<br/>[Library.tsx]"]
  node_onboarding["Vault onboarding<br/>[Onboarding.tsx]"]
  node_cli["sx CLI<br/>[main.go]"]
  node_commands["CLI commands<br/>[commands.go]"]
end

subgraph group_assets["Asset lifecycle"]
  node_asset_add["Add assets<br/>[add.go]"]
  node_manifest["Asset manifest<br/>[manifest.go]"]
  node_vault[("Vault storage<br/>[repository.go]")]
  node_versioning[("Version storage<br/>[storage.go]")]
  node_publish["Publish assets<br/>[publish.go]"]
end

subgraph group_distribution["Installation"]
  node_scope["Install scopes<br/>[scope.go]"]
  node_install["Install workflow<br/>[install_context.go]"]
  node_client_registry["Client registry<br/>[registry.go]"]
  node_client_adapters["AI client adapters<br/>[client.go]"]
end

subgraph group_governance["Teams and governance"]
  node_teams_bots["Teams and bots<br/>[teams.go]"]
  node_audit["Audit trail<br/>[audit.go]"]
  node_usage["Usage reporting<br/>[queue.go]"]
end

subgraph group_integrations["External integrations"]
  node_cloud_mcp["Cloud MCP relay<br/>[bridge.go]"]
  node_ai_clients(("AI tools"))
  node_shared_folder[("Synced team folder")]
  node_web_ai(("Web AI services"))
end

node_user(("User or automation"))

node_user -->|"opens app"| node_desktop
node_user -->|"runs commands"| node_cli
node_desktop -->|"sets up vault"| node_onboarding
node_desktop -->|"opens library"| node_library_ui
node_user -->|"adds assets"| node_asset_add
node_cli -->|"dispatches"| node_commands
node_commands -->|"routes add"| node_asset_add
node_asset_add -->|"stores assets"| node_vault
node_vault -->|"tracks metadata"| node_manifest
node_vault -->|"stores versions"| node_versioning
node_vault -->|"uses as vault"| node_shared_folder
node_user -->|"publishes assets"| node_publish
node_user -->|"requests installs"| node_install
node_install -->|"resolves target"| node_scope
node_install -->|"loads assets"| node_vault
node_install -->|"selects clients"| node_client_registry
node_client_registry -->|"dispatches installs"| node_client_adapters
node_client_adapters -->|"writes native assets"| node_ai_clients
node_user -->|"manages access"| node_teams_bots
node_user -->|"reviews changes"| node_audit
node_ai_clients -.->|"reports adoption"| node_usage
node_user -->|"starts relay"| node_cloud_mcp
node_cloud_mcp -->|"serves vault content"| node_vault
node_web_ai -->|"requests MCP"| node_cloud_mcp

click node_desktop "https://github.com/sleuth-io/sx/blob/main/app/main.go"
click node_library_ui "https://github.com/sleuth-io/sx/blob/main/app/frontend/src/screens/Library.tsx"
click node_onboarding "https://github.com/sleuth-io/sx/blob/main/app/frontend/src/screens/Onboarding.tsx"
click node_cli "https://github.com/sleuth-io/sx/blob/main/cmd/sx/main.go"
click node_commands "https://github.com/sleuth-io/sx/blob/main/internal/commands/commands.go"
click node_asset_add "https://github.com/sleuth-io/sx/blob/main/internal/commands/add.go"
click node_manifest "https://github.com/sleuth-io/sx/blob/main/internal/manifest/manifest.go"
click node_vault "https://github.com/sleuth-io/sx/blob/main/internal/vault/repository.go"
click node_versioning "https://github.com/sleuth-io/sx/blob/main/internal/vault/storage.go"
click node_publish "https://github.com/sleuth-io/sx/blob/main/internal/publish/publish.go"
click node_scope "https://github.com/sleuth-io/sx/blob/main/internal/scope/scope.go"
click node_install "https://github.com/sleuth-io/sx/blob/main/internal/commands/install_context.go"
click node_client_registry "https://github.com/sleuth-io/sx/blob/main/internal/clients/registry.go"
click node_client_adapters "https://github.com/sleuth-io/sx/blob/main/internal/clients/client.go"
click node_teams_bots "https://github.com/sleuth-io/sx/blob/main/internal/mgmt/teams.go"
click node_audit "https://github.com/sleuth-io/sx/blob/main/internal/mgmt/audit.go"
click node_usage "https://github.com/sleuth-io/sx/blob/main/internal/stats/queue.go"
click node_cloud_mcp "https://github.com/sleuth-io/sx/blob/main/internal/cloud/bridge.go"

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,node_library_ui,node_onboarding,node_cli,node_commands,node_user toneBlue
class node_asset_add,node_manifest,node_vault,node_versioning,node_publish toneAmber
class node_scope,node_install,node_client_registry,node_client_adapters toneMint
class node_teams_bots,node_audit,node_usage toneRose
class node_cloud_mcp,node_ai_clients,node_shared_folder,node_web_ai toneIndigo
```

## Components

### User interfaces

- [Desktop app](https://github.com/sleuth-io/sx/blob/main/app/main.go): `app/main.go`
- [Library workspace](https://github.com/sleuth-io/sx/blob/main/app/frontend/src/screens/Library.tsx): `app/frontend/src/screens/Library.tsx`
- [Vault onboarding](https://github.com/sleuth-io/sx/blob/main/app/frontend/src/screens/Onboarding.tsx): `app/frontend/src/screens/Onboarding.tsx`
- [sx CLI](https://github.com/sleuth-io/sx/blob/main/cmd/sx/main.go): `cmd/sx/main.go`
- [CLI commands](https://github.com/sleuth-io/sx/blob/main/internal/commands/commands.go): `internal/commands/commands.go`

### Asset lifecycle

- [Add assets](https://github.com/sleuth-io/sx/blob/main/internal/commands/add.go): `internal/commands/add.go`
- [Asset manifest](https://github.com/sleuth-io/sx/blob/main/internal/manifest/manifest.go): `internal/manifest/manifest.go`
- [Vault storage](https://github.com/sleuth-io/sx/blob/main/internal/vault/repository.go): `internal/vault/repository.go`
- [Version storage](https://github.com/sleuth-io/sx/blob/main/internal/vault/storage.go): `internal/vault/storage.go`
- [Publish assets](https://github.com/sleuth-io/sx/blob/main/internal/publish/publish.go): `internal/publish/publish.go`

### Installation

- [Install scopes](https://github.com/sleuth-io/sx/blob/main/internal/scope/scope.go): `internal/scope/scope.go`
- [Install workflow](https://github.com/sleuth-io/sx/blob/main/internal/commands/install_context.go): `internal/commands/install_context.go`
- [Client registry](https://github.com/sleuth-io/sx/blob/main/internal/clients/registry.go): `internal/clients/registry.go`
- [AI client adapters](https://github.com/sleuth-io/sx/blob/main/internal/clients/client.go): `internal/clients/client.go`

### Teams and governance

- [Teams and bots](https://github.com/sleuth-io/sx/blob/main/internal/mgmt/teams.go): `internal/mgmt/teams.go`
- [Audit trail](https://github.com/sleuth-io/sx/blob/main/internal/mgmt/audit.go): `internal/mgmt/audit.go`
- [Usage reporting](https://github.com/sleuth-io/sx/blob/main/internal/stats/queue.go): `internal/stats/queue.go`

### External integrations

- [Cloud MCP relay](https://github.com/sleuth-io/sx/blob/main/internal/cloud/bridge.go): `internal/cloud/bridge.go`
- **AI tools**
- **Synced team folder**
- **Web AI services**

### Other components

- **User or automation**

## Connections

- User or automation → Desktop app: opens app (evidence: `README.md`)
- User or automation → sx CLI: runs commands (evidence: `README.md`)
- Desktop app → Vault onboarding: sets up vault (evidence: `README.md`)
- Desktop app → Library workspace: opens library
- User or automation → Add assets: adds assets (evidence: `README.md`)
- sx CLI → CLI commands: dispatches (evidence: `cmd/sx/main.go`)
- CLI commands → Add assets: routes add (evidence: `README.md`)
- Add assets → Vault storage: stores assets (evidence: `README.md`)
- Vault storage → Asset manifest: tracks metadata (evidence: `internal/vault/repository.go`)
- Vault storage → Version storage: stores versions (evidence: `README.md`)
- Vault storage → Synced team folder: uses as vault (evidence: `README.md`)
- User or automation → Publish assets: publishes assets (evidence: `README.md`)
- User or automation → Install workflow: requests installs (evidence: `README.md`)
- Install workflow → Install scopes: resolves target (evidence: `internal/commands/install_context.go`)
- Install workflow → Vault storage: loads assets (evidence: `internal/commands/install_context.go`)
- Install workflow → Client registry: selects clients (evidence: `internal/commands/install_context.go`)
- Client registry → AI client adapters: dispatches installs
- AI client adapters → AI tools: writes native assets (evidence: `README.md`)
- User or automation → Teams and bots: manages access (evidence: `README.md`)
- User or automation → Audit trail: reviews changes (evidence: `README.md`)
- AI tools → Usage reporting: reports adoption
- User or automation → Cloud MCP relay: starts relay (evidence: `README.md`)
- Cloud MCP relay → Vault storage: serves vault content (evidence: `README.md`)
- Web AI services → Cloud MCP relay: requests MCP (evidence: `README.md`)
