calypso/docs/alpha/sds/SDS-01-System-Architecture.md

SDS-01: System Architecture

1. Architecture Overview

1.1 Three-Tier Architecture

┌─────────────────────────────────────┐
│      Presentation Layer             │
│      (React SPA)                    │
└──────────────┬──────────────────────┘
               │ HTTP/REST
┌──────────────▼──────────────────────┐
│      Application Layer               │
│      (Go REST API)                   │
└──────────────┬──────────────────────┘
               │ SQL
┌──────────────▼──────────────────────┐
│      Data Layer                      │
│      (PostgreSQL)                    │
└─────────────────────────────────────┘

1.2 Component Layers

Backend Layers

1. Handler Layer: HTTP request handling, validation
2. Service Layer: Business logic, orchestration
3. Repository Layer: Data access, database operations
4. Model Layer: Data structures, domain models

Frontend Layers

1. Page Layer: Route-based page components
2. Component Layer: Reusable UI components
3. API Layer: API client, data fetching
4. Store Layer: Global state management

2. Backend Architecture

2.1 Directory Structure

backend/
├── cmd/
│   └── calypso-api/
│       └── main.go
├── internal/
│   ├── auth/
│   ├── storage/
│   ├── shares/
│   ├── scst/
│   ├── tape_physical/
│   ├── tape_vtl/
│   ├── backup/
│   ├── system/
│   ├── monitoring/
│   ├── iam/
│   ├── tasks/
│   └── common/
│       ├── config/
│       ├── database/
│       ├── logger/
│       ├── router/
│       └── cache/
└── db/
    └── migrations/

2.2 Module Organization

Each module follows this structure:

• handler.go: HTTP handlers
• service.go: Business logic
• model.go: Data models (if needed)
• repository.go: Database operations (if needed)

2.3 Common Components

• config: Configuration management
• database: Database connection and migrations
• logger: Structured logging
• router: HTTP router, middleware
• cache: Response caching
• auth: Authentication middleware
• audit: Audit logging middleware

3. Frontend Architecture

3.1 Directory Structure

frontend/
├── src/
│   ├── pages/
│   ├── components/
│   ├── api/
│   ├── store/
│   ├── hooks/
│   ├── lib/
│   └── App.tsx
└── public/

3.2 Component Organization

• pages/: Route-based page components
• components/: Reusable UI components
  • ui/: Base UI components (buttons, inputs, etc.)
  • Layout.tsx: Main layout component
• api/: API client and query definitions
• store/: Zustand stores
• hooks/: Custom React hooks
• lib/: Utility functions

4. Request Processing Flow

4.1 HTTP Request Flow

Client Request
    ↓
CORS Middleware
    ↓
Rate Limiting Middleware
    ↓
Security Headers Middleware
    ↓
Cache Middleware (if enabled)
    ↓
Audit Logging Middleware
    ↓
Authentication Middleware
    ↓
Permission Middleware
    ↓
Handler
    ↓
Service
    ↓
Database
    ↓
Response

4.2 Error Handling Flow

Error Occurred
    ↓
Service Layer Error
    ↓
Handler Error Handling
    ↓
Error Response Formatting
    ↓
HTTP Error Response
    ↓
Frontend Error Handling
    ↓
User Notification

5. Background Services

5.1 Monitoring Services

• Disk Monitor: Syncs disk information every 5 minutes
• ZFS Pool Monitor: Syncs ZFS pool status every 2 minutes
• Metrics Service: Collects system metrics every 30 seconds
• Alert Rule Engine: Continuously evaluates alert rules

5.2 Event System

• Event Hub: Broadcasts events to subscribers
• Metrics Broadcaster: Broadcasts metrics to WebSocket clients
• Alert Service: Processes alerts and notifications

6. Data Flow Patterns

6.1 Read Operations

Frontend Query
    ↓
API Call
    ↓
Handler
    ↓
Service
    ↓
Database Query
    ↓
Response
    ↓
React Query Cache
    ↓
UI Update

6.2 Write Operations

Frontend Mutation
    ↓
API Call
    ↓
Handler (Validation)
    ↓
Service (Business Logic)
    ↓
Database Transaction
    ↓
Cache Invalidation
    ↓
Response
    ↓
React Query Invalidation
    ↓
UI Update

7. Integration Points

7.1 External System Integrations

• ZFS: Command-line tools (zpool, zfs)
• SCST: Configuration files and commands
• Bacula/Bareos: Database and bconsole commands
• MHVTL: Configuration and control
• Systemd: Service management

7.2 Integration Patterns

• Command Execution: Execute system commands
• File Operations: Read/write configuration files
• Database Access: Direct database queries (Bacula)
• API Calls: HTTP API calls (future)

8. Security Architecture

8.1 Authentication Flow

Login Request
    ↓
Credential Validation
    ↓
JWT Token Generation
    ↓
Token Response
    ↓
Token Storage (Frontend)
    ↓
Token in Request Headers
    ↓
Token Validation (Middleware)
    ↓
Request Processing

8.2 Authorization Flow

Authenticated Request
    ↓
User Role Retrieval
    ↓
Permission Check
    ↓
Resource Access Check
    ↓
Request Processing or Denial

9. Caching Strategy

9.1 Response Caching

• Cacheable Endpoints: GET requests only
• Cache Keys: Based on URL and query parameters
• TTL: Configurable per endpoint
• Invalidation: On write operations

9.2 Frontend Caching

• React Query: Automatic caching and invalidation
• Stale Time: 5 minutes default
• Cache Time: 30 minutes default

10. Logging Architecture

10.1 Log Levels

• DEBUG: Detailed debugging information
• INFO: General informational messages
• WARN: Warning messages
• ERROR: Error messages

10.2 Log Structure

• Structured Logging: JSON format
• Fields: Timestamp, level, message, context
• Audit Logs: Separate audit log table

11. Error Handling Architecture

11.1 Error Types

• Validation Errors: 400 Bad Request
• Authentication Errors: 401 Unauthorized
• Authorization Errors: 403 Forbidden
• Not Found Errors: 404 Not Found
• Server Errors: 500 Internal Server Error

11.2 Error Response Format

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}