tidy up documentation for alpha release

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

@@ -0,0 +1,182 @@
+# 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 |
+