# 1catai/1catdl architecture

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

- Interactive diagram: https://gitdiagram.com/1catai/1catdl
- Repository: https://github.com/1catai/1catdl

## Overview

1CatDL combines a self-service Gaudi2 rental platform with a separate hardware-status dashboard. The rental workflow runs from customer registration and instance selection through account-backed resource allocation, VM operation, and usage billing; administrators also manage balances, recharge codes, and accounts. The dashboard presents Gaudi telemetry and live fabric data through its own API proxies. README capabilities inform the map where excerpts do not show implementation details; those uncertain internal call links are omitted.

Main entry points: [`rental-platform/server.py`](https://github.com/1catai/1catdl/blob/main/rental-platform/server.py) (HTTP service), [`gaudi-status-panel/app/page.tsx`](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/page.tsx) (Gaudi dashboard), [`gaudi-status-panel/app/rental/page.tsx`](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/rental/page.tsx) (Rental page), [`gaudi-status-panel/components/rental/rental-panel.tsx`](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/components/rental/rental-panel.tsx) (Rental workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rental_ui["Rental interface"]
  node_rental_panel["Rental workspace<br/>[rental-panel.tsx]"]
  node_rental_page["Rental page<br/>[page.tsx]"]
end

subgraph group_rental_service["Rental services"]
  node_http_service["HTTP service<br/>[server.py]"]
  node_core["Accounts and scheduler<br/>[core.py]"]
  node_ledger[("SQLite ledger<br/>[core.py]")]
  node_recharge["Recharge codes<br/>[recharge_codes.py]"]
end

subgraph group_compute["Compute and storage"]
  node_local_backend["Local VM backend<br/>[backend.py]"]
  node_remote_backend["Node backend<br/>[remote_backend.py]"]
  node_node_agent["Node executor<br/>[node_agent.py]"]
  node_shared_storage["Public shared storage<br/>[shared_storage.py]"]
  node_host_export["Host export<br/>[host-export.py]"]
end

subgraph group_status["Gaudi status dashboard"]
  node_dashboard["Gaudi dashboard<br/>[page.tsx]"]
  node_status_proxy["Status proxy<br/>[route.ts]"]
  node_stream_proxy["Stream proxy<br/>[route.ts]"]
end

node_customer(("Customer"))
node_admin(("Administrator"))
node_hypervisor["Node hypervisor"]
node_collector["Telemetry collector"]

node_customer -->|"opens workspace"| node_rental_page
node_admin -->|"opens admin view"| node_rental_page
node_rental_page -->|"renders"| node_rental_panel
node_rental_panel -->|"sends requests"| node_http_service
node_http_service -->|"authenticates and schedules"| node_core
node_core -->|"reads and writes"| node_ledger
node_http_service -->|"operates local VMs"| node_local_backend
node_http_service -->|"selects node backend"| node_remote_backend
node_remote_backend -->|"dispatches commands"| node_node_agent
node_node_agent -->|"operates guests"| node_hypervisor
node_http_service -.->|"validates shared storage"| node_shared_storage
node_host_export -->|"validates host export"| node_shared_storage
node_customer -->|"views telemetry"| node_dashboard
node_dashboard -->|"fetches status"| node_status_proxy
node_status_proxy -->|"proxies status request"| node_collector
node_dashboard -->|"opens live stream"| node_stream_proxy
node_stream_proxy -->|"proxies event stream"| node_collector

click node_rental_panel "https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/components/rental/rental-panel.tsx"
click node_rental_page "https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/rental/page.tsx"
click node_http_service "https://github.com/1catai/1catdl/blob/main/rental-platform/server.py"
click node_core "https://github.com/1catai/1catdl/blob/main/rental-platform/core.py"
click node_ledger "https://github.com/1catai/1catdl/blob/main/rental-platform/core.py"
click node_recharge "https://github.com/1catai/1catdl/blob/main/rental-platform/recharge_codes.py"
click node_local_backend "https://github.com/1catai/1catdl/blob/main/rental-platform/backend.py"
click node_remote_backend "https://github.com/1catai/1catdl/blob/main/rental-platform/remote_backend.py"
click node_node_agent "https://github.com/1catai/1catdl/blob/main/rental-platform/node_agent.py"
click node_shared_storage "https://github.com/1catai/1catdl/blob/main/rental-platform/shared_storage.py"
click node_host_export "https://github.com/1catai/1catdl/blob/main/rental-platform/shared-storage/host-export.py"
click node_dashboard "https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/page.tsx"
click node_status_proxy "https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/api/status/route.ts"
click node_stream_proxy "https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/api/stream/route.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_rental_panel,node_rental_page toneBlue
class node_http_service,node_core,node_ledger,node_recharge toneAmber
class node_local_backend,node_remote_backend,node_node_agent,node_shared_storage,node_host_export toneMint
class node_dashboard,node_status_proxy,node_stream_proxy toneRose
class node_customer,node_admin,node_hypervisor,node_collector toneIndigo
```

## Components

### Rental interface

- [Rental workspace](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/components/rental/rental-panel.tsx): `gaudi-status-panel/components/rental/rental-panel.tsx`
- [Rental page](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/rental/page.tsx): `gaudi-status-panel/app/rental/page.tsx`

### Rental services

- [HTTP service](https://github.com/1catai/1catdl/blob/main/rental-platform/server.py): `rental-platform/server.py`
- [Accounts and scheduler](https://github.com/1catai/1catdl/blob/main/rental-platform/core.py): `rental-platform/core.py`
- [SQLite ledger](https://github.com/1catai/1catdl/blob/main/rental-platform/core.py): `rental-platform/core.py`
- [Recharge codes](https://github.com/1catai/1catdl/blob/main/rental-platform/recharge_codes.py): `rental-platform/recharge_codes.py`

### Compute and storage

- [Local VM backend](https://github.com/1catai/1catdl/blob/main/rental-platform/backend.py): `rental-platform/backend.py`
- [Node backend](https://github.com/1catai/1catdl/blob/main/rental-platform/remote_backend.py): `rental-platform/remote_backend.py`
- [Node executor](https://github.com/1catai/1catdl/blob/main/rental-platform/node_agent.py): `rental-platform/node_agent.py`
- [Public shared storage](https://github.com/1catai/1catdl/blob/main/rental-platform/shared_storage.py): `rental-platform/shared_storage.py`
- [Host export](https://github.com/1catai/1catdl/blob/main/rental-platform/shared-storage/host-export.py): `rental-platform/shared-storage/host-export.py`

### Gaudi status dashboard

- [Gaudi dashboard](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/page.tsx): `gaudi-status-panel/app/page.tsx`
- [Status proxy](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/api/status/route.ts): `gaudi-status-panel/app/api/status/route.ts`
- [Stream proxy](https://github.com/1catai/1catdl/blob/main/gaudi-status-panel/app/api/stream/route.ts): `gaudi-status-panel/app/api/stream/route.ts`

### Other components

- **Customer**
- **Administrator**
- **Node hypervisor**
- **Telemetry collector**

## Connections

- Customer → Rental page: opens workspace
- Administrator → Rental page: opens admin view
- Rental page → Rental workspace: renders
- Rental workspace → HTTP service: sends requests
- HTTP service → Accounts and scheduler: authenticates and schedules
- Accounts and scheduler → SQLite ledger: reads and writes
- HTTP service → Local VM backend: operates local VMs
- HTTP service → Node backend: selects node backend
- Node backend → Node executor: dispatches commands
- Node executor → Node hypervisor: operates guests
- HTTP service → Public shared storage: validates shared storage
- Host export → Public shared storage: validates host export
- Customer → Gaudi dashboard: views telemetry
- Gaudi dashboard → Status proxy: fetches status
- Status proxy → Telemetry collector: proxies status request
- Gaudi dashboard → Stream proxy: opens live stream
- Stream proxy → Telemetry collector: proxies event stream