# AtlasOS – Calypso  
## Engineering & Architecture Master Document  
### (CURSOR.md – Single Source of Truth)

Version: 2.0  
Status: Baseline – Product Definition  
Target OS: Ubuntu Server 24.04 LTS  
Category: Backup Appliance / Tape & VTL Virtualization Platform  
Date: 2025

---

## 0. Project Definition

**AtlasOS – Calypso** adalah **generic backup appliance** yang menyediakan:

- Disk-based backup storage (iSCSI block)
- Physical tape library bridging (SAS / FC → iSCSI)
- Virtual Tape Library (VTL) menggunakan **MHVTL**
- Unified web-based management GUI
- Authentication, authorization, audit, dan monitoring terpusat

Calypso **tidak terikat pada backup software tertentu**.

Backup software yang didukung mencakup (namun tidak terbatas pada):
- Bacula
- Veeam
- Dell NetWorker
- Veritas NetBackup
- Commvault
- Arcserve
- Custom / proprietary SCSI-compliant backup engines

Calypso berperan sebagai **storage & SCSI virtualization appliance**, bukan backup controller.

---

## 1. Non-Negotiable Design Rules

1. **SCST adalah satu-satunya iSCSI target framework**
   - Tidak menggunakan LIO / targetcli
   - Semua disk, physical tape, dan VTL diexport melalui SCST

2. **Mapping tape device wajib konsisten**
   - LUN 0 → Medium changer
   - LUN 1..N → Tape drives (maksimal 8)
   - Berlaku untuk:
     - Physical tape library
     - MHVTL virtual library

3. **Single initiator policy untuk tape**
   - Hanya satu IQN initiator boleh login ke tape target
   - Pelanggaran harus terdeteksi dan ditampilkan di UI

4. **Backup software agnostic**
   - Tidak ada logic Bacula / NetWorker / Veeam di core
   - Hanya SCSI semantics + optional compatibility profile

5. **Tidak ada shell/terminal di UI (v1)**
   - Semua aksi melalui API tervalidasi

6. **Least privilege backend**
   - Backend berjalan sebagai non-root
   - Aksi privileged via polkit atau sudoers allowlist ketat

7. **Audit wajib**
   - Setiap perubahan konfigurasi
   - Operasi tape
   - Apply iSCSI
   - Perubahan IAM

8. **Operasi berat bersifat async**
   - Inventory
   - Load / unload
   - Rescan
   - Apply SCST
   - Support bundle

---

## 2. Core Appliance Capabilities

### 2.1 Disk Storage
- LVM-backed repository
- Optional ZFS (advanced SKU)
- Export sebagai iSCSI block device
- Digunakan untuk:
  - Disk backup target
  - Backing store MHVTL

### 2.2 Physical Tape Bridge (SAS / FC)
- Discovery changer & drive
- Inventory slot & barcode
- Load / unload tape
- Bridge ke backup software via iSCSI

### 2.3 Virtual Tape Library (MHVTL)
- Virtual changer, drive, slot, dan tape
- Disk-backed tape image
- Barcode emulation
- Export via SCST iSCSI
- Use case:
  - Backup staging
  - Copy-to-tape
  - Testing / development
  - Air-gap simulation

---

## 3. High-Level Architecture

Backup Software (Any Vendor)
|
iSCSI
|
+--------------------------------+
| AtlasOS – Calypso |
| |
| Disk Repository (LUN) |
| MHVTL (Virtual Tape) |
| Physical Tape Bridge |
| SCST iSCSI Core |
| |
+--------------------------------+
|
SAS / FC
|
Physical Tape Library

---

## 4. Component List (Authoritative)

### 4.1 Base Platform
- Ubuntu Server 24.04 LTS
- systemd, journald
- udev persistent naming
- chrony
- ufw / nftables

### 4.2 Disk Storage Layer
- LVM2
- thin-provisioning-tools
- XFS (primary)
- ext4 (alternative)
- Optional ZFS
- smartmontools, nvme-cli
- parted, gdisk

