Add system architecture document

docs/alpha/Calypso_System_Architecture.md

@@ -0,0 +1,102 @@
+# Calypso System Architecture Document
+Adastra Storage & Backup Appliance  
+Version: 1.0 (Dev Release V1)  
+Status: Baseline Architecture  
+
+## 1. Purpose & Scope
+This document describes the system architecture of Calypso as an integrated storage and backup appliance. It aligns with the System Requirements Specification (SRS) and System Design Specification (SDS), and serves as a reference for architects, engineers, operators, and auditors.
+
+## 2. Architectural Principles
+- Appliance-first design
+- Clear separation of binaries, configuration, and data
+- ZFS-native storage architecture
+- Upgrade and rollback safety
+- Minimal external dependencies
+
+## 3. High-Level Architecture
+Calypso operates as a single-node appliance where the control plane orchestrates storage, backup, object storage, tape, and iSCSI subsystems through a unified API and UI.
+
+## 4. Deployment Model
+- Single-node deployment
+- Bare metal or VM (bare metal recommended)
+- Linux-based OS (LTS)
+
+## 5. Centralized Filesystem Architecture
+
+### 5.1 Domain Separation
+| Domain | Location |
+|------|---------|
+| Binaries | /opt/adastra/calypso |
+| Configuration | /etc/calypso |
+| Data (ZFS) | /srv/calypso |
+| Logs | /var/log/calypso |
+| Runtime | /var/lib/calypso, /run/calypso |
+
+### 5.2 Binary Layout
+```
+/opt/adastra/calypso/
+  releases/
+    1.0.0/
+      bin/
+      web/
+      migrations/
+      scripts/
+  current -> releases/1.0.0
+  third_party/
+```
+
+### 5.3 Configuration Layout
+```
+/etc/calypso/
+  calypso.yaml
+  secrets.env
+  tls/
+  integrations/
+  system/
+```
+
+### 5.4 ZFS Data Layout
+```
+/srv/calypso/
+  db/
+  backups/
+  object/
+  shares/
+  vtl/
+  iscsi/
+  uploads/
+  cache/
+  _system/
+```
+
+## 6. Component Architecture
+- Calypso Control Plane (Go-based API)
+- ZFS (core storage)
+- Bacula (backup)
+- MinIO (object storage)
+- SCST (iSCSI)
+- MHVTL (virtual tape library)
+
+## 7. Data Flow
+- User actions handled by Calypso API
+- Operations executed on ZFS datasets
+- Metadata stored centrally in ZFS
+
+## 8. Security Baseline
+- Service isolation
+- Permission-based filesystem access
+- Secrets separation
+- Controlled subsystem access
+
+## 9. Upgrade & Rollback
+- Versioned releases
+- Atomic switch via symlink
+- Data preserved independently in ZFS
+
+## 10. Non-Goals (V1)
+- Multi-node clustering
+- Kubernetes orchestration
+- Inline malware scanning
+
+## 11. Summary
+Calypso provides a clean, upgrade-safe, and enterprise-grade appliance architecture, forming a strong foundation for future HA and immutable designs.