# 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.
