calypso/docs/alpha/sds/SDS-00-Overview.md

Software Design Specification (SDS)

AtlasOS - Calypso Backup Appliance

Alpha Release

Version: 1.0.0-alpha
Date: 2025-01-XX
Status: In Development

---

1. Introduction

1.1 Purpose

This document provides a comprehensive Software Design Specification (SDS) for AtlasOS - Calypso, describing the system architecture, component design, database schema, API design, and implementation details.

1.2 Scope

This SDS covers:

• System architecture and design patterns
• Component structure and organization
• Database schema and data models
• API design and endpoints
• Security architecture
• Deployment architecture
• Integration patterns

1.3 Document Organization

• SDS-01: System Architecture
• SDS-02: Backend Design
• SDS-03: Frontend Design
• SDS-04: Database Design
• SDS-05: API Design
• SDS-06: Security Design
• SDS-07: Integration Design

---

2. System Architecture Overview

2.1 High-Level Architecture

Calypso follows a three-tier architecture:

1. Presentation Layer: React-based SPA
2. Application Layer: Go-based REST API
3. Data Layer: PostgreSQL database

2.2 Architecture Patterns

• Clean Architecture: Separation of concerns, domain-driven design
• RESTful API: Resource-based API design
• Repository Pattern: Data access abstraction
• Service Layer: Business logic encapsulation
• Middleware Pattern: Cross-cutting concerns

2.3 Technology Stack

Backend

• Language: Go 1.21+
• Framework: Gin web framework
• Database: PostgreSQL 14+
• Authentication: JWT tokens
• Logging: Zerolog structured logging

Frontend

• Framework: React 18 with TypeScript
• Build Tool: Vite
• Styling: TailwindCSS
• State Management: Zustand + TanStack Query
• Routing: React Router
• HTTP Client: Axios

---

3. Design Principles

3.1 Separation of Concerns

• Clear boundaries between layers
• Single responsibility principle
• Dependency inversion

3.2 Scalability

• Stateless API design
• Horizontal scaling capability
• Efficient database queries

3.3 Security

• Defense in depth
• Principle of least privilege
• Input validation and sanitization

3.4 Maintainability

• Clean code principles
• Comprehensive logging
• Error handling
• Code documentation

3.5 Performance

• Response caching
• Database query optimization
• Efficient data structures
• Background job processing

---

4. System Components

4.1 Backend Components

• Auth: Authentication and authorization
• Storage: ZFS and storage management
• Shares: SMB/NFS share management
• SCST: iSCSI target management
• Tape: Physical and VTL management
• Backup: Bacula/Bareos integration
• System: System service management
• Monitoring: Metrics and alerting
• IAM: User and access management

4.2 Frontend Components

• Pages: Route-based page components
• Components: Reusable UI components
• API: API client and queries
• Store: Global state management
• Hooks: Custom React hooks
• Utils: Utility functions

---

5. Data Flow

5.1 Request Flow

1. User action in frontend
2. API call via Axios
3. Request middleware (auth, logging, rate limiting)
4. Handler processes request
5. Service layer business logic
6. Database operations
7. Response returned to frontend
8. UI update via React Query

5.2 Background Jobs

• Disk monitoring (every 5 minutes)
• ZFS pool monitoring (every 2 minutes)
• Metrics collection (every 30 seconds)
• Alert rule evaluation (continuous)

---

6. Deployment Architecture

6.1 Single-Server Deployment

• Backend API service (systemd)
• Frontend static files (nginx/caddy)
• PostgreSQL database
• External services (ZFS, SCST, Bacula)

6.2 Service Management

• Systemd service files
• Auto-restart on failure
• Log rotation
• Health checks

---

7. Future Enhancements

7.1 Scalability

• Multi-server deployment
• Load balancing
• Database replication
• Distributed caching

7.2 Features

• WebSocket real-time updates
• GraphQL API option
• Microservices architecture
• Container orchestration

---

Document History

Version	Date	Author	Changes
1.0.0-alpha	2025-01-XX	Development Team	Initial SDS document