### 4.3 Physical Tape Subsystem
- SAS / FC HBA drivers
- multipath-tools (optional)
- lsscsi
- sg3_utils
- mt-st
- mtx

### 4.4 Virtual Tape Library
- mhvtl
- mhvtl-utils / vtlcmd
- Disk-backed tape images

### 4.5 iSCSI Target Stack
- scst
- iscsi-scst
- scstadmin

### 4.6 Calypso Core Application
**Backend (Go):**
- storage
- tape_physical
- tape_vtl
- scst
- iscsi
- tasks
- system
- monitoring
- audit
- profile_engine

**Frontend (React + Vite):**
- Dashboard
- Disk Repository
- Physical Tape
- Virtual Tape Library
- iSCSI Targets
- Clients / Initiators
- Tasks & Jobs
- Alerts & Logs
- System & IAM

### 4.7 Authentication & IAM
- PostgreSQL
- Local auth (Argon2id)
- LDAP
- OIDC SSO
- RBAC
- Audit log

### 4.8 Monitoring & Observability
- Built-in health checks
- Alerts engine
- Event stream (WebSocket)
- Optional Prometheus exporter
- node_exporter

### 4.9 Web & Security Perimeter
- Caddy (recommended) / Nginx
- TLS
- Security headers
- Rate limiting

### 4.10 Packaging & Operations
- Debian packages (.deb)
- systemd services:
  - calypso-api
  - scst
  - mhvtl
  - postgresql
  - caddy/nginx
- Installer & upgrade scripts
- Support bundle generator

---

## 5. Repository Structure (Monorepo)

calypso/
README.md
CURSOR.md

docs/
COMPONENT-LIST-AtlasOS-Calypso.md
SRS-00-Main-AtlasOS-Calypso.md
SRS-01-Storage-Component.md
SRS-02-VTL-and-Tape-Bridge.md
SRS-03-System-Management.md
SRS-04-Auth-and-IAM.md
SRS-05-Monitoring-and-Observability.md

frontend/
backend/
deploy/

---

## 6. API Design Rules

- Base path `/api/v1`
- JSON only
- RBAC + audit untuk endpoint mutating
- Async → `task_id`
- Task status → `/api/v1/tasks/{id}`
- WebSocket `/ws`:
  - task progress
  - alerts
  - inventory
  - iSCSI session changes

---

## 7. Database Scope (PostgreSQL)

Digunakan untuk:
- Users, roles, permissions
- Sessions & tokens
- Audit log
- Appliance configuration
- Async task state
- Alerts

Tidak digunakan untuk:
- Backup data
- Tape data

---

## 8. Coding Standards

### Backend
- Go ≥ 1.22
- Context everywhere
- No raw shell execution
- Strict validation
- Unit tests untuk:
  - SCST config
  - Tape discovery
  - Task state machine
  - RBAC

### Frontend
- TypeScript strict
- API via `src/api`
- No business logic di component
- Unified error handling
- WebSocket reconnect handling

---

## 9. Safety & Guardrails

- Blok aksi berbahaya saat tape aktif
- Cegah:
  - multi-initiator tape
  - remove active drive
  - reconfig SCST saat write
- Konfirmasi wajib untuk destructive action

---

## 10. Implementation Phases

1. Foundation & Auth
2. Disk Repository
3. Physical Tape Bridge
4. Virtual Tape Library (MHVTL)
5. Monitoring & IAM extensions
6. UI polish & hardening

---

## 11. Definition of Done (DoD)

Feature dianggap selesai jika:
- API implemented
- RBAC enforced
- Audit logged
- UI workflow complete
- Error handled
- Docs updated

---

## 12. Final Authority

Jika ada konflik antar dokumen:  
**FILE INI ADALAH SUMBER KEBENARAN.**

AtlasOS – Calypso adalah **tape & VTL appliance kelas enterprise**.