# chiranjitk/staysuite_cmc architecture

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

- Interactive diagram: https://gitdiagram.com/chiranjitk/staysuite_cmc
- Repository: https://github.com/chiranjitk/staysuite_cmc

## Overview

StaySuite CMC is a multi-tenant console for managing StaySuite devices and gateways. Operators enroll and approve devices, monitor health and alerts, issue commands, deploy configuration or software, and manage licenses and remote support. The Go agent registers with the CMC, reports heartbeats, polls for commands, and can establish a reverse SSH tunnel. The tree and sampled routes support these capabilities, but most UI-to-route wiring and several feature implementations were not sampled; those links are shown only where the product structure or excerpts support them.

Main entry points: [`web/src/lib/db.ts`](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/lib/db.ts) (Application database), [`agent/cmd/staysuite-cmc-agent/main.go`](https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/cmd/staysuite-cmc-agent/main.go) (Device agent), [`web/src/lib/tenant-context.ts`](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/lib/tenant-context.ts) (Tenant permissions), [`web/src/app/api/v1/licenses/route.ts`](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/licenses/route.ts) (License management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Management console"]
  node_console_ui["CMC console"]
  node_api["Versioned API"]
end

subgraph group_device["Device lifecycle"]
  node_enrollment_tokens["Bootstrap tokens<br/>[route.ts]"]
  node_registration["Agent registration<br/>[route.ts]"]
  node_approval["Device approval<br/>[route.ts]"]
  node_agent["Device agent<br/>[main.go]"]
  node_agent_identity["Agent identity<br/>[identity.go]"]
  node_agent_config["Agent configuration<br/>[config.go]"]
end

subgraph group_operations["Fleet operations"]
  node_heartbeat["Heartbeat intake<br/>[route.ts]"]
  node_commands["Command dispatch<br/>[route.ts]"]
  node_agent_commands["Agent command execution<br/>[commands.go]"]
  node_alerts["Alert management<br/>[route.ts]"]
  node_configuration["Configuration deployment<br/>[route.ts]"]
  node_software["Software deployment<br/>[route.ts]"]
  node_licenses["License management<br/>[route.ts]"]
  node_reports["Reports and audit"]
end

subgraph group_access["Remote access"]
  node_support_sessions["Support sessions<br/>[route.ts]"]
  node_remote_ui["Remote UI sessions<br/>[route.ts]"]
  node_tunnel_peers["Tunnel peer provisioning<br/>[route.ts]"]
  node_agent_tunnel["Reverse SSH tunnel<br/>[tunnel.go]"]
  node_ssh_service["SSH service<br/>[index.ts]"]
end

subgraph group_foundation["Shared services"]
  node_tenant_auth["Tenant permissions<br/>[tenant-context.ts]"]
  node_database[("Application database<br/>[db.ts]")]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_console_ui
node_console_ui -->|"requests"| node_api
node_api -->|"checks access"| node_tenant_auth
node_enrollment_tokens -->|"checks access"| node_tenant_auth
node_enrollment_tokens -->|"stores tokens"| node_database
node_registration -->|"validates token; records device"| node_database
node_agent -->|"loads settings"| node_agent_config
node_agent -->|"reads identity"| node_agent_identity
node_agent -->|"registers"| node_registration
node_operator -->|"approves device"| node_approval
node_approval -->|"updates device"| node_database
node_agent -->|"reports health"| node_heartbeat
node_heartbeat -->|"updates device and metrics"| node_database
node_agent -->|"polls and reports results"| node_commands
node_commands -->|"reads and updates commands"| node_database
node_agent -->|"executes commands"| node_agent_commands
node_agent_commands -->|"returns results"| node_agent
node_operator -->|"reviews alerts"| node_alerts
node_alerts -->|"reads alerts"| node_database
node_operator -->|"deploys configuration"| node_configuration
node_configuration -->|"accesses deployment data"| node_database
node_operator -->|"deploys software"| node_software
node_software -->|"accesses deployment data"| node_database
node_operator -->|"manages licenses"| node_licenses
node_licenses -->|"checks access"| node_tenant_auth
node_licenses -->|"reads and writes licenses"| node_database
node_operator -->|"views reports"| node_reports
node_reports -->|"reads reporting data"| node_database
node_operator -->|"starts support"| node_support_sessions
node_support_sessions -->|"checks access"| node_tenant_auth
node_support_sessions -->|"stores sessions"| node_database
node_operator -->|"opens session"| node_remote_ui
node_remote_ui -->|"validates session"| node_database
node_operator -->|"provisions peer"| node_tunnel_peers
node_tunnel_peers -->|"checks access"| node_tenant_auth
node_tunnel_peers -->|"stores peer"| node_database
node_agent -->|"starts tunnel"| node_agent_tunnel
node_agent_tunnel -.->|"connects"| node_ssh_service

click node_console_ui "https://github.com/chiranjitk/staysuite_cmc/tree/main/web/src/app"
click node_api "https://github.com/chiranjitk/staysuite_cmc/tree/main/web/src/app/api/v1"
click node_tenant_auth "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/lib/tenant-context.ts"
click node_database "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/lib/db.ts"
click node_enrollment_tokens "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/bootstrap-tokens/route.ts"
click node_registration "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/agent/register/route.ts"
click node_approval "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/devices/%5Bid%5D/approve/route.ts"
click node_agent "https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/cmd/staysuite-cmc-agent/main.go"
click node_agent_identity "https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/identity/identity.go"
click node_agent_config "https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/config/config.go"
click node_heartbeat "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/agent/heartbeat/route.ts"
click node_commands "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/agent/command/route.ts"
click node_agent_commands "https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/commands/commands.go"
click node_alerts "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/alerts/route.ts"
click node_configuration "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/configuration/deploy/route.ts"
click node_software "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/software/deploy/route.ts"
click node_licenses "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/licenses/route.ts"
click node_reports "https://github.com/chiranjitk/staysuite_cmc/tree/main/web/src/app/api/v1/reports"
click node_support_sessions "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/support-sessions/route.ts"
click node_remote_ui "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/remote/%5BsessionId%5D/%5B%5B...path%5D%5D/route.ts"
click node_tunnel_peers "https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/admin/tunnel-peer/route.ts"
click node_agent_tunnel "https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/tunnel/tunnel.go"
click node_ssh_service "https://github.com/chiranjitk/staysuite_cmc/blob/main/mini-services/ssh-server/index.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_console_ui,node_api toneBlue
class node_enrollment_tokens,node_registration,node_approval,node_agent,node_agent_identity,node_agent_config toneAmber
class node_heartbeat,node_commands,node_agent_commands,node_alerts,node_configuration,node_software,node_licenses,node_reports toneMint
class node_support_sessions,node_remote_ui,node_tunnel_peers,node_agent_tunnel,node_ssh_service toneRose
class node_tenant_auth,node_database,node_operator toneIndigo
```

## Components

### Management console

- [CMC console](https://github.com/chiranjitk/staysuite_cmc/tree/main/web/src/app): `web/src/app`
- [Versioned API](https://github.com/chiranjitk/staysuite_cmc/tree/main/web/src/app/api/v1): `web/src/app/api/v1`

### Device lifecycle

- [Bootstrap tokens](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/bootstrap-tokens/route.ts): `web/src/app/api/v1/bootstrap-tokens/route.ts`
- [Agent registration](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/agent/register/route.ts): `web/src/app/api/v1/agent/register/route.ts`
- [Device approval](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/devices/%5Bid%5D/approve/route.ts): `web/src/app/api/v1/devices/[id]/approve/route.ts`
- [Device agent](https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/cmd/staysuite-cmc-agent/main.go): `agent/cmd/staysuite-cmc-agent/main.go`
- [Agent identity](https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/identity/identity.go): `agent/internal/identity/identity.go`
- [Agent configuration](https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/config/config.go): `agent/internal/config/config.go`

### Fleet operations

- [Heartbeat intake](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/agent/heartbeat/route.ts): `web/src/app/api/v1/agent/heartbeat/route.ts`
- [Command dispatch](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/agent/command/route.ts): `web/src/app/api/v1/agent/command/route.ts`
- [Agent command execution](https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/commands/commands.go): `agent/internal/commands/commands.go`
- [Alert management](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/alerts/route.ts): `web/src/app/api/v1/alerts/route.ts`
- [Configuration deployment](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/configuration/deploy/route.ts): `web/src/app/api/v1/configuration/deploy/route.ts`
- [Software deployment](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/software/deploy/route.ts): `web/src/app/api/v1/software/deploy/route.ts`
- [License management](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/licenses/route.ts): `web/src/app/api/v1/licenses/route.ts`
- [Reports and audit](https://github.com/chiranjitk/staysuite_cmc/tree/main/web/src/app/api/v1/reports): `web/src/app/api/v1/reports`

### Remote access

- [Support sessions](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/support-sessions/route.ts): `web/src/app/api/v1/support-sessions/route.ts`
- [Remote UI sessions](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/remote/%5BsessionId%5D/%5B%5B...path%5D%5D/route.ts): `web/src/app/remote/[sessionId]/[[...path]]/route.ts`
- [Tunnel peer provisioning](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/app/api/v1/admin/tunnel-peer/route.ts): `web/src/app/api/v1/admin/tunnel-peer/route.ts`
- [Reverse SSH tunnel](https://github.com/chiranjitk/staysuite_cmc/blob/main/agent/internal/tunnel/tunnel.go): `agent/internal/tunnel/tunnel.go`
- [SSH service](https://github.com/chiranjitk/staysuite_cmc/blob/main/mini-services/ssh-server/index.ts): `mini-services/ssh-server/index.ts`

### Shared services

- [Tenant permissions](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/lib/tenant-context.ts): `web/src/lib/tenant-context.ts`
- [Application database](https://github.com/chiranjitk/staysuite_cmc/blob/main/web/src/lib/db.ts): `web/src/lib/db.ts`

### Other components

- **Operator**

## Connections

- Operator → CMC console: uses
- CMC console → Versioned API: requests
- Versioned API → Tenant permissions: checks access
- Bootstrap tokens → Tenant permissions: checks access
- Bootstrap tokens → Application database: stores tokens
- Agent registration → Application database: validates token; records device
- Device agent → Agent configuration: loads settings
- Device agent → Agent identity: reads identity
- Device agent → Agent registration: registers
- Operator → Device approval: approves device
- Device approval → Application database: updates device
- Device agent → Heartbeat intake: reports health
- Heartbeat intake → Application database: updates device and metrics
- Device agent → Command dispatch: polls and reports results
- Command dispatch → Application database: reads and updates commands
- Device agent → Agent command execution: executes commands
- Agent command execution → Device agent: returns results
- Operator → Alert management: reviews alerts
- Alert management → Application database: reads alerts
- Operator → Configuration deployment: deploys configuration
- Configuration deployment → Application database: accesses deployment data
- Operator → Software deployment: deploys software
- Software deployment → Application database: accesses deployment data
- Operator → License management: manages licenses
- License management → Tenant permissions: checks access
- License management → Application database: reads and writes licenses
- Operator → Reports and audit: views reports
- Reports and audit → Application database: reads reporting data
- Operator → Support sessions: starts support
- Support sessions → Tenant permissions: checks access
- Support sessions → Application database: stores sessions
- Operator → Remote UI sessions: opens session
- Remote UI sessions → Application database: validates session
- Operator → Tunnel peer provisioning: provisions peer
- Tunnel peer provisioning → Tenant permissions: checks access
- Tunnel peer provisioning → Application database: stores peer
- Device agent → Reverse SSH tunnel: starts tunnel
- Reverse SSH tunnel → SSH service: connects