tidy up documentation for alpha release
This commit is contained in:
Warp Agent
302
docs/alpha/sds/SDS-01-System-Architecture.md
Normal file
302
docs/alpha/sds/SDS-01-System-Architecture.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# 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": {}
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user