# AtlasOS – Calypso Architecture Diagrams

## 1) System Context (High-Level)

```mermaid
flowchart LR
  subgraph Client["Backup Software Client (Any Vendor)"]
    C1["Backup Server / VM\n(Bacula / Veeam / NetWorker / NetBackup / etc)"]
  end

  subgraph Net["Backup Network"]
    ISCSI["iSCSI (TCP/3260)\nInitiator Sessions"]
    HTTPS["HTTPS (TCP/443)\nAdmin GUI/API"]
  end

  subgraph Calypso["AtlasOS – Calypso Appliance (Ubuntu 24.04)"]
    RP["Reverse Proxy\n(Caddy/Nginx)"]
    UI["Web GUI\n(React + Vite)"]
    API["Calypso Core API\n(Go REST + WebSocket)"]
    DB["PostgreSQL\n(IAM + Audit + Tasks + Alerts)"]
    SCST["SCST iSCSI Target Core\n(scst + iscsi-scst + scstadmin)"]
    DISK["Disk Storage Layer\n(LVM + XFS)\nBackup Repo + VTL Backing"]
    MHVTL["MHVTL Engine\n(Virtual Changer/Drives/Slots/Tapes)"]
    TOOLS["Tape Tools\n(lsscsi, sg3_utils, mtx, mt)"]
  end

  subgraph Fabric["SAS/FC Fabric"]
    HBA["SAS/FC HBA"]
  end

  subgraph Phys["Physical Tape Library"]
    CHG["Medium Changer"]
    DRV["Tape Drives (LTO-8)\nMax 8 presented"]
    SLOTS["Slots + Barcodes"]
  end

  C1 --> ISCSI --> SCST
  C1 --> HTTPS --> RP
  RP --> UI
  RP --> API
  API --> DB
  API --> SCST
  API --> DISK
  API --> MHVTL
  API --> TOOLS

  SCST --> DISK
  SCST --> MHVTL

  TOOLS --> HBA --> CHG
  TOOLS --> HBA --> DRV
  HBA --> SLOTS

flowchart TB
  subgraph ControlPlane["Control Plane"]
    RP["Reverse Proxy\n(Caddy/Nginx)"]
    UI["Web GUI\nReact + Vite"]
    API["Calypso Core API (Go)\nREST + WS"]
    IAM["IAM Module\nLocal + LDAP + OIDC"]
    MON["Monitoring Module\nHealth + Alerts + Metrics"]
    TASKS["Task Engine\nAsync Ops + Progress"]
    AUDIT["Audit Engine\nAppend-only"]
    DB["PostgreSQL\nUsers/Roles/Sessions\nTasks/Alerts/Audit\nConfig State"]
  end

  subgraph DataPlane["Data Plane (Storage/SCSI)"]
    SCST["SCST Target Core\niscsi-scst + scstadmin"]
    DISK["Disk Repo\nLVM + XFS"]
    MHVTL["MHVTL VTL\nVirtual Changer/Drives/Slots"]
    PHYS["Physical Tape\nSAS/FC Changer + Drives"]
    TOOLS["Tape Ops Tools\nlsscsi/sg3_utils/mtx/mt"]
  end

  RP --> UI
  RP --> API

  API --> IAM
  API --> MON
  API --> TASKS
  API --> AUDIT
  IAM --> DB
  MON --> DB
  TASKS --> DB
  AUDIT --> DB

  API --> SCST
  API --> DISK
  API --> MHVTL
  API --> TOOLS

  SCST --> DISK
  SCST --> MHVTL

  TOOLS --> PHYS
  API --> PHYS

flowchart LR
  subgraph Initiator["Backup Software (Initiator)"]
    BSVR["Backup Server/VM\n(any vendor)"]
  end

  subgraph Targets["Calypso iSCSI Targets (SCST)"]
    TDISK["Target: Disk Repository\nIQN: calypso.repo\nLUN 0: Disk LUN"]
    TPHYS["Target: Physical Tape Bridge\nIQN: calypso.tape.phys\nLUN 0: Changer\nLUN 1..8: Drives"]
    TVTL["Target: Virtual Tape Library\nIQN: calypso.tape.vtl\nLUN 0: VTL Changer\nLUN 1..N: VTL Drives"]
  end

  subgraph Backing["Backing Devices"]
    DISK["LVM/XFS Repo LUN"]
    PHYCHG["Physical Changer (SAS/FC)"]
    PHYDRV["Physical Drives (LTO-8)"]
    VTLCHG["MHVTL Changer"]
    VTLDRV["MHVTL Drives"]
    VTLDATA["Disk-backed Tape Images\n(under repo/pool)"]
  end

  BSVR --> TDISK
  BSVR --> TPHYS
  BSVR --> TVTL

  TDISK --> DISK

  TPHYS --> PHYCHG
  TPHYS --> PHYDRV

  TVTL --> VTLCHG
  TVTL --> VTLDRV
  VTLDRV --> VTLDATA

sequenceDiagram
  autonumber
  participant UI as Web GUI
  participant API as Calypso API (Go)
  participant DB as PostgreSQL
  participant SCST as SCST (iSCSI Target)
  participant MHVTL as MHVTL
  participant TOOLS as Tape Tools (mtx/mt/sg3)
  participant WS as WebSocket Stream

  UI->>API: POST /api/v1/tape/inventory (physical or vtl)
  API->>DB: create task (inventory)
  API-->>UI: 202 Accepted + task_id
  API->>WS: publish task_started(task_id)

  alt Physical inventory
    API->>TOOLS: run inventory (mtx/sg3)
    TOOLS-->>API: inventory result
  else VTL inventory
    API->>MHVTL: vtlcmd inventory
    MHVTL-->>API: inventory result
  end

  API->>DB: update task result + state=success
  API->>WS: publish task_progress + task_success
  UI->>WS: receive updates (realtime)

  UI->>API: POST /api/v1/iscsi/apply
  API->>DB: audit + task (apply scst)
  API->>SCST: scstadmin apply config (validate/rollback)
  SCST-->>API: apply result
  API->>WS: publish iscsi_apply_result



