add instruction and srs

2025-12-24 23:55:55 +07:00
commit 0537709576
31 changed files with 6611 additions and 0 deletions
--- a/src/srs-technical-spec-documents/CURSOR.md
+++ b/src/srs-technical-spec-documents/CURSOR.md
@@ -0,0 +1,339 @@
+# 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**.