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
```json
{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}
```