tidy up documentation for alpha release
This commit is contained in:
Warp Agent
788
docs/alpha/CODING-STANDARDS.md
Normal file
788
docs/alpha/CODING-STANDARDS.md
Normal file
@@ -0,0 +1,788 @@
|
||||
# Coding Standards
|
||||
## AtlasOS - Calypso Backup Appliance
|
||||
|
||||
**Version:** 1.0.0-alpha
|
||||
**Date:** 2025-01-XX
|
||||
**Status:** Active
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document defines the coding standards and best practices for the Calypso project. All code must adhere to these standards to ensure consistency, maintainability, and quality.
|
||||
|
||||
## 2. General Principles
|
||||
|
||||
### 2.1 Code Quality
|
||||
- **Readability**: Code should be self-documenting and easy to understand
|
||||
- **Maintainability**: Code should be easy to modify and extend
|
||||
- **Consistency**: Follow consistent patterns across the codebase
|
||||
- **Simplicity**: Prefer simple solutions over complex ones
|
||||
- **DRY**: Don't Repeat Yourself - avoid code duplication
|
||||
|
||||
### 2.2 Code Review
|
||||
- All code must be reviewed before merging
|
||||
- Reviewers should check for adherence to these standards
|
||||
- Address review comments before merging
|
||||
|
||||
### 2.3 Documentation
|
||||
- Document complex logic and algorithms
|
||||
- Keep comments up-to-date with code changes
|
||||
- Write clear commit messages
|
||||
|
||||
---
|
||||
|
||||
## 3. Backend (Go) Standards
|
||||
|
||||
### 3.1 Code Formatting
|
||||
|
||||
#### 3.1.1 Use gofmt
|
||||
- Always run `gofmt` before committing
|
||||
- Use `goimports` for import organization
|
||||
- Configure IDE to format on save
|
||||
|
||||
#### 3.1.2 Line Length
|
||||
- Maximum line length: 100 characters
|
||||
- Break long lines for readability
|
||||
|
||||
#### 3.1.3 Indentation
|
||||
- Use tabs for indentation (not spaces)
|
||||
- Tab width: 4 spaces equivalent
|
||||
|
||||
### 3.2 Naming Conventions
|
||||
|
||||
#### 3.2.1 Packages
|
||||
```go
|
||||
// Good: lowercase, single word, descriptive
|
||||
package storage
|
||||
package auth
|
||||
package monitoring
|
||||
|
||||
// Bad: mixed case, abbreviations
|
||||
package Storage
|
||||
package Auth
|
||||
package Mon
|
||||
```
|
||||
|
||||
#### 3.2.2 Functions
|
||||
```go
|
||||
// Good: camelCase, descriptive
|
||||
func createZFSPool(name string) error
|
||||
func listNetworkInterfaces() ([]Interface, error)
|
||||
func validateUserInput(input string) error
|
||||
|
||||
// Bad: unclear names, abbreviations
|
||||
func create(name string) error
|
||||
func list() ([]Interface, error)
|
||||
func val(input string) error
|
||||
```
|
||||
|
||||
#### 3.2.3 Variables
|
||||
```go
|
||||
// Good: camelCase, descriptive
|
||||
var poolName string
|
||||
var networkInterfaces []Interface
|
||||
var isActive bool
|
||||
|
||||
// Bad: single letters, unclear
|
||||
var n string
|
||||
var ifs []Interface
|
||||
var a bool
|
||||
```
|
||||
|
||||
#### 3.2.4 Constants
|
||||
```go
|
||||
// Good: PascalCase for exported, camelCase for unexported
|
||||
const DefaultPort = 8080
|
||||
const maxRetries = 3
|
||||
|
||||
// Bad: inconsistent casing
|
||||
const defaultPort = 8080
|
||||
const MAX_RETRIES = 3
|
||||
```
|
||||
|
||||
#### 3.2.5 Types and Structs
|
||||
```go
|
||||
// Good: PascalCase, descriptive
|
||||
type ZFSPool struct {
|
||||
ID string
|
||||
Name string
|
||||
Status string
|
||||
}
|
||||
|
||||
// Bad: unclear names
|
||||
type Pool struct {
|
||||
I string
|
||||
N string
|
||||
S string
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 File Organization
|
||||
|
||||
#### 3.3.1 File Structure
|
||||
```go
|
||||
// 1. Package declaration
|
||||
package storage
|
||||
|
||||
// 2. Imports (standard, third-party, local)
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
|
||||
"github.com/atlasos/calypso/internal/common/database"
|
||||
)
|
||||
|
||||
// 3. Constants
|
||||
const (
|
||||
defaultTimeout = 30 * time.Second
|
||||
)
|
||||
|
||||
// 4. Types
|
||||
type Service struct {
|
||||
db *database.DB
|
||||
}
|
||||
|
||||
// 5. Functions
|
||||
func NewService(db *database.DB) *Service {
|
||||
return &Service{db: db}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.3.2 File Naming
|
||||
- Use lowercase with underscores: `handler.go`, `service.go`
|
||||
- Test files: `handler_test.go`
|
||||
- One main type per file when possible
|
||||
|
||||
### 3.4 Error Handling
|
||||
|
||||
#### 3.4.1 Error Return
|
||||
```go
|
||||
// Good: always return error as last value
|
||||
func createPool(name string) (*Pool, error) {
|
||||
if name == "" {
|
||||
return nil, fmt.Errorf("pool name cannot be empty")
|
||||
}
|
||||
// ...
|
||||
}
|
||||
|
||||
// Bad: panic, no error return
|
||||
func createPool(name string) *Pool {
|
||||
if name == "" {
|
||||
panic("pool name cannot be empty")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.4.2 Error Wrapping
|
||||
```go
|
||||
// Good: wrap errors with context
|
||||
if err != nil {
|
||||
return fmt.Errorf("failed to create pool %s: %w", name, err)
|
||||
}
|
||||
|
||||
// Bad: lose error context
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.4.3 Error Messages
|
||||
```go
|
||||
// Good: clear, actionable error messages
|
||||
return fmt.Errorf("pool '%s' already exists", name)
|
||||
return fmt.Errorf("insufficient disk space: need %d bytes, have %d bytes", needed, available)
|
||||
|
||||
// Bad: unclear error messages
|
||||
return fmt.Errorf("error")
|
||||
return fmt.Errorf("failed")
|
||||
```
|
||||
|
||||
### 3.5 Comments
|
||||
|
||||
#### 3.5.1 Package Comments
|
||||
```go
|
||||
// Package storage provides storage management functionality including
|
||||
// ZFS pool and dataset operations, disk discovery, and storage repository management.
|
||||
package storage
|
||||
```
|
||||
|
||||
#### 3.5.2 Function Comments
|
||||
```go
|
||||
// CreateZFSPool creates a new ZFS pool with the specified configuration.
|
||||
// It validates the pool name, checks disk availability, and creates the pool.
|
||||
// Returns an error if the pool cannot be created.
|
||||
func CreateZFSPool(ctx context.Context, name string, disks []string) error {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.5.3 Inline Comments
|
||||
```go
|
||||
// Good: explain why, not what
|
||||
// Retry up to 3 times to handle transient network errors
|
||||
for i := 0; i < 3; i++ {
|
||||
// ...
|
||||
}
|
||||
|
||||
// Bad: obvious comments
|
||||
// Loop 3 times
|
||||
for i := 0; i < 3; i++ {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 3.6 Testing
|
||||
|
||||
#### 3.6.1 Test File Naming
|
||||
- Test files: `*_test.go`
|
||||
- Test functions: `TestFunctionName`
|
||||
- Benchmark functions: `BenchmarkFunctionName`
|
||||
|
||||
#### 3.6.2 Test Structure
|
||||
```go
|
||||
func TestCreateZFSPool(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input string
|
||||
wantErr bool
|
||||
}{
|
||||
{
|
||||
name: "valid pool name",
|
||||
input: "tank",
|
||||
wantErr: false,
|
||||
},
|
||||
{
|
||||
name: "empty pool name",
|
||||
input: "",
|
||||
wantErr: true,
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
err := createPool(tt.input)
|
||||
if (err != nil) != tt.wantErr {
|
||||
t.Errorf("createPool() error = %v, wantErr %v", err, tt.wantErr)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.7 Concurrency
|
||||
|
||||
#### 3.7.1 Context Usage
|
||||
```go
|
||||
// Good: always accept context as first parameter
|
||||
func (s *Service) CreatePool(ctx context.Context, name string) error {
|
||||
// Use context for cancellation and timeout
|
||||
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
|
||||
defer cancel()
|
||||
// ...
|
||||
}
|
||||
|
||||
// Bad: no context
|
||||
func (s *Service) CreatePool(name string) error {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.7.2 Goroutines
|
||||
```go
|
||||
// Good: use context for cancellation
|
||||
go func() {
|
||||
ctx, cancel := context.WithCancel(ctx)
|
||||
defer cancel()
|
||||
// ...
|
||||
}()
|
||||
|
||||
// Bad: no cancellation mechanism
|
||||
go func() {
|
||||
// ...
|
||||
}()
|
||||
```
|
||||
|
||||
### 3.8 Database Operations
|
||||
|
||||
#### 3.8.1 Query Context
|
||||
```go
|
||||
// Good: use context for queries
|
||||
rows, err := s.db.QueryContext(ctx, query, args...)
|
||||
|
||||
// Bad: no context
|
||||
rows, err := s.db.Query(query, args...)
|
||||
```
|
||||
|
||||
#### 3.8.2 Transactions
|
||||
```go
|
||||
// Good: use transactions for multiple operations
|
||||
tx, err := s.db.BeginTx(ctx, nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
defer tx.Rollback()
|
||||
|
||||
// ... operations ...
|
||||
|
||||
if err := tx.Commit(); err != nil {
|
||||
return err
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Frontend (TypeScript/React) Standards
|
||||
|
||||
### 4.1 Code Formatting
|
||||
|
||||
#### 4.1.1 Use Prettier
|
||||
- Configure Prettier for consistent formatting
|
||||
- Format on save enabled
|
||||
- Maximum line length: 100 characters
|
||||
|
||||
#### 4.1.2 Indentation
|
||||
- Use 2 spaces for indentation
|
||||
- Consistent spacing in JSX
|
||||
|
||||
### 4.2 Naming Conventions
|
||||
|
||||
#### 4.2.1 Components
|
||||
```typescript
|
||||
// Good: PascalCase, descriptive
|
||||
function StoragePage() { }
|
||||
function CreatePoolModal() { }
|
||||
function NetworkInterfaceCard() { }
|
||||
|
||||
// Bad: unclear names
|
||||
function Page() { }
|
||||
function Modal() { }
|
||||
function Card() { }
|
||||
```
|
||||
|
||||
#### 4.2.2 Functions
|
||||
```typescript
|
||||
// Good: camelCase, descriptive
|
||||
function createZFSPool(name: string): Promise<ZFSPool> { }
|
||||
function handleSubmit(event: React.FormEvent): void { }
|
||||
function formatBytes(bytes: number): string { }
|
||||
|
||||
// Bad: unclear names
|
||||
function create(name: string) { }
|
||||
function handle(e: any) { }
|
||||
function fmt(b: number) { }
|
||||
```
|
||||
|
||||
#### 4.2.3 Variables
|
||||
```typescript
|
||||
// Good: camelCase, descriptive
|
||||
const poolName = 'tank'
|
||||
const networkInterfaces: NetworkInterface[] = []
|
||||
const isActive = true
|
||||
|
||||
// Bad: unclear names
|
||||
const n = 'tank'
|
||||
const ifs: any[] = []
|
||||
const a = true
|
||||
```
|
||||
|
||||
#### 4.2.4 Constants
|
||||
```typescript
|
||||
// Good: UPPER_SNAKE_CASE for constants
|
||||
const DEFAULT_PORT = 8080
|
||||
const MAX_RETRIES = 3
|
||||
const API_BASE_URL = '/api/v1'
|
||||
|
||||
// Bad: inconsistent casing
|
||||
const defaultPort = 8080
|
||||
const maxRetries = 3
|
||||
```
|
||||
|
||||
#### 4.2.5 Types and Interfaces
|
||||
```typescript
|
||||
// Good: PascalCase, descriptive
|
||||
interface ZFSPool {
|
||||
id: string
|
||||
name: string
|
||||
status: string
|
||||
}
|
||||
|
||||
type PoolStatus = 'online' | 'offline' | 'degraded'
|
||||
|
||||
// Bad: unclear names
|
||||
interface Pool {
|
||||
i: string
|
||||
n: string
|
||||
s: string
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 File Organization
|
||||
|
||||
#### 4.3.1 Component Structure
|
||||
```typescript
|
||||
// 1. Imports (React, third-party, local)
|
||||
import { useState } from 'react'
|
||||
import { useQuery } from '@tanstack/react-query'
|
||||
import { zfsApi } from '@/api/storage'
|
||||
|
||||
// 2. Types/Interfaces
|
||||
interface Props {
|
||||
poolId: string
|
||||
}
|
||||
|
||||
// 3. Component
|
||||
export default function PoolDetail({ poolId }: Props) {
|
||||
// 4. Hooks
|
||||
const [isLoading, setIsLoading] = useState(false)
|
||||
|
||||
// 5. Queries
|
||||
const { data: pool } = useQuery({
|
||||
queryKey: ['pool', poolId],
|
||||
queryFn: () => zfsApi.getPool(poolId),
|
||||
})
|
||||
|
||||
// 6. Handlers
|
||||
const handleDelete = () => {
|
||||
// ...
|
||||
}
|
||||
|
||||
// 7. Effects
|
||||
useEffect(() => {
|
||||
// ...
|
||||
}, [poolId])
|
||||
|
||||
// 8. Render
|
||||
return (
|
||||
// JSX
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.3.2 File Naming
|
||||
- Components: `PascalCase.tsx` (e.g., `StoragePage.tsx`)
|
||||
- Utilities: `camelCase.ts` (e.g., `formatBytes.ts`)
|
||||
- Types: `camelCase.ts` or `types.ts`
|
||||
- Hooks: `useCamelCase.ts` (e.g., `useStorage.ts`)
|
||||
|
||||
### 4.4 TypeScript
|
||||
|
||||
#### 4.4.1 Type Safety
|
||||
```typescript
|
||||
// Good: explicit types
|
||||
function createPool(name: string): Promise<ZFSPool> {
|
||||
// ...
|
||||
}
|
||||
|
||||
// Bad: any types
|
||||
function createPool(name: any): any {
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.4.2 Interface Definitions
|
||||
```typescript
|
||||
// Good: clear interface definitions
|
||||
interface ZFSPool {
|
||||
id: string
|
||||
name: string
|
||||
status: 'online' | 'offline' | 'degraded'
|
||||
totalCapacityBytes: number
|
||||
usedCapacityBytes: number
|
||||
}
|
||||
|
||||
// Bad: unclear or missing types
|
||||
interface Pool {
|
||||
id: any
|
||||
name: any
|
||||
status: any
|
||||
}
|
||||
```
|
||||
|
||||
### 4.5 React Patterns
|
||||
|
||||
#### 4.5.1 Hooks
|
||||
```typescript
|
||||
// Good: custom hooks for reusable logic
|
||||
function useZFSPool(poolId: string) {
|
||||
return useQuery({
|
||||
queryKey: ['pool', poolId],
|
||||
queryFn: () => zfsApi.getPool(poolId),
|
||||
})
|
||||
}
|
||||
|
||||
// Usage
|
||||
const { data: pool } = useZFSPool(poolId)
|
||||
```
|
||||
|
||||
#### 4.5.2 Component Composition
|
||||
```typescript
|
||||
// Good: small, focused components
|
||||
function PoolCard({ pool }: { pool: ZFSPool }) {
|
||||
return (
|
||||
<div>
|
||||
<PoolHeader pool={pool} />
|
||||
<PoolStats pool={pool} />
|
||||
<PoolActions pool={pool} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// Bad: large, monolithic components
|
||||
function PoolCard({ pool }: { pool: ZFSPool }) {
|
||||
// 500+ lines of JSX
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.5.3 State Management
|
||||
```typescript
|
||||
// Good: use React Query for server state
|
||||
const { data, isLoading } = useQuery({
|
||||
queryKey: ['pools'],
|
||||
queryFn: zfsApi.listPools,
|
||||
})
|
||||
|
||||
// Good: use local state for UI state
|
||||
const [isModalOpen, setIsModalOpen] = useState(false)
|
||||
|
||||
// Good: use Zustand for global UI state
|
||||
const { user, setUser } = useAuthStore()
|
||||
```
|
||||
|
||||
### 4.6 Error Handling
|
||||
|
||||
#### 4.6.1 Error Boundaries
|
||||
```typescript
|
||||
// Good: use error boundaries
|
||||
function ErrorBoundary({ children }: { children: React.ReactNode }) {
|
||||
// ...
|
||||
}
|
||||
|
||||
// Usage
|
||||
<ErrorBoundary>
|
||||
<App />
|
||||
</ErrorBoundary>
|
||||
```
|
||||
|
||||
#### 4.6.2 Error Handling in Queries
|
||||
```typescript
|
||||
// Good: handle errors in queries
|
||||
const { data, error, isLoading } = useQuery({
|
||||
queryKey: ['pools'],
|
||||
queryFn: zfsApi.listPools,
|
||||
onError: (error) => {
|
||||
console.error('Failed to load pools:', error)
|
||||
// Show user-friendly error message
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
### 4.7 Styling
|
||||
|
||||
#### 4.7.1 TailwindCSS
|
||||
```typescript
|
||||
// Good: use Tailwind classes
|
||||
<div className="flex items-center gap-4 p-6 bg-card-dark rounded-lg border border-border-dark">
|
||||
<h2 className="text-lg font-bold text-white">Storage Pools</h2>
|
||||
</div>
|
||||
|
||||
// Bad: inline styles
|
||||
<div style={{ display: 'flex', padding: '24px', backgroundColor: '#18232e' }}>
|
||||
<h2 style={{ fontSize: '18px', fontWeight: 'bold', color: 'white' }}>Storage Pools</h2>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### 4.7.2 Class Organization
|
||||
```typescript
|
||||
// Good: logical grouping
|
||||
className="flex items-center gap-4 p-6 bg-card-dark rounded-lg border border-border-dark hover:bg-border-dark transition-colors"
|
||||
|
||||
// Bad: random order
|
||||
className="p-6 flex border rounded-lg items-center gap-4 bg-card-dark border-border-dark"
|
||||
```
|
||||
|
||||
### 4.8 Testing
|
||||
|
||||
#### 4.8.1 Component Testing
|
||||
```typescript
|
||||
// Good: test component behavior
|
||||
describe('StoragePage', () => {
|
||||
it('displays pools when loaded', () => {
|
||||
render(<StoragePage />)
|
||||
expect(screen.getByText('tank')).toBeInTheDocument()
|
||||
})
|
||||
|
||||
it('shows loading state', () => {
|
||||
render(<StoragePage />)
|
||||
expect(screen.getByText('Loading...')).toBeInTheDocument()
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Git Commit Standards
|
||||
|
||||
### 5.1 Commit Message Format
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
### 5.2 Commit Types
|
||||
- **feat**: New feature
|
||||
- **fix**: Bug fix
|
||||
- **docs**: Documentation changes
|
||||
- **style**: Code style changes (formatting, etc.)
|
||||
- **refactor**: Code refactoring
|
||||
- **test**: Test additions or changes
|
||||
- **chore**: Build process or auxiliary tool changes
|
||||
|
||||
### 5.3 Commit Examples
|
||||
```
|
||||
feat(storage): add ZFS pool creation endpoint
|
||||
|
||||
Add POST /api/v1/storage/zfs/pools endpoint with validation
|
||||
and error handling.
|
||||
|
||||
Closes #123
|
||||
|
||||
fix(shares): correct dataset_id field in create share
|
||||
|
||||
The frontend was sending dataset_name instead of dataset_id.
|
||||
Updated to use UUID from dataset selection.
|
||||
|
||||
docs: update API documentation for snapshot endpoints
|
||||
|
||||
refactor(auth): simplify JWT token validation logic
|
||||
```
|
||||
|
||||
### 5.4 Branch Naming
|
||||
- **feature/**: New features (e.g., `feature/object-storage`)
|
||||
- **fix/**: Bug fixes (e.g., `fix/share-creation-error`)
|
||||
- **docs/**: Documentation (e.g., `docs/api-documentation`)
|
||||
- **refactor/**: Refactoring (e.g., `refactor/storage-service`)
|
||||
|
||||
---
|
||||
|
||||
## 6. Code Review Guidelines
|
||||
|
||||
### 6.1 Review Checklist
|
||||
- [ ] Code follows naming conventions
|
||||
- [ ] Code is properly formatted
|
||||
- [ ] Error handling is appropriate
|
||||
- [ ] Tests are included for new features
|
||||
- [ ] Documentation is updated
|
||||
- [ ] No security vulnerabilities
|
||||
- [ ] Performance considerations addressed
|
||||
- [ ] No commented-out code
|
||||
- [ ] No console.log statements (use proper logging)
|
||||
|
||||
### 6.2 Review Comments
|
||||
- Be constructive and respectful
|
||||
- Explain why, not just what
|
||||
- Suggest improvements, not just point out issues
|
||||
- Approve when code meets standards
|
||||
|
||||
---
|
||||
|
||||
## 7. Documentation Standards
|
||||
|
||||
### 7.1 Code Comments
|
||||
- Document complex logic
|
||||
- Explain "why" not "what"
|
||||
- Keep comments up-to-date
|
||||
|
||||
### 7.2 API Documentation
|
||||
- Document all public APIs
|
||||
- Include parameter descriptions
|
||||
- Include return value descriptions
|
||||
- Include error conditions
|
||||
|
||||
### 7.3 README Files
|
||||
- Keep README files updated
|
||||
- Include setup instructions
|
||||
- Include usage examples
|
||||
- Include troubleshooting tips
|
||||
|
||||
---
|
||||
|
||||
## 8. Performance Standards
|
||||
|
||||
### 8.1 Backend
|
||||
- Database queries should be optimized
|
||||
- Use indexes appropriately
|
||||
- Avoid N+1 query problems
|
||||
- Use connection pooling
|
||||
|
||||
### 8.2 Frontend
|
||||
- Minimize re-renders
|
||||
- Use React.memo for expensive components
|
||||
- Lazy load routes
|
||||
- Optimize bundle size
|
||||
|
||||
---
|
||||
|
||||
## 9. Security Standards
|
||||
|
||||
### 9.1 Input Validation
|
||||
- Validate all user inputs
|
||||
- Sanitize inputs before use
|
||||
- Use parameterized queries
|
||||
- Escape output
|
||||
|
||||
### 9.2 Authentication
|
||||
- Never store passwords in plaintext
|
||||
- Use secure token storage
|
||||
- Implement proper session management
|
||||
- Handle token expiration
|
||||
|
||||
### 9.3 Authorization
|
||||
- Check permissions on every request
|
||||
- Use principle of least privilege
|
||||
- Log security events
|
||||
- Handle authorization errors properly
|
||||
|
||||
---
|
||||
|
||||
## 10. Tools and Configuration
|
||||
|
||||
### 10.1 Backend Tools
|
||||
- **gofmt**: Code formatting
|
||||
- **goimports**: Import organization
|
||||
- **golint**: Linting
|
||||
- **go vet**: Static analysis
|
||||
|
||||
### 10.2 Frontend Tools
|
||||
- **Prettier**: Code formatting
|
||||
- **ESLint**: Linting
|
||||
- **TypeScript**: Type checking
|
||||
- **Vite**: Build tool
|
||||
|
||||
---
|
||||
|
||||
## 11. Exceptions
|
||||
|
||||
### 11.1 When to Deviate
|
||||
- Performance-critical code may require optimization
|
||||
- Legacy code integration may require different patterns
|
||||
- Third-party library constraints
|
||||
|
||||
### 11.2 Documenting Exceptions
|
||||
- Document why standards are not followed
|
||||
- Include comments explaining deviations
|
||||
- Review exceptions during code review
|
||||
|
||||
---
|
||||
|
||||
## Document History
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0-alpha | 2025-01-XX | Development Team | Initial coding standards document |
|
||||
|
||||
75
docs/alpha/README.md
Normal file
75
docs/alpha/README.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# AtlasOS - Calypso Documentation
|
||||
## Alpha Release
|
||||
|
||||
This directory contains the Software Requirements Specification (SRS) and Software Design Specification (SDS) documentation for the Calypso backup appliance management system.
|
||||
|
||||
## Documentation Structure
|
||||
|
||||
### Software Requirements Specification (SRS)
|
||||
Located in `srs/` directory:
|
||||
|
||||
- **SRS-00-Overview.md**: Overview and introduction
|
||||
- **SRS-01-Storage-Management.md**: ZFS storage management requirements
|
||||
- **SRS-02-File-Sharing.md**: SMB/NFS share management requirements
|
||||
- **SRS-03-iSCSI-Management.md**: iSCSI target management requirements
|
||||
- **SRS-04-Tape-Library-Management.md**: Physical and VTL management requirements
|
||||
- **SRS-05-Backup-Management.md**: Bacula/Bareos integration requirements
|
||||
- **SRS-06-Object-Storage.md**: S3-compatible object storage requirements
|
||||
- **SRS-07-Snapshot-Replication.md**: ZFS snapshot and replication requirements
|
||||
- **SRS-08-System-Management.md**: System configuration and management requirements
|
||||
- **SRS-09-Monitoring-Alerting.md**: Monitoring and alerting requirements
|
||||
- **SRS-10-IAM.md**: Identity and access management requirements
|
||||
- **SRS-11-User-Interface.md**: User interface and experience requirements
|
||||
|
||||
### Software Design Specification (SDS)
|
||||
Located in `sds/` directory:
|
||||
|
||||
- **SDS-00-Overview.md**: Design overview and introduction
|
||||
- **SDS-01-System-Architecture.md**: System architecture and component design
|
||||
- **SDS-02-Database-Design.md**: Database schema and data models
|
||||
- **SDS-03-API-Design.md**: REST API design and endpoints
|
||||
- **SDS-04-Security-Design.md**: Security architecture and implementation
|
||||
- **SDS-05-Integration-Design.md**: External system integration patterns
|
||||
|
||||
### Coding Standards
|
||||
- **CODING-STANDARDS.md**: Code style, naming conventions, and best practices for Go and TypeScript/React
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Features Implemented
|
||||
1. ✅ Storage Management (ZFS pools, datasets, disks)
|
||||
2. ✅ File Sharing (SMB/CIFS, NFS)
|
||||
3. ✅ iSCSI Management (SCST integration)
|
||||
4. ✅ Tape Library Management (Physical & VTL)
|
||||
5. ✅ Backup Management (Bacula/Bareos integration)
|
||||
6. ✅ Object Storage (S3-compatible)
|
||||
7. ✅ Snapshot & Replication
|
||||
8. ✅ System Management (Network, Services, NTP, SNMP, License)
|
||||
9. ✅ Monitoring & Alerting
|
||||
10. ✅ Identity & Access Management (IAM)
|
||||
11. ✅ User Interface (React SPA)
|
||||
|
||||
### Technology Stack
|
||||
- **Backend**: Go 1.21+, Gin, PostgreSQL
|
||||
- **Frontend**: React 18, TypeScript, Vite, TailwindCSS
|
||||
- **External**: ZFS, SCST, Bacula/Bareos, MHVTL
|
||||
|
||||
## Document Status
|
||||
|
||||
**Version**: 1.0.0-alpha
|
||||
**Last Updated**: 2025-01-XX
|
||||
**Status**: In Development
|
||||
|
||||
## Contributing
|
||||
|
||||
When updating documentation:
|
||||
1. Update the relevant SRS or SDS document
|
||||
2. Update the version and date in the document
|
||||
3. Update this README if structure changes
|
||||
4. Maintain consistency across documents
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- Implementation guides: `../on-progress/`
|
||||
- Technical specifications: `../../src/srs-technical-spec-documents/`
|
||||
|
||||
182
docs/alpha/sds/SDS-00-Overview.md
Normal file
182
docs/alpha/sds/SDS-00-Overview.md
Normal file
@@ -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 |
|
||||
|
||||
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": {}
|
||||
}
|
||||
```
|
||||
|
||||
385
docs/alpha/sds/SDS-02-Database-Design.md
Normal file
385
docs/alpha/sds/SDS-02-Database-Design.md
Normal file
@@ -0,0 +1,385 @@
|
||||
# SDS-02: Database Design
|
||||
|
||||
## 1. Database Overview
|
||||
|
||||
### 1.1 Database System
|
||||
- **Type**: PostgreSQL 14+
|
||||
- **Encoding**: UTF-8
|
||||
- **Connection Pooling**: pgxpool
|
||||
- **Migrations**: Custom migration system
|
||||
|
||||
### 1.2 Database Schema Organization
|
||||
- **Tables**: Organized by domain (users, storage, shares, etc.)
|
||||
- **Indexes**: Performance indexes on foreign keys and frequently queried columns
|
||||
- **Constraints**: Foreign keys, unique constraints, check constraints
|
||||
|
||||
## 2. Core Tables
|
||||
|
||||
### 2.1 Users & Authentication
|
||||
```sql
|
||||
users (
|
||||
id UUID PRIMARY KEY,
|
||||
username VARCHAR(255) UNIQUE NOT NULL,
|
||||
email VARCHAR(255) UNIQUE,
|
||||
password_hash VARCHAR(255) NOT NULL,
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
)
|
||||
|
||||
roles (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
description TEXT,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
)
|
||||
|
||||
permissions (
|
||||
id UUID PRIMARY KEY,
|
||||
resource VARCHAR(255) NOT NULL,
|
||||
action VARCHAR(255) NOT NULL,
|
||||
description TEXT,
|
||||
UNIQUE(resource, action)
|
||||
)
|
||||
|
||||
user_roles (
|
||||
user_id UUID REFERENCES users(id),
|
||||
role_id UUID REFERENCES roles(id),
|
||||
PRIMARY KEY (user_id, role_id)
|
||||
)
|
||||
|
||||
role_permissions (
|
||||
role_id UUID REFERENCES roles(id),
|
||||
permission_id UUID REFERENCES permissions(id),
|
||||
PRIMARY KEY (role_id, permission_id)
|
||||
)
|
||||
|
||||
groups (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
description TEXT,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
)
|
||||
|
||||
user_groups (
|
||||
user_id UUID REFERENCES users(id),
|
||||
group_id UUID REFERENCES groups(id),
|
||||
PRIMARY KEY (user_id, group_id)
|
||||
)
|
||||
```
|
||||
|
||||
### 2.2 Storage Tables
|
||||
```sql
|
||||
zfs_pools (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
description TEXT,
|
||||
raid_level VARCHAR(50),
|
||||
status VARCHAR(50),
|
||||
total_capacity_bytes BIGINT,
|
||||
used_capacity_bytes BIGINT,
|
||||
health_status VARCHAR(50),
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
created_by UUID REFERENCES users(id)
|
||||
)
|
||||
|
||||
zfs_datasets (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) NOT NULL,
|
||||
pool_name VARCHAR(255) REFERENCES zfs_pools(name),
|
||||
type VARCHAR(50),
|
||||
mount_point VARCHAR(255),
|
||||
used_bytes BIGINT,
|
||||
available_bytes BIGINT,
|
||||
compression VARCHAR(50),
|
||||
quota BIGINT,
|
||||
reservation BIGINT,
|
||||
created_at TIMESTAMP,
|
||||
UNIQUE(pool_name, name)
|
||||
)
|
||||
|
||||
physical_disks (
|
||||
id UUID PRIMARY KEY,
|
||||
device_path VARCHAR(255) UNIQUE NOT NULL,
|
||||
vendor VARCHAR(255),
|
||||
model VARCHAR(255),
|
||||
serial_number VARCHAR(255),
|
||||
size_bytes BIGINT,
|
||||
type VARCHAR(50),
|
||||
status VARCHAR(50),
|
||||
last_synced_at TIMESTAMP
|
||||
)
|
||||
|
||||
storage_repositories (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
type VARCHAR(50),
|
||||
path VARCHAR(255),
|
||||
capacity_bytes BIGINT,
|
||||
used_bytes BIGINT,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
)
|
||||
```
|
||||
|
||||
### 2.3 Shares Tables
|
||||
```sql
|
||||
shares (
|
||||
id UUID PRIMARY KEY,
|
||||
dataset_id UUID REFERENCES zfs_datasets(id),
|
||||
share_type VARCHAR(50),
|
||||
nfs_enabled BOOLEAN DEFAULT false,
|
||||
nfs_options TEXT,
|
||||
nfs_clients TEXT[],
|
||||
smb_enabled BOOLEAN DEFAULT false,
|
||||
smb_share_name VARCHAR(255),
|
||||
smb_path VARCHAR(255),
|
||||
smb_comment TEXT,
|
||||
smb_guest_ok BOOLEAN DEFAULT false,
|
||||
smb_read_only BOOLEAN DEFAULT false,
|
||||
smb_browseable BOOLEAN DEFAULT true,
|
||||
is_active BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
created_by UUID REFERENCES users(id)
|
||||
)
|
||||
```
|
||||
|
||||
### 2.4 iSCSI Tables
|
||||
```sql
|
||||
iscsi_targets (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
alias VARCHAR(255),
|
||||
enabled BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
created_by UUID REFERENCES users(id)
|
||||
)
|
||||
|
||||
iscsi_luns (
|
||||
id UUID PRIMARY KEY,
|
||||
target_id UUID REFERENCES iscsi_targets(id),
|
||||
lun_number INTEGER,
|
||||
device_path VARCHAR(255),
|
||||
size_bytes BIGINT,
|
||||
created_at TIMESTAMP
|
||||
)
|
||||
|
||||
iscsi_initiators (
|
||||
id UUID PRIMARY KEY,
|
||||
iqn VARCHAR(255) UNIQUE NOT NULL,
|
||||
created_at TIMESTAMP
|
||||
)
|
||||
|
||||
target_initiators (
|
||||
target_id UUID REFERENCES iscsi_targets(id),
|
||||
initiator_id UUID REFERENCES iscsi_initiators(id),
|
||||
PRIMARY KEY (target_id, initiator_id)
|
||||
)
|
||||
```
|
||||
|
||||
### 2.5 Tape Tables
|
||||
```sql
|
||||
vtl_libraries (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
vendor VARCHAR(255),
|
||||
model VARCHAR(255),
|
||||
drive_count INTEGER,
|
||||
slot_count INTEGER,
|
||||
status VARCHAR(50),
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
created_by UUID REFERENCES users(id)
|
||||
)
|
||||
|
||||
physical_libraries (
|
||||
id UUID PRIMARY KEY,
|
||||
vendor VARCHAR(255),
|
||||
model VARCHAR(255),
|
||||
serial_number VARCHAR(255),
|
||||
drive_count INTEGER,
|
||||
slot_count INTEGER,
|
||||
discovered_at TIMESTAMP
|
||||
)
|
||||
```
|
||||
|
||||
### 2.6 Backup Tables
|
||||
```sql
|
||||
backup_jobs (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
client_id INTEGER,
|
||||
fileset_id INTEGER,
|
||||
schedule VARCHAR(255),
|
||||
storage_pool_id INTEGER,
|
||||
enabled BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
created_by UUID REFERENCES users(id)
|
||||
)
|
||||
```
|
||||
|
||||
### 2.7 Monitoring Tables
|
||||
```sql
|
||||
alerts (
|
||||
id UUID PRIMARY KEY,
|
||||
rule_id UUID,
|
||||
severity VARCHAR(50),
|
||||
source VARCHAR(255),
|
||||
message TEXT,
|
||||
status VARCHAR(50),
|
||||
acknowledged_at TIMESTAMP,
|
||||
resolved_at TIMESTAMP,
|
||||
created_at TIMESTAMP
|
||||
)
|
||||
|
||||
alert_rules (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(255) UNIQUE NOT NULL,
|
||||
description TEXT,
|
||||
source VARCHAR(255),
|
||||
condition_type VARCHAR(255),
|
||||
condition_config JSONB,
|
||||
severity VARCHAR(50),
|
||||
enabled BOOLEAN DEFAULT true,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP
|
||||
)
|
||||
```
|
||||
|
||||
### 2.8 Audit Tables
|
||||
```sql
|
||||
audit_logs (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id UUID REFERENCES users(id),
|
||||
action VARCHAR(255),
|
||||
resource_type VARCHAR(255),
|
||||
resource_id VARCHAR(255),
|
||||
method VARCHAR(10),
|
||||
path VARCHAR(255),
|
||||
ip_address VARCHAR(45),
|
||||
user_agent TEXT,
|
||||
request_body JSONB,
|
||||
response_status INTEGER,
|
||||
created_at TIMESTAMP
|
||||
)
|
||||
```
|
||||
|
||||
### 2.9 Task Tables
|
||||
```sql
|
||||
tasks (
|
||||
id UUID PRIMARY KEY,
|
||||
type VARCHAR(255),
|
||||
status VARCHAR(50),
|
||||
progress INTEGER,
|
||||
result JSONB,
|
||||
error_message TEXT,
|
||||
created_at TIMESTAMP,
|
||||
updated_at TIMESTAMP,
|
||||
completed_at TIMESTAMP,
|
||||
created_by UUID REFERENCES users(id)
|
||||
)
|
||||
```
|
||||
|
||||
## 3. Indexes
|
||||
|
||||
### 3.1 Performance Indexes
|
||||
```sql
|
||||
-- Users
|
||||
CREATE INDEX idx_users_username ON users(username);
|
||||
CREATE INDEX idx_users_email ON users(email);
|
||||
|
||||
-- Storage
|
||||
CREATE INDEX idx_zfs_pools_name ON zfs_pools(name);
|
||||
CREATE INDEX idx_zfs_datasets_pool_name ON zfs_datasets(pool_name);
|
||||
|
||||
-- Shares
|
||||
CREATE INDEX idx_shares_dataset_id ON shares(dataset_id);
|
||||
CREATE INDEX idx_shares_created_by ON shares(created_by);
|
||||
|
||||
-- iSCSI
|
||||
CREATE INDEX idx_iscsi_targets_name ON iscsi_targets(name);
|
||||
CREATE INDEX idx_iscsi_luns_target_id ON iscsi_luns(target_id);
|
||||
|
||||
-- Monitoring
|
||||
CREATE INDEX idx_alerts_status ON alerts(status);
|
||||
CREATE INDEX idx_alerts_created_at ON alerts(created_at);
|
||||
CREATE INDEX idx_audit_logs_user_id ON audit_logs(user_id);
|
||||
CREATE INDEX idx_audit_logs_created_at ON audit_logs(created_at);
|
||||
```
|
||||
|
||||
## 4. Migrations
|
||||
|
||||
### 4.1 Migration System
|
||||
- **Location**: `db/migrations/`
|
||||
- **Naming**: `NNN_description.sql`
|
||||
- **Execution**: Sequential execution on startup
|
||||
- **Version Tracking**: `schema_migrations` table
|
||||
|
||||
### 4.2 Migration Files
|
||||
- `001_initial_schema.sql`: Core tables
|
||||
- `002_storage_and_tape_schema.sql`: Storage and tape tables
|
||||
- `003_performance_indexes.sql`: Performance indexes
|
||||
- `004_add_zfs_pools_table.sql`: ZFS pools
|
||||
- `005_add_zfs_datasets_table.sql`: ZFS datasets
|
||||
- `006_add_zfs_shares_and_iscsi.sql`: Shares and iSCSI
|
||||
- `007_add_vendor_to_vtl_libraries.sql`: VTL updates
|
||||
- `008_add_user_groups.sql`: User groups
|
||||
- `009_backup_jobs_schema.sql`: Backup jobs
|
||||
- `010_add_backup_permissions.sql`: Backup permissions
|
||||
- `011_sync_bacula_jobs_function.sql`: Bacula sync function
|
||||
|
||||
## 5. Data Relationships
|
||||
|
||||
### 5.1 Entity Relationships
|
||||
- **Users** → **Roles** (many-to-many)
|
||||
- **Roles** → **Permissions** (many-to-many)
|
||||
- **Users** → **Groups** (many-to-many)
|
||||
- **ZFS Pools** → **ZFS Datasets** (one-to-many)
|
||||
- **ZFS Datasets** → **Shares** (one-to-many)
|
||||
- **iSCSI Targets** → **LUNs** (one-to-many)
|
||||
- **iSCSI Targets** → **Initiators** (many-to-many)
|
||||
|
||||
## 6. Data Integrity
|
||||
|
||||
### 6.1 Constraints
|
||||
- **Primary Keys**: UUID primary keys for all tables
|
||||
- **Foreign Keys**: Referential integrity
|
||||
- **Unique Constraints**: Unique usernames, emails, names
|
||||
- **Check Constraints**: Valid status values, positive numbers
|
||||
|
||||
### 6.2 Cascading Rules
|
||||
- **ON DELETE CASCADE**: Child records deleted with parent
|
||||
- **ON DELETE RESTRICT**: Prevent deletion if referenced
|
||||
- **ON UPDATE CASCADE**: Update foreign keys on parent update
|
||||
|
||||
## 7. Query Optimization
|
||||
|
||||
### 7.1 Query Patterns
|
||||
- **Eager Loading**: Join related data when needed
|
||||
- **Pagination**: Limit and offset for large datasets
|
||||
- **Filtering**: WHERE clauses for filtering
|
||||
- **Sorting**: ORDER BY for sorted results
|
||||
|
||||
### 7.2 Caching Strategy
|
||||
- **Query Result Caching**: Cache frequently accessed queries
|
||||
- **Cache Invalidation**: Invalidate on write operations
|
||||
- **TTL**: Time-to-live for cached data
|
||||
|
||||
## 8. Backup & Recovery
|
||||
|
||||
### 8.1 Backup Strategy
|
||||
- **Regular Backups**: Daily database backups
|
||||
- **Point-in-Time Recovery**: WAL archiving
|
||||
- **Backup Retention**: 30 days retention
|
||||
|
||||
### 8.2 Recovery Procedures
|
||||
- **Full Restore**: Restore from backup
|
||||
- **Point-in-Time**: Restore to specific timestamp
|
||||
- **Selective Restore**: Restore specific tables
|
||||
|
||||
286
docs/alpha/sds/SDS-03-API-Design.md
Normal file
286
docs/alpha/sds/SDS-03-API-Design.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# SDS-03: API Design
|
||||
|
||||
## 1. API Overview
|
||||
|
||||
### 1.1 API Style
|
||||
- **RESTful**: Resource-based API design
|
||||
- **Versioning**: `/api/v1/` prefix
|
||||
- **Content-Type**: `application/json`
|
||||
- **Authentication**: JWT Bearer tokens
|
||||
|
||||
### 1.2 API Base URL
|
||||
```
|
||||
http://localhost:8080/api/v1
|
||||
```
|
||||
|
||||
## 2. Authentication API
|
||||
|
||||
### 2.1 Endpoints
|
||||
```
|
||||
POST /auth/login
|
||||
POST /auth/logout
|
||||
GET /auth/me
|
||||
```
|
||||
|
||||
### 2.2 Request/Response Examples
|
||||
|
||||
#### Login
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "admin",
|
||||
"password": "password"
|
||||
}
|
||||
|
||||
Response: 200 OK
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"user": {
|
||||
"id": "uuid",
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"roles": ["admin"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Current User
|
||||
```http
|
||||
GET /api/v1/auth/me
|
||||
Authorization: Bearer <token>
|
||||
|
||||
Response: 200 OK
|
||||
{
|
||||
"id": "uuid",
|
||||
"username": "admin",
|
||||
"email": "admin@example.com",
|
||||
"roles": ["admin"],
|
||||
"permissions": ["storage:read", "storage:write", ...]
|
||||
}
|
||||
```
|
||||
|
||||
## 3. Storage API
|
||||
|
||||
### 3.1 ZFS Pools
|
||||
```
|
||||
GET /storage/zfs/pools
|
||||
GET /storage/zfs/pools/:id
|
||||
POST /storage/zfs/pools
|
||||
DELETE /storage/zfs/pools/:id
|
||||
POST /storage/zfs/pools/:id/spare
|
||||
```
|
||||
|
||||
### 3.2 ZFS Datasets
|
||||
```
|
||||
GET /storage/zfs/pools/:id/datasets
|
||||
POST /storage/zfs/pools/:id/datasets
|
||||
DELETE /storage/zfs/pools/:id/datasets/:dataset
|
||||
```
|
||||
|
||||
### 3.3 Request/Response Examples
|
||||
|
||||
#### Create ZFS Pool
|
||||
```http
|
||||
POST /api/v1/storage/zfs/pools
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"name": "tank",
|
||||
"raid_level": "mirror",
|
||||
"disks": ["/dev/sdb", "/dev/sdc"],
|
||||
"compression": "lz4",
|
||||
"deduplication": false
|
||||
}
|
||||
|
||||
Response: 201 Created
|
||||
{
|
||||
"id": "uuid",
|
||||
"name": "tank",
|
||||
"status": "online",
|
||||
"total_capacity_bytes": 1000000000000,
|
||||
"created_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Shares API
|
||||
|
||||
### 4.1 Endpoints
|
||||
```
|
||||
GET /shares
|
||||
GET /shares/:id
|
||||
POST /shares
|
||||
PUT /shares/:id
|
||||
DELETE /shares/:id
|
||||
```
|
||||
|
||||
### 4.2 Request/Response Examples
|
||||
|
||||
#### Create Share
|
||||
```http
|
||||
POST /api/v1/shares
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"dataset_id": "uuid",
|
||||
"share_type": "both",
|
||||
"nfs_enabled": true,
|
||||
"nfs_clients": ["192.168.1.0/24"],
|
||||
"smb_enabled": true,
|
||||
"smb_share_name": "shared",
|
||||
"smb_path": "/mnt/tank/shared",
|
||||
"smb_guest_ok": false,
|
||||
"smb_read_only": false
|
||||
}
|
||||
|
||||
Response: 201 Created
|
||||
{
|
||||
"id": "uuid",
|
||||
"dataset_id": "uuid",
|
||||
"share_type": "both",
|
||||
"nfs_enabled": true,
|
||||
"smb_enabled": true,
|
||||
"created_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 5. iSCSI API
|
||||
|
||||
### 5.1 Endpoints
|
||||
```
|
||||
GET /scst/targets
|
||||
GET /scst/targets/:id
|
||||
POST /scst/targets
|
||||
DELETE /scst/targets/:id
|
||||
POST /scst/targets/:id/luns
|
||||
DELETE /scst/targets/:id/luns/:lunId
|
||||
POST /scst/targets/:id/initiators
|
||||
GET /scst/initiators
|
||||
POST /scst/config/apply
|
||||
```
|
||||
|
||||
## 6. System API
|
||||
|
||||
### 6.1 Endpoints
|
||||
```
|
||||
GET /system/services
|
||||
GET /system/services/:name
|
||||
POST /system/services/:name/restart
|
||||
GET /system/services/:name/logs
|
||||
GET /system/interfaces
|
||||
PUT /system/interfaces/:name
|
||||
GET /system/ntp
|
||||
POST /system/ntp
|
||||
GET /system/logs
|
||||
GET /system/network/throughput
|
||||
POST /system/execute
|
||||
POST /system/support-bundle
|
||||
```
|
||||
|
||||
## 7. Monitoring API
|
||||
|
||||
### 7.1 Endpoints
|
||||
```
|
||||
GET /monitoring/metrics
|
||||
GET /monitoring/health
|
||||
GET /monitoring/alerts
|
||||
GET /monitoring/alerts/:id
|
||||
POST /monitoring/alerts/:id/acknowledge
|
||||
POST /monitoring/alerts/:id/resolve
|
||||
GET /monitoring/rules
|
||||
POST /monitoring/rules
|
||||
```
|
||||
|
||||
## 8. IAM API
|
||||
|
||||
### 8.1 Endpoints
|
||||
```
|
||||
GET /iam/users
|
||||
GET /iam/users/:id
|
||||
POST /iam/users
|
||||
PUT /iam/users/:id
|
||||
DELETE /iam/users/:id
|
||||
|
||||
GET /iam/roles
|
||||
GET /iam/roles/:id
|
||||
POST /iam/roles
|
||||
PUT /iam/roles/:id
|
||||
DELETE /iam/roles/:id
|
||||
|
||||
GET /iam/permissions
|
||||
GET /iam/groups
|
||||
```
|
||||
|
||||
## 9. Error Responses
|
||||
|
||||
### 9.1 Error Format
|
||||
```json
|
||||
{
|
||||
"error": "Error message",
|
||||
"code": "ERROR_CODE",
|
||||
"details": {
|
||||
"field": "validation error"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 HTTP Status Codes
|
||||
- **200 OK**: Success
|
||||
- **201 Created**: Resource created
|
||||
- **400 Bad Request**: Validation error
|
||||
- **401 Unauthorized**: Authentication required
|
||||
- **403 Forbidden**: Permission denied
|
||||
- **404 Not Found**: Resource not found
|
||||
- **500 Internal Server Error**: Server error
|
||||
|
||||
## 10. Pagination
|
||||
|
||||
### 10.1 Pagination Parameters
|
||||
```
|
||||
GET /api/v1/resource?page=1&limit=20
|
||||
```
|
||||
|
||||
### 10.2 Pagination Response
|
||||
```json
|
||||
{
|
||||
"data": [...],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"limit": 20,
|
||||
"total": 100,
|
||||
"total_pages": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 11. Filtering & Sorting
|
||||
|
||||
### 11.1 Filtering
|
||||
```
|
||||
GET /api/v1/resource?status=active&type=filesystem
|
||||
```
|
||||
|
||||
### 11.2 Sorting
|
||||
```
|
||||
GET /api/v1/resource?sort=name&order=asc
|
||||
```
|
||||
|
||||
## 12. Rate Limiting
|
||||
|
||||
### 12.1 Rate Limits
|
||||
- **Default**: 100 requests per minute per IP
|
||||
- **Authenticated**: 200 requests per minute per user
|
||||
- **Headers**: `X-RateLimit-Limit`, `X-RateLimit-Remaining`
|
||||
|
||||
## 13. Caching
|
||||
|
||||
### 13.1 Cache Headers
|
||||
- **Cache-Control**: `max-age=300` for GET requests
|
||||
- **ETag**: Entity tags for cache validation
|
||||
- **Last-Modified**: Last modification time
|
||||
|
||||
### 13.2 Cache Invalidation
|
||||
- **On Write**: Invalidate related cache entries
|
||||
- **Manual**: Clear cache via admin endpoint
|
||||
|
||||
224
docs/alpha/sds/SDS-04-Security-Design.md
Normal file
224
docs/alpha/sds/SDS-04-Security-Design.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# SDS-04: Security Design
|
||||
|
||||
## 1. Security Overview
|
||||
|
||||
### 1.1 Security Principles
|
||||
- **Defense in Depth**: Multiple layers of security
|
||||
- **Principle of Least Privilege**: Minimum required permissions
|
||||
- **Secure by Default**: Secure default configurations
|
||||
- **Input Validation**: Validate all inputs
|
||||
- **Output Encoding**: Encode all outputs
|
||||
|
||||
## 2. Authentication
|
||||
|
||||
### 2.1 Authentication Method
|
||||
- **JWT Tokens**: JSON Web Tokens for stateless authentication
|
||||
- **Token Expiration**: Configurable expiration time
|
||||
- **Token Refresh**: Refresh token mechanism (future)
|
||||
|
||||
### 2.2 Password Security
|
||||
- **Hashing**: bcrypt with cost factor 10
|
||||
- **Password Requirements**: Minimum length, complexity
|
||||
- **Password Storage**: Hashed passwords only, never plaintext
|
||||
|
||||
### 2.3 Session Management
|
||||
- **Stateless**: No server-side session storage
|
||||
- **Token Storage**: Secure storage in frontend (localStorage/sessionStorage)
|
||||
- **Token Validation**: Validate on every request
|
||||
|
||||
## 3. Authorization
|
||||
|
||||
### 3.1 Role-Based Access Control (RBAC)
|
||||
- **Roles**: Admin, Operator, ReadOnly
|
||||
- **Permissions**: Resource-based permissions (storage:read, storage:write)
|
||||
- **Role Assignment**: Users assigned to roles
|
||||
- **Permission Inheritance**: Permissions inherited from roles
|
||||
|
||||
### 3.2 Permission Model
|
||||
```
|
||||
Resource:Action
|
||||
Examples:
|
||||
- storage:read
|
||||
- storage:write
|
||||
- iscsi:read
|
||||
- iscsi:write
|
||||
- backup:read
|
||||
- backup:write
|
||||
- system:read
|
||||
- system:write
|
||||
```
|
||||
|
||||
### 3.3 Permission Checking
|
||||
- **Middleware**: Permission middleware checks on protected routes
|
||||
- **Handler Level**: Additional checks in handlers if needed
|
||||
- **Service Level**: Business logic permission checks
|
||||
|
||||
## 4. Input Validation
|
||||
|
||||
### 4.1 Validation Layers
|
||||
1. **Frontend**: Client-side validation
|
||||
2. **Handler**: Request validation
|
||||
3. **Service**: Business logic validation
|
||||
4. **Database**: Constraint validation
|
||||
|
||||
### 4.2 Validation Rules
|
||||
- **Required Fields**: Check for required fields
|
||||
- **Type Validation**: Validate data types
|
||||
- **Format Validation**: Validate formats (email, IP, etc.)
|
||||
- **Range Validation**: Validate numeric ranges
|
||||
- **Length Validation**: Validate string lengths
|
||||
|
||||
### 4.3 SQL Injection Prevention
|
||||
- **Parameterized Queries**: Use parameterized queries only
|
||||
- **No String Concatenation**: Never concatenate SQL strings
|
||||
- **Input Sanitization**: Sanitize all inputs
|
||||
|
||||
## 5. Output Encoding
|
||||
|
||||
### 5.1 XSS Prevention
|
||||
- **HTML Encoding**: Encode HTML in responses
|
||||
- **JSON Encoding**: Proper JSON encoding
|
||||
- **Content Security Policy**: CSP headers
|
||||
|
||||
### 5.2 Response Headers
|
||||
```
|
||||
Content-Security-Policy: default-src 'self'
|
||||
X-Content-Type-Options: nosniff
|
||||
X-Frame-Options: DENY
|
||||
X-XSS-Protection: 1; mode=block
|
||||
```
|
||||
|
||||
## 6. HTTPS & TLS
|
||||
|
||||
### 6.1 TLS Configuration
|
||||
- **TLS Version**: TLS 1.2 minimum
|
||||
- **Cipher Suites**: Strong cipher suites only
|
||||
- **Certificate**: Valid SSL certificate
|
||||
|
||||
### 6.2 HTTPS Enforcement
|
||||
- **Redirect HTTP to HTTPS**: Force HTTPS
|
||||
- **HSTS**: HTTP Strict Transport Security
|
||||
|
||||
## 7. Rate Limiting
|
||||
|
||||
### 7.1 Rate Limit Strategy
|
||||
- **IP-Based**: Rate limit by IP address
|
||||
- **User-Based**: Rate limit by authenticated user
|
||||
- **Endpoint-Based**: Different limits per endpoint
|
||||
|
||||
### 7.2 Rate Limit Configuration
|
||||
- **Default**: 100 requests/minute
|
||||
- **Authenticated**: 200 requests/minute
|
||||
- **Strict Endpoints**: Lower limits for sensitive endpoints
|
||||
|
||||
## 8. Audit Logging
|
||||
|
||||
### 8.1 Audit Events
|
||||
- **Authentication**: Login, logout, failed login
|
||||
- **Authorization**: Permission denied events
|
||||
- **Data Access**: Read operations (configurable)
|
||||
- **Data Modification**: Create, update, delete operations
|
||||
- **System Actions**: System configuration changes
|
||||
|
||||
### 8.2 Audit Log Format
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"user_id": "uuid",
|
||||
"action": "CREATE_SHARE",
|
||||
"resource_type": "share",
|
||||
"resource_id": "uuid",
|
||||
"method": "POST",
|
||||
"path": "/api/v1/shares",
|
||||
"ip_address": "192.168.1.100",
|
||||
"user_agent": "Mozilla/5.0...",
|
||||
"request_body": {...},
|
||||
"response_status": 201,
|
||||
"created_at": "2025-01-01T00:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 9. Error Handling
|
||||
|
||||
### 9.1 Error Information
|
||||
- **Public Errors**: Safe error messages for users
|
||||
- **Private Errors**: Detailed errors in logs only
|
||||
- **No Stack Traces**: Never expose stack traces to users
|
||||
|
||||
### 9.2 Error Logging
|
||||
- **Log All Errors**: Log all errors with context
|
||||
- **Sensitive Data**: Never log passwords, tokens, secrets
|
||||
- **Error Tracking**: Track error patterns
|
||||
|
||||
## 10. File Upload Security
|
||||
|
||||
### 10.1 Upload Restrictions
|
||||
- **File Types**: Whitelist allowed file types
|
||||
- **File Size**: Maximum file size limits
|
||||
- **File Validation**: Validate file contents
|
||||
|
||||
### 10.2 Storage Security
|
||||
- **Secure Storage**: Store in secure location
|
||||
- **Access Control**: Restrict file access
|
||||
- **Virus Scanning**: Scan uploaded files (future)
|
||||
|
||||
## 11. API Security
|
||||
|
||||
### 11.1 API Authentication
|
||||
- **Bearer Tokens**: JWT in Authorization header
|
||||
- **Token Validation**: Validate on every request
|
||||
- **Token Expiration**: Enforce token expiration
|
||||
|
||||
### 11.2 API Rate Limiting
|
||||
- **Per IP**: Rate limit by IP address
|
||||
- **Per User**: Rate limit by authenticated user
|
||||
- **Per Endpoint**: Different limits per endpoint
|
||||
|
||||
## 12. Database Security
|
||||
|
||||
### 12.1 Database Access
|
||||
- **Connection Security**: Encrypted connections
|
||||
- **Credentials**: Secure credential storage
|
||||
- **Least Privilege**: Database user with minimum privileges
|
||||
|
||||
### 12.2 Data Encryption
|
||||
- **At Rest**: Database encryption (future)
|
||||
- **In Transit**: TLS for database connections
|
||||
- **Sensitive Data**: Encrypt sensitive fields
|
||||
|
||||
## 13. System Security
|
||||
|
||||
### 13.1 Command Execution
|
||||
- **Whitelist**: Only allow whitelisted commands
|
||||
- **Input Validation**: Validate command inputs
|
||||
- **Output Sanitization**: Sanitize command outputs
|
||||
|
||||
### 13.2 File System Access
|
||||
- **Path Validation**: Validate all file paths
|
||||
- **Access Control**: Restrict file system access
|
||||
- **Symlink Protection**: Prevent symlink attacks
|
||||
|
||||
## 14. Security Headers
|
||||
|
||||
### 14.1 HTTP Security Headers
|
||||
```
|
||||
X-Content-Type-Options: nosniff
|
||||
X-Frame-Options: DENY
|
||||
X-XSS-Protection: 1; mode=block
|
||||
Content-Security-Policy: default-src 'self'
|
||||
Strict-Transport-Security: max-age=31536000
|
||||
Referrer-Policy: strict-origin-when-cross-origin
|
||||
```
|
||||
|
||||
## 15. Security Monitoring
|
||||
|
||||
### 15.1 Security Events
|
||||
- **Failed Logins**: Monitor failed login attempts
|
||||
- **Permission Denials**: Monitor permission denials
|
||||
- **Suspicious Activity**: Detect suspicious patterns
|
||||
|
||||
### 15.2 Alerting
|
||||
- **Security Alerts**: Alert on security events
|
||||
- **Thresholds**: Alert thresholds for suspicious activity
|
||||
- **Notification**: Notify administrators
|
||||
|
||||
294
docs/alpha/sds/SDS-05-Integration-Design.md
Normal file
294
docs/alpha/sds/SDS-05-Integration-Design.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# SDS-05: Integration Design
|
||||
|
||||
## 1. Integration Overview
|
||||
|
||||
### 1.1 External Systems
|
||||
Calypso integrates with several external systems:
|
||||
- **ZFS**: Zettabyte File System for storage management
|
||||
- **SCST**: SCSI target subsystem for iSCSI
|
||||
- **Bacula/Bareos**: Backup software
|
||||
- **MHVTL**: Virtual Tape Library emulation
|
||||
- **Systemd**: Service management
|
||||
- **PostgreSQL**: Database system
|
||||
|
||||
## 2. ZFS Integration
|
||||
|
||||
### 2.1 Integration Method
|
||||
- **Command Execution**: Execute `zpool` and `zfs` commands
|
||||
- **Output Parsing**: Parse command output
|
||||
- **Error Handling**: Handle command errors
|
||||
|
||||
### 2.2 ZFS Commands
|
||||
```bash
|
||||
# Pool operations
|
||||
zpool create <pool> <disks>
|
||||
zpool list
|
||||
zpool status <pool>
|
||||
zpool destroy <pool>
|
||||
|
||||
# Dataset operations
|
||||
zfs create <dataset>
|
||||
zfs list
|
||||
zfs destroy <dataset>
|
||||
zfs snapshot <dataset>@<snapshot>
|
||||
zfs clone <snapshot> <clone>
|
||||
zfs rollback <snapshot>
|
||||
```
|
||||
|
||||
### 2.3 Data Synchronization
|
||||
- **Pool Monitor**: Background service syncs pool status every 2 minutes
|
||||
- **Dataset Monitor**: Real-time dataset information
|
||||
- **ARC Stats**: Real-time ARC statistics
|
||||
|
||||
## 3. SCST Integration
|
||||
|
||||
### 3.1 Integration Method
|
||||
- **Configuration Files**: Read/write SCST configuration files
|
||||
- **Command Execution**: Execute SCST admin commands
|
||||
- **Config Apply**: Apply configuration changes
|
||||
|
||||
### 3.2 SCST Operations
|
||||
```bash
|
||||
# Target management
|
||||
scstadmin -add_target <target>
|
||||
scstadmin -enable_target <target>
|
||||
scstadmin -disable_target <target>
|
||||
scstadmin -remove_target <target>
|
||||
|
||||
# LUN management
|
||||
scstadmin -add_lun <lun> -driver <driver> -target <target>
|
||||
scstadmin -remove_lun <lun> -driver <driver> -target <target>
|
||||
|
||||
# Initiator management
|
||||
scstadmin -add_init <initiator> -driver <driver> -target <target>
|
||||
scstadmin -remove_init <initiator> -driver <driver> -target <target>
|
||||
|
||||
# Config apply
|
||||
scstadmin -write_config /etc/scst.conf
|
||||
```
|
||||
|
||||
### 3.3 Configuration File Format
|
||||
- **Location**: `/etc/scst.conf`
|
||||
- **Format**: SCST configuration syntax
|
||||
- **Backup**: Backup before modifications
|
||||
|
||||
## 4. Bacula/Bareos Integration
|
||||
|
||||
### 4.1 Integration Methods
|
||||
- **Database Access**: Direct PostgreSQL access to Bacula database
|
||||
- **Bconsole Commands**: Execute commands via `bconsole`
|
||||
- **Job Synchronization**: Sync jobs from Bacula database
|
||||
|
||||
### 4.2 Database Schema
|
||||
- **Tables**: Jobs, Clients, Filesets, Pools, Volumes, Media
|
||||
- **Queries**: SQL queries to retrieve backup information
|
||||
- **Updates**: Update job status, volume information
|
||||
|
||||
### 4.3 Bconsole Commands
|
||||
```bash
|
||||
# Job operations
|
||||
run job=<job_name>
|
||||
status job=<job_id>
|
||||
list jobs
|
||||
list files jobid=<job_id>
|
||||
|
||||
# Client operations
|
||||
list clients
|
||||
status client=<client_name>
|
||||
|
||||
# Pool operations
|
||||
list pools
|
||||
list volumes pool=<pool_name>
|
||||
|
||||
# Storage operations
|
||||
list storage
|
||||
status storage=<storage_name>
|
||||
```
|
||||
|
||||
### 4.4 Job Synchronization
|
||||
- **Background Sync**: Periodic sync from Bacula database
|
||||
- **Real-time Updates**: Update on job completion
|
||||
- **Status Mapping**: Map Bacula status to Calypso status
|
||||
|
||||
## 5. MHVTL Integration
|
||||
|
||||
### 5.1 Integration Method
|
||||
- **Configuration Files**: Read/write MHVTL configuration
|
||||
- **Command Execution**: Execute MHVTL control commands
|
||||
- **Status Monitoring**: Monitor VTL status
|
||||
|
||||
### 5.2 MHVTL Operations
|
||||
```bash
|
||||
# Library operations
|
||||
vtlcmd -l <library> -s <status>
|
||||
vtlcmd -l <library> -d <drive> -l <load>
|
||||
vtlcmd -l <library> -d <drive> -u <unload>
|
||||
|
||||
# Media operations
|
||||
vtlcmd -l <library> -m <media> -l <label>
|
||||
```
|
||||
|
||||
### 5.3 Configuration Management
|
||||
- **Library Configuration**: Create/update VTL library configs
|
||||
- **Drive Configuration**: Configure virtual drives
|
||||
- **Slot Configuration**: Configure virtual slots
|
||||
|
||||
## 6. Systemd Integration
|
||||
|
||||
### 6.1 Integration Method
|
||||
- **DBus API**: Use systemd DBus API
|
||||
- **Command Execution**: Execute `systemctl` commands
|
||||
- **Service Status**: Query service status
|
||||
|
||||
### 6.2 Systemd Operations
|
||||
```bash
|
||||
# Service control
|
||||
systemctl start <service>
|
||||
systemctl stop <service>
|
||||
systemctl restart <service>
|
||||
systemctl status <service>
|
||||
|
||||
# Service information
|
||||
systemctl list-units --type=service
|
||||
systemctl show <service>
|
||||
```
|
||||
|
||||
### 6.3 Service Management
|
||||
- **Service Discovery**: Discover available services
|
||||
- **Status Monitoring**: Monitor service status
|
||||
- **Log Access**: Access service logs via journalctl
|
||||
|
||||
## 7. Network Interface Integration
|
||||
|
||||
### 7.1 Integration Method
|
||||
- **System Commands**: Execute network configuration commands
|
||||
- **File Operations**: Read/write network configuration files
|
||||
- **Status Queries**: Query interface status
|
||||
|
||||
### 7.2 Network Operations
|
||||
```bash
|
||||
# Interface information
|
||||
ip addr show
|
||||
ip link show
|
||||
ethtool <interface>
|
||||
|
||||
# Interface configuration
|
||||
ip addr add <ip>/<mask> dev <interface>
|
||||
ip link set <interface> up/down
|
||||
```
|
||||
|
||||
### 7.3 Configuration Files
|
||||
- **Netplan**: Ubuntu network configuration
|
||||
- **NetworkManager**: NetworkManager configuration
|
||||
- **ifconfig**: Legacy configuration
|
||||
|
||||
## 8. NTP Integration
|
||||
|
||||
### 8.1 Integration Method
|
||||
- **Configuration Files**: Read/write NTP configuration
|
||||
- **Command Execution**: Execute NTP commands
|
||||
- **Status Queries**: Query NTP status
|
||||
|
||||
### 8.2 NTP Operations
|
||||
```bash
|
||||
# NTP status
|
||||
ntpq -p
|
||||
timedatectl status
|
||||
|
||||
# NTP configuration
|
||||
timedatectl set-timezone <timezone>
|
||||
timedatectl set-ntp <true/false>
|
||||
```
|
||||
|
||||
### 8.3 Configuration Files
|
||||
- **ntp.conf**: NTP daemon configuration
|
||||
- **chrony.conf**: Chrony configuration (alternative)
|
||||
|
||||
## 9. Integration Patterns
|
||||
|
||||
### 9.1 Command Execution Pattern
|
||||
```go
|
||||
func executeCommand(cmd string, args []string) (string, error) {
|
||||
ctx := context.Background()
|
||||
output, err := exec.CommandContext(ctx, cmd, args...).CombinedOutput()
|
||||
if err != nil {
|
||||
return "", fmt.Errorf("command failed: %w", err)
|
||||
}
|
||||
return string(output), nil
|
||||
}
|
||||
```
|
||||
|
||||
### 9.2 File Operation Pattern
|
||||
```go
|
||||
func readConfigFile(path string) ([]byte, error) {
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("failed to read config: %w", err)
|
||||
}
|
||||
return data, nil
|
||||
}
|
||||
|
||||
func writeConfigFile(path string, data []byte) error {
|
||||
if err := os.WriteFile(path, data, 0644); err != nil {
|
||||
return fmt.Errorf("failed to write config: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 9.3 Database Integration Pattern
|
||||
```go
|
||||
func queryBaculaDB(query string, args ...interface{}) ([]map[string]interface{}, error) {
|
||||
rows, err := db.Query(query, args...)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
|
||||
// Process rows...
|
||||
return results, nil
|
||||
}
|
||||
```
|
||||
|
||||
## 10. Error Handling
|
||||
|
||||
### 10.1 Command Execution Errors
|
||||
- **Timeout**: Command execution timeout
|
||||
- **Exit Code**: Check command exit codes
|
||||
- **Output Parsing**: Handle parsing errors
|
||||
|
||||
### 10.2 File Operation Errors
|
||||
- **Permission Errors**: Handle permission denied
|
||||
- **File Not Found**: Handle missing files
|
||||
- **Write Errors**: Handle write failures
|
||||
|
||||
### 10.3 Database Integration Errors
|
||||
- **Connection Errors**: Handle database connection failures
|
||||
- **Query Errors**: Handle SQL query errors
|
||||
- **Transaction Errors**: Handle transaction failures
|
||||
|
||||
## 11. Monitoring & Health Checks
|
||||
|
||||
### 11.1 Integration Health
|
||||
- **ZFS Health**: Monitor ZFS pool health
|
||||
- **SCST Health**: Monitor SCST service status
|
||||
- **Bacula Health**: Monitor Bacula service status
|
||||
- **MHVTL Health**: Monitor MHVTL service status
|
||||
|
||||
### 11.2 Health Check Endpoints
|
||||
```
|
||||
GET /api/v1/health
|
||||
GET /api/v1/health/zfs
|
||||
GET /api/v1/health/scst
|
||||
GET /api/v1/health/bacula
|
||||
GET /api/v1/health/vtl
|
||||
```
|
||||
|
||||
## 12. Future Integrations
|
||||
|
||||
### 12.1 Planned Integrations
|
||||
- **LDAP/AD**: Directory service integration
|
||||
- **Cloud Storage**: Cloud backup integration
|
||||
- **Monitoring Systems**: Prometheus, Grafana integration
|
||||
- **Notification Systems**: Email, Slack, PagerDuty integration
|
||||
|
||||
283
docs/alpha/srs/SRS-00-Overview.md
Normal file
283
docs/alpha/srs/SRS-00-Overview.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# Software Requirements Specification (SRS)
|
||||
## 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 Requirements Specification (SRS) for AtlasOS - Calypso, an enterprise-grade backup appliance management system. The system provides unified management for storage, backup, tape libraries, and system administration through a modern web-based interface.
|
||||
|
||||
### 1.2 Scope
|
||||
Calypso is designed to manage:
|
||||
- ZFS storage pools and datasets
|
||||
- File sharing (SMB/CIFS and NFS)
|
||||
- iSCSI block storage targets
|
||||
- Physical and Virtual Tape Libraries (VTL)
|
||||
- Backup job management (Bacula/Bareos integration)
|
||||
- System monitoring and alerting
|
||||
- User and access management (IAM)
|
||||
- Object storage services
|
||||
- Snapshot and replication management
|
||||
|
||||
### 1.3 Definitions, Acronyms, and Abbreviations
|
||||
- **ZFS**: Zettabyte File System
|
||||
- **SMB/CIFS**: Server Message Block / Common Internet File System
|
||||
- **NFS**: Network File System
|
||||
- **iSCSI**: Internet Small Computer Systems Interface
|
||||
- **VTL**: Virtual Tape Library
|
||||
- **IAM**: Identity and Access Management
|
||||
- **RBAC**: Role-Based Access Control
|
||||
- **API**: Application Programming Interface
|
||||
- **REST**: Representational State Transfer
|
||||
- **JWT**: JSON Web Token
|
||||
- **SNMP**: Simple Network Management Protocol
|
||||
- **NTP**: Network Time Protocol
|
||||
|
||||
### 1.4 References
|
||||
- ZFS Documentation: https://openzfs.github.io/openzfs-docs/
|
||||
- SCST Documentation: http://scst.sourceforge.net/
|
||||
- Bacula Documentation: https://www.bacula.org/documentation/
|
||||
- React Documentation: https://react.dev/
|
||||
- Go Documentation: https://go.dev/doc/
|
||||
|
||||
### 1.5 Overview
|
||||
This SRS is organized into the following sections:
|
||||
- **SRS-01**: Storage Management
|
||||
- **SRS-02**: File Sharing (SMB/NFS)
|
||||
- **SRS-03**: iSCSI Management
|
||||
- **SRS-04**: Tape Library Management
|
||||
- **SRS-05**: Backup Management
|
||||
- **SRS-06**: Object Storage
|
||||
- **SRS-07**: Snapshot & Replication
|
||||
- **SRS-08**: System Management
|
||||
- **SRS-09**: Monitoring & Alerting
|
||||
- **SRS-10**: Identity & Access Management
|
||||
- **SRS-11**: User Interface & Experience
|
||||
|
||||
---
|
||||
|
||||
## 2. System Overview
|
||||
|
||||
### 2.1 System Architecture
|
||||
Calypso follows a client-server architecture:
|
||||
- **Frontend**: React-based Single Page Application (SPA)
|
||||
- **Backend**: Go-based REST API server
|
||||
- **Database**: PostgreSQL for persistent storage
|
||||
- **External Services**: ZFS, SCST, Bacula/Bareos, MHVTL
|
||||
|
||||
### 2.2 Technology Stack
|
||||
|
||||
#### Frontend
|
||||
- React 18 with TypeScript
|
||||
- Vite for build tooling
|
||||
- TailwindCSS for styling
|
||||
- TanStack Query for data fetching
|
||||
- React Router for navigation
|
||||
- Zustand for state management
|
||||
- Axios for HTTP requests
|
||||
- Lucide React for icons
|
||||
|
||||
#### Backend
|
||||
- Go 1.21+
|
||||
- Gin web framework
|
||||
- PostgreSQL database
|
||||
- JWT for authentication
|
||||
- Structured logging (zerolog)
|
||||
|
||||
### 2.3 Deployment Model
|
||||
- Single-server deployment
|
||||
- Systemd service management
|
||||
- Reverse proxy support (nginx/caddy)
|
||||
- WebSocket support for real-time updates
|
||||
|
||||
---
|
||||
|
||||
## 3. Functional Requirements
|
||||
|
||||
### 3.1 Authentication & Authorization
|
||||
- User login/logout
|
||||
- JWT-based session management
|
||||
- Role-based access control (Admin, Operator, ReadOnly)
|
||||
- Permission-based feature access
|
||||
- Session timeout and refresh
|
||||
|
||||
### 3.2 Storage Management
|
||||
- ZFS pool creation, deletion, and monitoring
|
||||
- Dataset management (filesystems and volumes)
|
||||
- Disk discovery and monitoring
|
||||
- Storage repository management
|
||||
- ARC statistics monitoring
|
||||
|
||||
### 3.3 File Sharing
|
||||
- SMB/CIFS share creation and configuration
|
||||
- NFS share creation and client management
|
||||
- Share access control
|
||||
- Mount point management
|
||||
|
||||
### 3.4 iSCSI Management
|
||||
- iSCSI target creation and management
|
||||
- LUN mapping and configuration
|
||||
- Initiator access control
|
||||
- Portal configuration
|
||||
- Extent management
|
||||
|
||||
### 3.5 Tape Library Management
|
||||
- Physical tape library discovery
|
||||
- Virtual Tape Library (VTL) management
|
||||
- Tape drive and slot management
|
||||
- Media inventory
|
||||
|
||||
### 3.6 Backup Management
|
||||
- Backup job creation and scheduling
|
||||
- Bacula/Bareos integration
|
||||
- Storage pool and volume management
|
||||
- Job history and monitoring
|
||||
- Client management
|
||||
|
||||
### 3.7 Object Storage
|
||||
- S3-compatible bucket management
|
||||
- Access policy configuration
|
||||
- User and key management
|
||||
- Usage monitoring
|
||||
|
||||
### 3.8 Snapshot & Replication
|
||||
- ZFS snapshot creation and management
|
||||
- Snapshot rollback and cloning
|
||||
- Replication task configuration
|
||||
- Remote replication management
|
||||
|
||||
### 3.9 System Management
|
||||
- Network interface configuration
|
||||
- Service management (start/stop/restart)
|
||||
- NTP configuration
|
||||
- SNMP configuration
|
||||
- System logs viewing
|
||||
- Terminal console access
|
||||
- Feature license management
|
||||
|
||||
### 3.10 Monitoring & Alerting
|
||||
- Real-time system metrics
|
||||
- Storage health monitoring
|
||||
- Network throughput monitoring
|
||||
- Alert rule configuration
|
||||
- Alert history and management
|
||||
|
||||
### 3.11 Identity & Access Management
|
||||
- User account management
|
||||
- Role management
|
||||
- Permission assignment
|
||||
- Group management
|
||||
- User profile management
|
||||
|
||||
---
|
||||
|
||||
## 4. Non-Functional Requirements
|
||||
|
||||
### 4.1 Performance
|
||||
- API response time < 200ms for read operations
|
||||
- API response time < 1s for write operations
|
||||
- Support for 100+ concurrent users
|
||||
- Real-time metrics update every 5-30 seconds
|
||||
|
||||
### 4.2 Security
|
||||
- HTTPS support
|
||||
- JWT token expiration and refresh
|
||||
- Password hashing (bcrypt)
|
||||
- SQL injection prevention
|
||||
- XSS protection
|
||||
- CSRF protection
|
||||
- Rate limiting
|
||||
- Audit logging
|
||||
|
||||
### 4.3 Reliability
|
||||
- Database transaction support
|
||||
- Error handling and recovery
|
||||
- Health check endpoints
|
||||
- Graceful shutdown
|
||||
|
||||
### 4.4 Usability
|
||||
- Responsive web design
|
||||
- Dark theme support
|
||||
- Intuitive navigation
|
||||
- Real-time feedback
|
||||
- Loading states
|
||||
- Error messages
|
||||
|
||||
### 4.5 Maintainability
|
||||
- Clean code architecture
|
||||
- Comprehensive logging
|
||||
- API documentation
|
||||
- Code comments
|
||||
- Modular design
|
||||
|
||||
---
|
||||
|
||||
## 5. System Constraints
|
||||
|
||||
### 5.1 Hardware Requirements
|
||||
- Minimum: 4GB RAM, 2 CPU cores, 100GB storage
|
||||
- Recommended: 8GB+ RAM, 4+ CPU cores, 500GB+ storage
|
||||
|
||||
### 5.2 Software Requirements
|
||||
- Linux-based operating system (Ubuntu 24.04+)
|
||||
- PostgreSQL 14+
|
||||
- ZFS support
|
||||
- SCST installed and configured
|
||||
- Bacula/Bareos (optional, for backup features)
|
||||
|
||||
### 5.3 Network Requirements
|
||||
- Network connectivity for remote access
|
||||
- SSH access for system management
|
||||
- Port 8080 (API) and 3000 (Frontend) accessible
|
||||
|
||||
---
|
||||
|
||||
## 6. Assumptions and Dependencies
|
||||
|
||||
### 6.1 Assumptions
|
||||
- System has root/sudo access for ZFS and system operations
|
||||
- Network interfaces are properly configured
|
||||
- External services (Bacula, SCST) are installed and accessible
|
||||
- Users have basic understanding of storage and backup concepts
|
||||
|
||||
### 6.2 Dependencies
|
||||
- PostgreSQL database
|
||||
- ZFS kernel module and tools
|
||||
- SCST kernel module and tools
|
||||
- Bacula/Bareos (for backup features)
|
||||
- MHVTL (for VTL features)
|
||||
|
||||
---
|
||||
|
||||
## 7. Future Enhancements
|
||||
|
||||
### 7.1 Planned Features
|
||||
- LDAP/Active Directory integration
|
||||
- Multi-site replication
|
||||
- Cloud backup integration
|
||||
- Advanced encryption at rest
|
||||
- WebSocket real-time updates
|
||||
- Mobile responsive improvements
|
||||
- Advanced reporting and analytics
|
||||
|
||||
### 7.2 Potential Enhancements
|
||||
- Multi-tenant support
|
||||
- API rate limiting per user
|
||||
- Advanced backup scheduling
|
||||
- Disaster recovery features
|
||||
- Performance optimization tools
|
||||
|
||||
---
|
||||
|
||||
## Document History
|
||||
|
||||
| Version | Date | Author | Changes |
|
||||
|---------|------|--------|---------|
|
||||
| 1.0.0-alpha | 2025-01-XX | Development Team | Initial SRS document |
|
||||
|
||||
127
docs/alpha/srs/SRS-01-Storage-Management.md
Normal file
127
docs/alpha/srs/SRS-01-Storage-Management.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# SRS-01: Storage Management
|
||||
|
||||
## 1. Overview
|
||||
Storage Management module provides comprehensive management of ZFS storage pools, datasets, disks, and storage repositories.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 ZFS Pool Management
|
||||
**FR-SM-001**: System shall allow users to create ZFS pools
|
||||
- **Input**: Pool name, RAID level, disk selection, compression, deduplication options
|
||||
- **Output**: Created pool with UUID
|
||||
- **Validation**: Pool name uniqueness, disk availability, RAID level compatibility
|
||||
|
||||
**FR-SM-002**: System shall allow users to list all ZFS pools
|
||||
- **Output**: List of pools with status, capacity, health information
|
||||
- **Refresh**: Auto-refresh every 2 minutes
|
||||
|
||||
**FR-SM-003**: System shall allow users to view ZFS pool details
|
||||
- **Output**: Pool configuration, capacity, health, datasets, disk information
|
||||
|
||||
**FR-SM-004**: System shall allow users to delete ZFS pools
|
||||
- **Validation**: Pool must be empty or confirmation required
|
||||
- **Side Effect**: All datasets in pool are destroyed
|
||||
|
||||
**FR-SM-005**: System shall allow users to add spare disks to pools
|
||||
- **Input**: Pool ID, disk list
|
||||
- **Validation**: Disk availability, compatibility
|
||||
|
||||
### 2.2 ZFS Dataset Management
|
||||
**FR-SM-006**: System shall allow users to create ZFS datasets
|
||||
- **Input**: Pool ID, dataset name, type (filesystem/volume), compression, quota, reservation, mount point
|
||||
- **Output**: Created dataset with UUID
|
||||
- **Validation**: Name uniqueness within pool, valid mount point
|
||||
|
||||
**FR-SM-007**: System shall allow users to list datasets in a pool
|
||||
- **Input**: Pool ID
|
||||
- **Output**: List of datasets with properties
|
||||
- **Refresh**: Auto-refresh every 1 second
|
||||
|
||||
**FR-SM-008**: System shall allow users to delete ZFS datasets
|
||||
- **Input**: Pool ID, dataset name
|
||||
- **Validation**: Dataset must not be in use
|
||||
|
||||
### 2.3 Disk Management
|
||||
**FR-SM-009**: System shall discover and list all physical disks
|
||||
- **Output**: Disk list with size, type, status, mount information
|
||||
- **Refresh**: Auto-refresh every 5 minutes
|
||||
|
||||
**FR-SM-010**: System shall allow users to manually sync disk discovery
|
||||
- **Action**: Trigger disk rescan
|
||||
|
||||
**FR-SM-011**: System shall display disk details
|
||||
- **Output**: Disk properties, partitions, usage, health status
|
||||
|
||||
### 2.4 Storage Repository Management
|
||||
**FR-SM-012**: System shall allow users to create storage repositories
|
||||
- **Input**: Name, type, path, capacity
|
||||
- **Output**: Created repository with ID
|
||||
|
||||
**FR-SM-013**: System shall allow users to list storage repositories
|
||||
- **Output**: Repository list with capacity, usage, status
|
||||
|
||||
**FR-SM-014**: System shall allow users to view repository details
|
||||
- **Output**: Repository properties, usage statistics
|
||||
|
||||
**FR-SM-015**: System shall allow users to delete storage repositories
|
||||
- **Validation**: Repository must not be in use
|
||||
|
||||
### 2.5 ARC Statistics
|
||||
**FR-SM-016**: System shall display ZFS ARC statistics
|
||||
- **Output**: Hit ratio, cache size, eviction statistics
|
||||
- **Refresh**: Real-time updates
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Storage Dashboard
|
||||
- Pool overview cards with capacity and health
|
||||
- Dataset tree view
|
||||
- Disk list with status indicators
|
||||
- Quick actions (create pool, create dataset)
|
||||
|
||||
### 3.2 Pool Management
|
||||
- Pool creation wizard
|
||||
- Pool detail view with tabs (Overview, Datasets, Disks, Settings)
|
||||
- Pool deletion confirmation dialog
|
||||
|
||||
### 3.3 Dataset Management
|
||||
- Dataset creation form
|
||||
- Dataset list with filtering and sorting
|
||||
- Dataset detail view
|
||||
- Dataset deletion confirmation
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/storage/zfs/pools
|
||||
GET /api/v1/storage/zfs/pools/:id
|
||||
POST /api/v1/storage/zfs/pools
|
||||
DELETE /api/v1/storage/zfs/pools/:id
|
||||
POST /api/v1/storage/zfs/pools/:id/spare
|
||||
|
||||
GET /api/v1/storage/zfs/pools/:id/datasets
|
||||
POST /api/v1/storage/zfs/pools/:id/datasets
|
||||
DELETE /api/v1/storage/zfs/pools/:id/datasets/:dataset
|
||||
|
||||
GET /api/v1/storage/disks
|
||||
POST /api/v1/storage/disks/sync
|
||||
|
||||
GET /api/v1/storage/repositories
|
||||
GET /api/v1/storage/repositories/:id
|
||||
POST /api/v1/storage/repositories
|
||||
DELETE /api/v1/storage/repositories/:id
|
||||
|
||||
GET /api/v1/storage/zfs/arc/stats
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **storage:read**: Required for all read operations
|
||||
- **storage:write**: Required for create, update, delete operations
|
||||
|
||||
## 6. Error Handling
|
||||
- Invalid pool name format
|
||||
- Disk not available
|
||||
- Pool already exists
|
||||
- Dataset in use
|
||||
- Insufficient permissions
|
||||
|
||||
141
docs/alpha/srs/SRS-02-File-Sharing.md
Normal file
141
docs/alpha/srs/SRS-02-File-Sharing.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# SRS-02: File Sharing (SMB/NFS)
|
||||
|
||||
## 1. Overview
|
||||
File Sharing module provides management of SMB/CIFS and NFS shares for network file access.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Share Management
|
||||
**FR-FS-001**: System shall allow users to create shares
|
||||
- **Input**: Dataset ID, share type (SMB/NFS/Both), share name, mount point
|
||||
- **Output**: Created share with UUID
|
||||
- **Validation**: Dataset exists, share name uniqueness
|
||||
|
||||
**FR-FS-002**: System shall allow users to list all shares
|
||||
- **Output**: Share list with type, dataset, status
|
||||
- **Filtering**: By protocol, dataset, status
|
||||
|
||||
**FR-FS-003**: System shall allow users to view share details
|
||||
- **Output**: Share configuration, protocol settings, access control
|
||||
|
||||
**FR-FS-004**: System shall allow users to update shares
|
||||
- **Input**: Share ID, updated configuration
|
||||
- **Validation**: Valid configuration values
|
||||
|
||||
**FR-FS-005**: System shall allow users to delete shares
|
||||
- **Validation**: Share must not be actively accessed
|
||||
|
||||
### 2.2 SMB/CIFS Configuration
|
||||
**FR-FS-006**: System shall allow users to configure SMB share name
|
||||
- **Input**: Share ID, SMB share name
|
||||
- **Validation**: Valid SMB share name format
|
||||
|
||||
**FR-FS-007**: System shall allow users to configure SMB path
|
||||
- **Input**: Share ID, SMB path
|
||||
- **Validation**: Path exists and is accessible
|
||||
|
||||
**FR-FS-008**: System shall allow users to configure SMB comment
|
||||
- **Input**: Share ID, comment text
|
||||
|
||||
**FR-FS-009**: System shall allow users to enable/disable guest access
|
||||
- **Input**: Share ID, guest access flag
|
||||
|
||||
**FR-FS-010**: System shall allow users to configure read-only access
|
||||
- **Input**: Share ID, read-only flag
|
||||
|
||||
**FR-FS-011**: System shall allow users to configure browseable option
|
||||
- **Input**: Share ID, browseable flag
|
||||
|
||||
### 2.3 NFS Configuration
|
||||
**FR-FS-012**: System shall allow users to configure NFS clients
|
||||
- **Input**: Share ID, client list (IP addresses or hostnames)
|
||||
- **Validation**: Valid IP/hostname format
|
||||
|
||||
**FR-FS-013**: System shall allow users to add NFS clients
|
||||
- **Input**: Share ID, client address
|
||||
- **Validation**: Client not already in list
|
||||
|
||||
**FR-FS-014**: System shall allow users to remove NFS clients
|
||||
- **Input**: Share ID, client address
|
||||
|
||||
**FR-FS-015**: System shall allow users to configure NFS options
|
||||
- **Input**: Share ID, NFS options (ro, rw, sync, async, etc.)
|
||||
|
||||
### 2.4 Share Status
|
||||
**FR-FS-016**: System shall display share status (enabled/disabled)
|
||||
- **Output**: Current status for each protocol
|
||||
|
||||
**FR-FS-017**: System shall allow users to enable/disable SMB protocol
|
||||
- **Input**: Share ID, enabled flag
|
||||
|
||||
**FR-FS-018**: System shall allow users to enable/disable NFS protocol
|
||||
- **Input**: Share ID, enabled flag
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Share List View
|
||||
- Master-detail layout
|
||||
- Search and filter functionality
|
||||
- Protocol indicators (SMB/NFS badges)
|
||||
- Status indicators
|
||||
|
||||
### 3.2 Share Detail View
|
||||
- Protocol tabs (SMB, NFS)
|
||||
- Configuration forms
|
||||
- Client management (for NFS)
|
||||
- Quick actions (enable/disable protocols)
|
||||
|
||||
### 3.3 Create Share Modal
|
||||
- Dataset selection
|
||||
- Share name input
|
||||
- Protocol selection
|
||||
- Initial configuration
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/shares
|
||||
GET /api/v1/shares/:id
|
||||
POST /api/v1/shares
|
||||
PUT /api/v1/shares/:id
|
||||
DELETE /api/v1/shares/:id
|
||||
```
|
||||
|
||||
## 5. Data Model
|
||||
|
||||
### Share Object
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"dataset_id": "uuid",
|
||||
"dataset_name": "string",
|
||||
"mount_point": "string",
|
||||
"share_type": "smb|nfs|both",
|
||||
"smb_enabled": boolean,
|
||||
"smb_share_name": "string",
|
||||
"smb_path": "string",
|
||||
"smb_comment": "string",
|
||||
"smb_guest_ok": boolean,
|
||||
"smb_read_only": boolean,
|
||||
"smb_browseable": boolean,
|
||||
"nfs_enabled": boolean,
|
||||
"nfs_clients": ["string"],
|
||||
"nfs_options": "string",
|
||||
"is_active": boolean,
|
||||
"created_at": "timestamp",
|
||||
"updated_at": "timestamp",
|
||||
"created_by": "uuid"
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Permissions
|
||||
- **storage:read**: Required for viewing shares
|
||||
- **storage:write**: Required for creating, updating, deleting shares
|
||||
|
||||
## 7. Error Handling
|
||||
- Invalid dataset ID
|
||||
- Duplicate share name
|
||||
- Invalid client address format
|
||||
- Share in use
|
||||
- Insufficient permissions
|
||||
|
||||
163
docs/alpha/srs/SRS-03-iSCSI-Management.md
Normal file
163
docs/alpha/srs/SRS-03-iSCSI-Management.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# SRS-03: iSCSI Management
|
||||
|
||||
## 1. Overview
|
||||
iSCSI Management module provides configuration and management of iSCSI targets, LUNs, initiators, and portals using SCST.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Target Management
|
||||
**FR-ISCSI-001**: System shall allow users to create iSCSI targets
|
||||
- **Input**: Target name, alias
|
||||
- **Output**: Created target with ID
|
||||
- **Validation**: Target name uniqueness, valid IQN format
|
||||
|
||||
**FR-ISCSI-002**: System shall allow users to list all iSCSI targets
|
||||
- **Output**: Target list with status, LUN count, initiator count
|
||||
|
||||
**FR-ISCSI-003**: System shall allow users to view target details
|
||||
- **Output**: Target configuration, LUNs, initiators, status
|
||||
|
||||
**FR-ISCSI-004**: System shall allow users to delete iSCSI targets
|
||||
- **Validation**: Target must not be in use
|
||||
|
||||
**FR-ISCSI-005**: System shall allow users to enable/disable targets
|
||||
- **Input**: Target ID, enabled flag
|
||||
|
||||
### 2.2 LUN Management
|
||||
**FR-ISCSI-006**: System shall allow users to add LUNs to targets
|
||||
- **Input**: Target ID, device path, LUN number
|
||||
- **Validation**: Device exists, LUN number available
|
||||
|
||||
**FR-ISCSI-007**: System shall allow users to remove LUNs from targets
|
||||
- **Input**: Target ID, LUN ID
|
||||
|
||||
**FR-ISCSI-008**: System shall display LUN information
|
||||
- **Output**: LUN number, device, size, status
|
||||
|
||||
### 2.3 Initiator Management
|
||||
**FR-ISCSI-009**: System shall allow users to add initiators to targets
|
||||
- **Input**: Target ID, initiator IQN
|
||||
- **Validation**: Valid IQN format
|
||||
|
||||
**FR-ISCSI-010**: System shall allow users to remove initiators from targets
|
||||
- **Input**: Target ID, initiator ID
|
||||
|
||||
**FR-ISCSI-011**: System shall allow users to list all initiators
|
||||
- **Output**: Initiator list with associated targets
|
||||
|
||||
**FR-ISCSI-012**: System shall allow users to create initiator groups
|
||||
- **Input**: Group name, initiator list
|
||||
- **Output**: Created group with ID
|
||||
|
||||
**FR-ISCSI-013**: System shall allow users to manage initiator groups
|
||||
- **Actions**: Create, update, delete, add/remove initiators
|
||||
|
||||
### 2.4 Portal Management
|
||||
**FR-ISCSI-014**: System shall allow users to create portals
|
||||
- **Input**: IP address, port
|
||||
- **Output**: Created portal with ID
|
||||
|
||||
**FR-ISCSI-015**: System shall allow users to list portals
|
||||
- **Output**: Portal list with IP, port, status
|
||||
|
||||
**FR-ISCSI-016**: System shall allow users to update portals
|
||||
- **Input**: Portal ID, updated configuration
|
||||
|
||||
**FR-ISCSI-017**: System shall allow users to delete portals
|
||||
- **Input**: Portal ID
|
||||
|
||||
### 2.5 Extent Management
|
||||
**FR-ISCSI-018**: System shall allow users to create extents
|
||||
- **Input**: Device path, size, type
|
||||
- **Output**: Created extent
|
||||
|
||||
**FR-ISCSI-019**: System shall allow users to list extents
|
||||
- **Output**: Extent list with device, size, type
|
||||
|
||||
**FR-ISCSI-020**: System shall allow users to delete extents
|
||||
- **Input**: Extent device
|
||||
|
||||
### 2.6 Configuration Management
|
||||
**FR-ISCSI-021**: System shall allow users to view SCST configuration file
|
||||
- **Output**: Current SCST configuration
|
||||
|
||||
**FR-ISCSI-022**: System shall allow users to update SCST configuration file
|
||||
- **Input**: Configuration content
|
||||
- **Validation**: Valid SCST configuration format
|
||||
|
||||
**FR-ISCSI-023**: System shall allow users to apply SCST configuration
|
||||
- **Action**: Reload SCST configuration
|
||||
- **Side Effect**: Targets may be restarted
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Target List View
|
||||
- Target cards with status indicators
|
||||
- Quick actions (enable/disable, delete)
|
||||
- Filter and search functionality
|
||||
|
||||
### 3.2 Target Detail View
|
||||
- Overview tab (target info, status)
|
||||
- LUNs tab (LUN list, add/remove)
|
||||
- Initiators tab (initiator list, add/remove)
|
||||
- Settings tab (target configuration)
|
||||
|
||||
### 3.3 Create Target Wizard
|
||||
- Target name input
|
||||
- Alias input
|
||||
- Initial LUN assignment (optional)
|
||||
- Initial initiator assignment (optional)
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/scst/targets
|
||||
GET /api/v1/scst/targets/:id
|
||||
POST /api/v1/scst/targets
|
||||
DELETE /api/v1/scst/targets/:id
|
||||
POST /api/v1/scst/targets/:id/enable
|
||||
POST /api/v1/scst/targets/:id/disable
|
||||
|
||||
POST /api/v1/scst/targets/:id/luns
|
||||
DELETE /api/v1/scst/targets/:id/luns/:lunId
|
||||
|
||||
POST /api/v1/scst/targets/:id/initiators
|
||||
GET /api/v1/scst/initiators
|
||||
GET /api/v1/scst/initiators/:id
|
||||
DELETE /api/v1/scst/initiators/:id
|
||||
|
||||
GET /api/v1/scst/initiator-groups
|
||||
GET /api/v1/scst/initiator-groups/:id
|
||||
POST /api/v1/scst/initiator-groups
|
||||
PUT /api/v1/scst/initiator-groups/:id
|
||||
DELETE /api/v1/scst/initiator-groups/:id
|
||||
POST /api/v1/scst/initiator-groups/:id/initiators
|
||||
|
||||
GET /api/v1/scst/portals
|
||||
GET /api/v1/scst/portals/:id
|
||||
POST /api/v1/scst/portals
|
||||
PUT /api/v1/scst/portals/:id
|
||||
DELETE /api/v1/scst/portals/:id
|
||||
|
||||
GET /api/v1/scst/extents
|
||||
POST /api/v1/scst/extents
|
||||
DELETE /api/v1/scst/extents/:device
|
||||
|
||||
GET /api/v1/scst/config/file
|
||||
PUT /api/v1/scst/config/file
|
||||
POST /api/v1/scst/config/apply
|
||||
|
||||
GET /api/v1/scst/handlers
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **iscsi:read**: Required for viewing targets, initiators, portals
|
||||
- **iscsi:write**: Required for creating, updating, deleting
|
||||
|
||||
## 6. Error Handling
|
||||
- Invalid IQN format
|
||||
- Target name already exists
|
||||
- Device not available
|
||||
- SCST configuration errors
|
||||
- Insufficient permissions
|
||||
|
||||
115
docs/alpha/srs/SRS-04-Tape-Library-Management.md
Normal file
115
docs/alpha/srs/SRS-04-Tape-Library-Management.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# SRS-04: Tape Library Management
|
||||
|
||||
## 1. Overview
|
||||
Tape Library Management module provides management of physical and virtual tape libraries, drives, slots, and media.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Physical Tape Library
|
||||
**FR-TAPE-001**: System shall discover physical tape libraries
|
||||
- **Action**: Scan for attached tape libraries
|
||||
- **Output**: List of discovered libraries
|
||||
|
||||
**FR-TAPE-002**: System shall list physical tape libraries
|
||||
- **Output**: Library list with vendor, model, serial number
|
||||
|
||||
**FR-TAPE-003**: System shall display physical library details
|
||||
- **Output**: Library properties, drives, slots, media
|
||||
|
||||
**FR-TAPE-004**: System shall allow users to load media
|
||||
- **Input**: Library ID, drive ID, slot ID
|
||||
- **Action**: Load tape from slot to drive
|
||||
|
||||
**FR-TAPE-005**: System shall allow users to unload media
|
||||
- **Input**: Library ID, drive ID, slot ID
|
||||
- **Action**: Unload tape from drive to slot
|
||||
|
||||
### 2.2 Virtual Tape Library (VTL)
|
||||
**FR-TAPE-006**: System shall allow users to create VTL libraries
|
||||
- **Input**: Library name, vendor, model, drive count, slot count
|
||||
- **Output**: Created VTL with ID
|
||||
|
||||
**FR-TAPE-007**: System shall allow users to list VTL libraries
|
||||
- **Output**: VTL list with status, drive count, slot count
|
||||
|
||||
**FR-TAPE-008**: System shall allow users to view VTL details
|
||||
- **Output**: VTL configuration, drives, slots, media
|
||||
|
||||
**FR-TAPE-009**: System shall allow users to update VTL libraries
|
||||
- **Input**: VTL ID, updated configuration
|
||||
|
||||
**FR-TAPE-010**: System shall allow users to delete VTL libraries
|
||||
- **Input**: VTL ID
|
||||
- **Validation**: VTL must not be in use
|
||||
|
||||
**FR-TAPE-011**: System shall allow users to start/stop VTL libraries
|
||||
- **Input**: VTL ID, action (start/stop)
|
||||
|
||||
### 2.3 Drive Management
|
||||
**FR-TAPE-012**: System shall display drive information
|
||||
- **Output**: Drive status, media loaded, position
|
||||
|
||||
**FR-TAPE-013**: System shall allow users to control drives
|
||||
- **Actions**: Load, unload, eject, rewind
|
||||
|
||||
### 2.4 Slot Management
|
||||
**FR-TAPE-014**: System shall display slot information
|
||||
- **Output**: Slot status, media present, media label
|
||||
|
||||
**FR-TAPE-015**: System shall allow users to manage slots
|
||||
- **Actions**: View media, move media
|
||||
|
||||
### 2.5 Media Management
|
||||
**FR-TAPE-016**: System shall display media inventory
|
||||
- **Output**: Media list with label, type, status, location
|
||||
|
||||
**FR-TAPE-017**: System shall allow users to label media
|
||||
- **Input**: Media ID, label
|
||||
- **Validation**: Valid label format
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Library List View
|
||||
- Physical and VTL library cards
|
||||
- Status indicators
|
||||
- Quick actions (discover, create VTL)
|
||||
|
||||
### 3.2 Library Detail View
|
||||
- Overview tab (library info, status)
|
||||
- Drives tab (drive list, controls)
|
||||
- Slots tab (slot grid, media info)
|
||||
- Media tab (media inventory)
|
||||
|
||||
### 3.3 VTL Creation Wizard
|
||||
- Library name and configuration
|
||||
- Drive and slot count
|
||||
- Vendor and model selection
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/tape/physical/libraries
|
||||
POST /api/v1/tape/physical/libraries/discover
|
||||
GET /api/v1/tape/physical/libraries/:id
|
||||
|
||||
GET /api/v1/tape/vtl/libraries
|
||||
GET /api/v1/tape/vtl/libraries/:id
|
||||
POST /api/v1/tape/vtl/libraries
|
||||
PUT /api/v1/tape/vtl/libraries/:id
|
||||
DELETE /api/v1/tape/vtl/libraries/:id
|
||||
POST /api/v1/tape/vtl/libraries/:id/start
|
||||
POST /api/v1/tape/vtl/libraries/:id/stop
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **tape:read**: Required for viewing libraries
|
||||
- **tape:write**: Required for creating, updating, deleting, controlling
|
||||
|
||||
## 6. Error Handling
|
||||
- Library not found
|
||||
- Drive not available
|
||||
- Slot already occupied
|
||||
- Media not found
|
||||
- MHVTL service errors
|
||||
- Insufficient permissions
|
||||
|
||||
130
docs/alpha/srs/SRS-05-Backup-Management.md
Normal file
130
docs/alpha/srs/SRS-05-Backup-Management.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# SRS-05: Backup Management
|
||||
|
||||
## 1. Overview
|
||||
Backup Management module provides integration with Bacula/Bareos for backup job management, scheduling, and monitoring.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Backup Jobs
|
||||
**FR-BACKUP-001**: System shall allow users to create backup jobs
|
||||
- **Input**: Job name, client, fileset, schedule, storage pool
|
||||
- **Output**: Created job with ID
|
||||
- **Validation**: Valid client, fileset, schedule
|
||||
|
||||
**FR-BACKUP-002**: System shall allow users to list backup jobs
|
||||
- **Output**: Job list with status, last run, next run
|
||||
- **Filtering**: By status, client, schedule
|
||||
|
||||
**FR-BACKUP-003**: System shall allow users to view job details
|
||||
- **Output**: Job configuration, history, statistics
|
||||
|
||||
**FR-BACKUP-004**: System shall allow users to run jobs manually
|
||||
- **Input**: Job ID
|
||||
- **Action**: Trigger immediate job execution
|
||||
|
||||
**FR-BACKUP-005**: System shall display job history
|
||||
- **Output**: Job run history with status, duration, data transferred
|
||||
|
||||
### 2.2 Clients
|
||||
**FR-BACKUP-006**: System shall list backup clients
|
||||
- **Output**: Client list with status, last backup
|
||||
|
||||
**FR-BACKUP-007**: System shall display client details
|
||||
- **Output**: Client configuration, job history
|
||||
|
||||
### 2.3 Storage Pools
|
||||
**FR-BACKUP-008**: System shall allow users to create storage pools
|
||||
- **Input**: Pool name, pool type, volume count
|
||||
- **Output**: Created pool with ID
|
||||
|
||||
**FR-BACKUP-009**: System shall allow users to list storage pools
|
||||
- **Output**: Pool list with type, volume count, usage
|
||||
|
||||
**FR-BACKUP-010**: System shall allow users to delete storage pools
|
||||
- **Input**: Pool ID
|
||||
- **Validation**: Pool must not be in use
|
||||
|
||||
### 2.4 Storage Volumes
|
||||
**FR-BACKUP-011**: System shall allow users to create storage volumes
|
||||
- **Input**: Pool ID, volume name, size
|
||||
- **Output**: Created volume with ID
|
||||
|
||||
**FR-BACKUP-012**: System shall allow users to list storage volumes
|
||||
- **Output**: Volume list with status, usage, expiration
|
||||
|
||||
**FR-BACKUP-013**: System shall allow users to update storage volumes
|
||||
- **Input**: Volume ID, updated properties
|
||||
|
||||
**FR-BACKUP-014**: System shall allow users to delete storage volumes
|
||||
- **Input**: Volume ID
|
||||
|
||||
### 2.5 Media Management
|
||||
**FR-BACKUP-015**: System shall list backup media
|
||||
- **Output**: Media list with label, type, status, location
|
||||
|
||||
**FR-BACKUP-016**: System shall display media details
|
||||
- **Output**: Media properties, job history, usage
|
||||
|
||||
### 2.6 Dashboard Statistics
|
||||
**FR-BACKUP-017**: System shall display backup dashboard statistics
|
||||
- **Output**: Total jobs, running jobs, success rate, data backed up
|
||||
|
||||
### 2.7 Bconsole Integration
|
||||
**FR-BACKUP-018**: System shall allow users to execute bconsole commands
|
||||
- **Input**: Command string
|
||||
- **Output**: Command output
|
||||
- **Validation**: Allowed commands only
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Backup Dashboard
|
||||
- Statistics cards (total jobs, running, success rate)
|
||||
- Recent job activity
|
||||
- Quick actions
|
||||
|
||||
### 3.2 Job Management
|
||||
- Job list with filtering
|
||||
- Job creation wizard
|
||||
- Job detail view with history
|
||||
- Job run controls
|
||||
|
||||
### 3.3 Storage Management
|
||||
- Storage pool list and management
|
||||
- Volume list and management
|
||||
- Media inventory
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/backup/dashboard/stats
|
||||
GET /api/v1/backup/jobs
|
||||
GET /api/v1/backup/jobs/:id
|
||||
POST /api/v1/backup/jobs
|
||||
|
||||
GET /api/v1/backup/clients
|
||||
GET /api/v1/backup/storage/pools
|
||||
POST /api/v1/backup/storage/pools
|
||||
DELETE /api/v1/backup/storage/pools/:id
|
||||
|
||||
GET /api/v1/backup/storage/volumes
|
||||
POST /api/v1/backup/storage/volumes
|
||||
PUT /api/v1/backup/storage/volumes/:id
|
||||
DELETE /api/v1/backup/storage/volumes/:id
|
||||
|
||||
GET /api/v1/backup/media
|
||||
GET /api/v1/backup/storage/daemons
|
||||
|
||||
POST /api/v1/backup/console/execute
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **backup:read**: Required for viewing jobs, clients, storage
|
||||
- **backup:write**: Required for creating, updating, deleting, executing
|
||||
|
||||
## 6. Error Handling
|
||||
- Bacula/Bareos connection errors
|
||||
- Invalid job configuration
|
||||
- Job execution failures
|
||||
- Storage pool/volume errors
|
||||
- Insufficient permissions
|
||||
|
||||
111
docs/alpha/srs/SRS-06-Object-Storage.md
Normal file
111
docs/alpha/srs/SRS-06-Object-Storage.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# SRS-06: Object Storage
|
||||
|
||||
## 1. Overview
|
||||
Object Storage module provides S3-compatible object storage service management including buckets, access policies, and user/key management.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Bucket Management
|
||||
**FR-OBJ-001**: System shall allow users to create buckets
|
||||
- **Input**: Bucket name, access policy (private/public-read)
|
||||
- **Output**: Created bucket with ID
|
||||
- **Validation**: Bucket name uniqueness, valid S3 naming
|
||||
|
||||
**FR-OBJ-002**: System shall allow users to list buckets
|
||||
- **Output**: Bucket list with name, type, usage, object count
|
||||
- **Filtering**: By name, type, access policy
|
||||
|
||||
**FR-OBJ-003**: System shall allow users to view bucket details
|
||||
- **Output**: Bucket configuration, usage statistics, access policy
|
||||
|
||||
**FR-OBJ-004**: System shall allow users to delete buckets
|
||||
- **Input**: Bucket ID
|
||||
- **Validation**: Bucket must be empty or confirmation required
|
||||
|
||||
**FR-OBJ-005**: System shall display bucket usage
|
||||
- **Output**: Storage used, object count, last modified
|
||||
|
||||
### 2.2 Access Policy Management
|
||||
**FR-OBJ-006**: System shall allow users to configure bucket access policies
|
||||
- **Input**: Bucket ID, access policy (private, public-read, public-read-write)
|
||||
- **Output**: Updated access policy
|
||||
|
||||
**FR-OBJ-007**: System shall display current access policy
|
||||
- **Output**: Policy type, policy document
|
||||
|
||||
### 2.3 User & Key Management
|
||||
**FR-OBJ-008**: System shall allow users to create S3 users
|
||||
- **Input**: Username, access level
|
||||
- **Output**: Created user with access keys
|
||||
|
||||
**FR-OBJ-009**: System shall allow users to list S3 users
|
||||
- **Output**: User list with access level, key count
|
||||
|
||||
**FR-OBJ-010**: System shall allow users to generate access keys
|
||||
- **Input**: User ID
|
||||
- **Output**: Access key ID and secret key
|
||||
|
||||
**FR-OBJ-011**: System shall allow users to revoke access keys
|
||||
- **Input**: User ID, key ID
|
||||
|
||||
### 2.4 Service Management
|
||||
**FR-OBJ-012**: System shall display service status
|
||||
- **Output**: Service status (running/stopped), uptime
|
||||
|
||||
**FR-OBJ-013**: System shall display service statistics
|
||||
- **Output**: Total usage, object count, endpoint URL
|
||||
|
||||
**FR-OBJ-014**: System shall display S3 endpoint URL
|
||||
- **Output**: Endpoint URL with copy functionality
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Object Storage Dashboard
|
||||
- Service status card
|
||||
- Statistics cards (total usage, object count, uptime)
|
||||
- S3 endpoint display with copy button
|
||||
|
||||
### 3.2 Bucket Management
|
||||
- Bucket list with search and filter
|
||||
- Bucket creation modal
|
||||
- Bucket detail view with tabs (Overview, Settings, Access Policy)
|
||||
- Bucket actions (delete, configure)
|
||||
|
||||
### 3.3 Tabs
|
||||
- **Buckets**: Main bucket management
|
||||
- **Users & Keys**: S3 user and access key management
|
||||
- **Monitoring**: Usage statistics and monitoring
|
||||
- **Settings**: Service configuration
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/object-storage/buckets
|
||||
GET /api/v1/object-storage/buckets/:id
|
||||
POST /api/v1/object-storage/buckets
|
||||
DELETE /api/v1/object-storage/buckets/:id
|
||||
PUT /api/v1/object-storage/buckets/:id/policy
|
||||
|
||||
GET /api/v1/object-storage/users
|
||||
POST /api/v1/object-storage/users
|
||||
GET /api/v1/object-storage/users/:id/keys
|
||||
POST /api/v1/object-storage/users/:id/keys
|
||||
DELETE /api/v1/object-storage/users/:id/keys/:keyId
|
||||
|
||||
GET /api/v1/object-storage/service/status
|
||||
GET /api/v1/object-storage/service/stats
|
||||
GET /api/v1/object-storage/service/endpoint
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **object-storage:read**: Required for viewing buckets, users
|
||||
- **object-storage:write**: Required for creating, updating, deleting
|
||||
|
||||
## 6. Error Handling
|
||||
- Invalid bucket name
|
||||
- Bucket already exists
|
||||
- Bucket not empty
|
||||
- Invalid access policy
|
||||
- Service not available
|
||||
- Insufficient permissions
|
||||
|
||||
145
docs/alpha/srs/SRS-07-Snapshot-Replication.md
Normal file
145
docs/alpha/srs/SRS-07-Snapshot-Replication.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# SRS-07: Snapshot & Replication
|
||||
|
||||
## 1. Overview
|
||||
Snapshot & Replication module provides ZFS snapshot management and remote replication task configuration.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Snapshot Management
|
||||
**FR-SNAP-001**: System shall allow users to create snapshots
|
||||
- **Input**: Dataset name, snapshot name
|
||||
- **Output**: Created snapshot with timestamp
|
||||
- **Validation**: Dataset exists, snapshot name uniqueness
|
||||
|
||||
**FR-SNAP-002**: System shall allow users to list snapshots
|
||||
- **Output**: Snapshot list with name, dataset, created date, referenced size
|
||||
- **Filtering**: By dataset, date range, name
|
||||
|
||||
**FR-SNAP-003**: System shall allow users to view snapshot details
|
||||
- **Output**: Snapshot properties, dataset, size, creation date
|
||||
|
||||
**FR-SNAP-004**: System shall allow users to delete snapshots
|
||||
- **Input**: Snapshot ID
|
||||
- **Validation**: Snapshot not in use
|
||||
|
||||
**FR-SNAP-005**: System shall allow users to rollback to snapshot
|
||||
- **Input**: Snapshot ID
|
||||
- **Warning**: Data loss warning required
|
||||
- **Action**: Rollback dataset to snapshot state
|
||||
|
||||
**FR-SNAP-006**: System shall allow users to clone snapshots
|
||||
- **Input**: Snapshot ID, clone name
|
||||
- **Output**: Created clone dataset
|
||||
|
||||
**FR-SNAP-007**: System shall display snapshot retention information
|
||||
- **Output**: Snapshots marked for expiration, retention policy
|
||||
|
||||
### 2.2 Replication Management
|
||||
**FR-SNAP-008**: System shall allow users to create replication tasks
|
||||
- **Input**: Task name, source dataset, target host, target dataset, schedule, compression
|
||||
- **Output**: Created replication task with ID
|
||||
- **Validation**: Valid source dataset, target host reachable
|
||||
|
||||
**FR-SNAP-009**: System shall allow users to list replication tasks
|
||||
- **Output**: Task list with status, last run, next run
|
||||
|
||||
**FR-SNAP-010**: System shall allow users to view replication task details
|
||||
- **Output**: Task configuration, history, status
|
||||
|
||||
**FR-SNAP-011**: System shall allow users to update replication tasks
|
||||
- **Input**: Task ID, updated configuration
|
||||
|
||||
**FR-SNAP-012**: System shall allow users to delete replication tasks
|
||||
- **Input**: Task ID
|
||||
|
||||
**FR-SNAP-013**: System shall display replication status
|
||||
- **Output**: Task status (idle, running, error), progress percentage
|
||||
|
||||
**FR-SNAP-014**: System shall allow users to run replication manually
|
||||
- **Input**: Task ID
|
||||
- **Action**: Trigger immediate replication
|
||||
|
||||
### 2.3 Replication Configuration
|
||||
**FR-SNAP-015**: System shall allow users to configure replication schedule
|
||||
- **Input**: Schedule type (hourly, daily, weekly, monthly, custom cron)
|
||||
- **Input**: Schedule time
|
||||
|
||||
**FR-SNAP-016**: System shall allow users to configure target settings
|
||||
- **Input**: Target host, SSH port, target user, target dataset
|
||||
|
||||
**FR-SNAP-017**: System shall allow users to configure compression
|
||||
- **Input**: Compression type (off, lz4, gzip, zstd)
|
||||
|
||||
**FR-SNAP-018**: System shall allow users to configure replication options
|
||||
- **Input**: Recursive flag, auto-snapshot flag, encryption flag
|
||||
|
||||
### 2.4 Restore Points
|
||||
**FR-SNAP-019**: System shall display restore points
|
||||
- **Output**: Available restore points from snapshots
|
||||
|
||||
**FR-SNAP-020**: System shall allow users to restore from snapshot
|
||||
- **Input**: Snapshot ID, restore target
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Snapshot & Replication Dashboard
|
||||
- Statistics cards (total snapshots, last replication, next scheduled)
|
||||
- Quick actions (create snapshot, view logs)
|
||||
|
||||
### 3.2 Tabs
|
||||
- **Snapshots**: Snapshot list and management
|
||||
- **Replication Tasks**: Replication task management
|
||||
- **Restore Points**: Restore point management
|
||||
|
||||
### 3.3 Snapshot List
|
||||
- Table view with columns (name, dataset, created, referenced, actions)
|
||||
- Search and filter functionality
|
||||
- Pagination
|
||||
- Bulk actions (select multiple)
|
||||
|
||||
### 3.4 Replication Task Management
|
||||
- Task list with status indicators
|
||||
- Task creation wizard
|
||||
- Task detail view with progress
|
||||
|
||||
### 3.5 Create Replication Modal
|
||||
- Task name input
|
||||
- Source dataset selection
|
||||
- Target configuration (host, port, user, dataset)
|
||||
- Schedule configuration
|
||||
- Compression and options
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/snapshots
|
||||
GET /api/v1/snapshots/:id
|
||||
POST /api/v1/snapshots
|
||||
DELETE /api/v1/snapshots/:id
|
||||
POST /api/v1/snapshots/:id/rollback
|
||||
POST /api/v1/snapshots/:id/clone
|
||||
|
||||
GET /api/v1/replication/tasks
|
||||
GET /api/v1/replication/tasks/:id
|
||||
POST /api/v1/replication/tasks
|
||||
PUT /api/v1/replication/tasks/:id
|
||||
DELETE /api/v1/replication/tasks/:id
|
||||
POST /api/v1/replication/tasks/:id/run
|
||||
GET /api/v1/replication/tasks/:id/status
|
||||
|
||||
GET /api/v1/restore-points
|
||||
POST /api/v1/restore-points/restore
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **storage:read**: Required for viewing snapshots and replication tasks
|
||||
- **storage:write**: Required for creating, updating, deleting, executing
|
||||
|
||||
## 6. Error Handling
|
||||
- Invalid dataset
|
||||
- Snapshot not found
|
||||
- Replication target unreachable
|
||||
- SSH authentication failure
|
||||
- Replication task errors
|
||||
- Insufficient permissions
|
||||
|
||||
167
docs/alpha/srs/SRS-08-System-Management.md
Normal file
167
docs/alpha/srs/SRS-08-System-Management.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# SRS-08: System Management
|
||||
|
||||
## 1. Overview
|
||||
System Management module provides configuration and management of system services, network interfaces, time synchronization, and system administration features.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Network Interface Management
|
||||
**FR-SYS-001**: System shall list network interfaces
|
||||
- **Output**: Interface list with name, IP address, status, speed
|
||||
- **Refresh**: Auto-refresh every 5 seconds
|
||||
|
||||
**FR-SYS-002**: System shall allow users to view interface details
|
||||
- **Output**: Interface properties, IP configuration, statistics
|
||||
|
||||
**FR-SYS-003**: System shall allow users to update interface configuration
|
||||
- **Input**: Interface name, IP address, subnet, gateway
|
||||
- **Validation**: Valid IP configuration
|
||||
|
||||
**FR-SYS-004**: System shall display interface status
|
||||
- **Output**: Connection status (Connected/Down), speed, role
|
||||
|
||||
### 2.2 Service Management
|
||||
**FR-SYS-005**: System shall list system services
|
||||
- **Output**: Service list with name, status, description
|
||||
- **Refresh**: Auto-refresh every 5 seconds
|
||||
|
||||
**FR-SYS-006**: System shall allow users to view service status
|
||||
- **Output**: Service status (active/inactive), enabled state
|
||||
|
||||
**FR-SYS-007**: System shall allow users to restart services
|
||||
- **Input**: Service name
|
||||
- **Action**: Restart service via systemd
|
||||
|
||||
**FR-SYS-008**: System shall allow users to start/stop services
|
||||
- **Input**: Service name, action (start/stop)
|
||||
|
||||
**FR-SYS-009**: System shall display service logs
|
||||
- **Input**: Service name
|
||||
- **Output**: Recent service logs
|
||||
|
||||
### 2.3 NTP Configuration
|
||||
**FR-SYS-010**: System shall allow users to configure timezone
|
||||
- **Input**: Timezone string
|
||||
- **Output**: Updated timezone
|
||||
|
||||
**FR-SYS-011**: System shall allow users to configure NTP servers
|
||||
- **Input**: NTP server list
|
||||
- **Output**: Updated NTP configuration
|
||||
|
||||
**FR-SYS-012**: System shall allow users to add NTP servers
|
||||
- **Input**: NTP server address
|
||||
- **Validation**: Valid NTP server address
|
||||
|
||||
**FR-SYS-013**: System shall allow users to remove NTP servers
|
||||
- **Input**: NTP server address
|
||||
|
||||
**FR-SYS-014**: System shall display NTP server status
|
||||
- **Output**: Server status, stratum, latency
|
||||
|
||||
### 2.4 SNMP Configuration
|
||||
**FR-SYS-015**: System shall allow users to enable/disable SNMP
|
||||
- **Input**: Enabled flag
|
||||
- **Action**: Enable/disable SNMP service
|
||||
|
||||
**FR-SYS-016**: System shall allow users to configure SNMP community string
|
||||
- **Input**: Community string
|
||||
- **Output**: Updated SNMP configuration
|
||||
|
||||
**FR-SYS-017**: System shall allow users to configure SNMP trap receiver
|
||||
- **Input**: Trap receiver IP address
|
||||
- **Output**: Updated SNMP configuration
|
||||
|
||||
### 2.5 System Logs
|
||||
**FR-SYS-018**: System shall allow users to view system logs
|
||||
- **Output**: System log entries with timestamp, level, message
|
||||
- **Filtering**: By level, time range, search
|
||||
|
||||
### 2.6 Terminal Console
|
||||
**FR-SYS-019**: System shall provide terminal console access
|
||||
- **Input**: Command string
|
||||
- **Output**: Command output
|
||||
- **Validation**: Allowed commands only (for security)
|
||||
|
||||
### 2.7 Feature License Management
|
||||
**FR-SYS-020**: System shall display license status
|
||||
- **Output**: License status (active/expired), expiration date, days remaining
|
||||
|
||||
**FR-SYS-021**: System shall display enabled features
|
||||
- **Output**: Feature list with enabled/disabled status
|
||||
|
||||
**FR-SYS-022**: System shall allow users to update license key
|
||||
- **Input**: License key
|
||||
- **Validation**: Valid license key format
|
||||
- **Action**: Update and validate license
|
||||
|
||||
**FR-SYS-023**: System shall allow users to download license information
|
||||
- **Output**: License information file
|
||||
|
||||
### 2.8 System Actions
|
||||
**FR-SYS-024**: System shall allow users to reboot system
|
||||
- **Action**: System reboot (with confirmation)
|
||||
|
||||
**FR-SYS-025**: System shall allow users to shutdown system
|
||||
- **Action**: System shutdown (with confirmation)
|
||||
|
||||
**FR-SYS-026**: System shall allow users to generate support bundle
|
||||
- **Output**: Support bundle archive
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 System Configuration Dashboard
|
||||
- Network interfaces card
|
||||
- Service control card
|
||||
- NTP configuration card
|
||||
- Management & SNMP card
|
||||
- Feature License card
|
||||
|
||||
### 3.2 Network Interface Management
|
||||
- Interface list with status indicators
|
||||
- Interface detail modal
|
||||
- Edit interface modal
|
||||
|
||||
### 3.3 Service Control
|
||||
- Service list with toggle switches
|
||||
- Service status indicators
|
||||
- Service log viewing
|
||||
|
||||
### 3.4 License Management
|
||||
- License status display
|
||||
- Enabled features list
|
||||
- Update license key modal
|
||||
- Download license info button
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/system/interfaces
|
||||
PUT /api/v1/system/interfaces/:name
|
||||
|
||||
GET /api/v1/system/services
|
||||
GET /api/v1/system/services/:name
|
||||
POST /api/v1/system/services/:name/restart
|
||||
GET /api/v1/system/services/:name/logs
|
||||
|
||||
GET /api/v1/system/ntp
|
||||
POST /api/v1/system/ntp
|
||||
|
||||
GET /api/v1/system/logs
|
||||
GET /api/v1/system/network/throughput
|
||||
|
||||
POST /api/v1/system/execute
|
||||
POST /api/v1/system/support-bundle
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **system:read**: Required for viewing interfaces, services, logs
|
||||
- **system:write**: Required for updating configuration, executing commands
|
||||
|
||||
## 6. Error Handling
|
||||
- Invalid IP configuration
|
||||
- Service not found
|
||||
- Service restart failures
|
||||
- Invalid NTP server
|
||||
- License validation errors
|
||||
- Insufficient permissions
|
||||
|
||||
127
docs/alpha/srs/SRS-09-Monitoring-Alerting.md
Normal file
127
docs/alpha/srs/SRS-09-Monitoring-Alerting.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# SRS-09: Monitoring & Alerting
|
||||
|
||||
## 1. Overview
|
||||
Monitoring & Alerting module provides real-time system monitoring, metrics collection, alert management, and system health tracking.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 System Metrics
|
||||
**FR-MON-001**: System shall collect and display CPU metrics
|
||||
- **Output**: CPU usage percentage, load average
|
||||
- **Refresh**: Every 5 seconds
|
||||
|
||||
**FR-MON-002**: System shall collect and display memory metrics
|
||||
- **Output**: Total memory, used memory, available memory, usage percentage
|
||||
- **Refresh**: Every 5 seconds
|
||||
|
||||
**FR-MON-003**: System shall collect and display storage metrics
|
||||
- **Output**: Total capacity, used capacity, available capacity, usage percentage
|
||||
- **Refresh**: Every 5 seconds
|
||||
|
||||
**FR-MON-004**: System shall collect and display network throughput
|
||||
- **Output**: Inbound/outbound throughput, historical data
|
||||
- **Refresh**: Every 5 seconds
|
||||
|
||||
**FR-MON-005**: System shall display ZFS ARC statistics
|
||||
- **Output**: ARC hit ratio, cache size, eviction statistics
|
||||
- **Refresh**: Real-time
|
||||
|
||||
### 2.2 ZFS Health Monitoring
|
||||
**FR-MON-006**: System shall display ZFS pool health
|
||||
- **Output**: Pool status, health indicators, errors
|
||||
|
||||
**FR-MON-007**: System shall display ZFS dataset health
|
||||
- **Output**: Dataset status, quota usage, compression ratio
|
||||
|
||||
### 2.3 System Logs
|
||||
**FR-MON-008**: System shall display system logs
|
||||
- **Output**: Log entries with timestamp, level, source, message
|
||||
- **Filtering**: By level, time range, search
|
||||
- **Refresh**: Every 10 minutes
|
||||
|
||||
**FR-MON-009**: System shall allow users to search logs
|
||||
- **Input**: Search query
|
||||
- **Output**: Filtered log entries
|
||||
|
||||
### 2.4 Active Jobs
|
||||
**FR-MON-010**: System shall display active jobs
|
||||
- **Output**: Job list with type, status, progress, start time
|
||||
|
||||
**FR-MON-011**: System shall allow users to view job details
|
||||
- **Output**: Job configuration, progress, logs
|
||||
|
||||
### 2.5 Alert Management
|
||||
**FR-MON-012**: System shall display active alerts
|
||||
- **Output**: Alert list with severity, source, message, timestamp
|
||||
|
||||
**FR-MON-013**: System shall allow users to acknowledge alerts
|
||||
- **Input**: Alert ID
|
||||
- **Action**: Mark alert as acknowledged
|
||||
|
||||
**FR-MON-014**: System shall allow users to resolve alerts
|
||||
- **Input**: Alert ID
|
||||
- **Action**: Mark alert as resolved
|
||||
|
||||
**FR-MON-015**: System shall display alert history
|
||||
- **Output**: Historical alerts with status, resolution
|
||||
|
||||
**FR-MON-016**: System shall allow users to configure alert rules
|
||||
- **Input**: Rule name, condition, severity, enabled flag
|
||||
- **Output**: Created alert rule
|
||||
|
||||
**FR-MON-017**: System shall evaluate alert rules
|
||||
- **Action**: Automatic evaluation based on metrics
|
||||
- **Output**: Generated alerts when conditions met
|
||||
|
||||
### 2.6 Health Checks
|
||||
**FR-MON-018**: System shall perform health checks
|
||||
- **Output**: Overall system health status (healthy/degraded/unhealthy)
|
||||
|
||||
**FR-MON-019**: System shall display health check details
|
||||
- **Output**: Component health status, issues, recommendations
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 Monitoring Dashboard
|
||||
- Metrics cards (CPU, Memory, Storage, Network)
|
||||
- Real-time charts (Network Throughput, ZFS ARC Hit Ratio)
|
||||
- System health indicators
|
||||
|
||||
### 3.2 Tabs
|
||||
- **Active Jobs**: Running jobs list
|
||||
- **System Logs**: Log viewer with filtering
|
||||
- **Alerts History**: Alert list and management
|
||||
|
||||
### 3.3 Alert Management
|
||||
- Alert list with severity indicators
|
||||
- Alert detail view
|
||||
- Alert acknowledgment and resolution
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/monitoring/metrics
|
||||
GET /api/v1/monitoring/health
|
||||
GET /api/v1/monitoring/alerts
|
||||
GET /api/v1/monitoring/alerts/:id
|
||||
POST /api/v1/monitoring/alerts/:id/acknowledge
|
||||
POST /api/v1/monitoring/alerts/:id/resolve
|
||||
GET /api/v1/monitoring/rules
|
||||
POST /api/v1/monitoring/rules
|
||||
PUT /api/v1/monitoring/rules/:id
|
||||
DELETE /api/v1/monitoring/rules/:id
|
||||
|
||||
GET /api/v1/system/logs
|
||||
GET /api/v1/system/network/throughput
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **monitoring:read**: Required for viewing metrics, alerts, logs
|
||||
- **monitoring:write**: Required for acknowledging/resolving alerts, configuring rules
|
||||
|
||||
## 6. Error Handling
|
||||
- Metrics collection failures
|
||||
- Alert rule evaluation errors
|
||||
- Log access errors
|
||||
- Insufficient permissions
|
||||
|
||||
191
docs/alpha/srs/SRS-10-IAM.md
Normal file
191
docs/alpha/srs/SRS-10-IAM.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# SRS-10: Identity & Access Management
|
||||
|
||||
## 1. Overview
|
||||
Identity & Access Management (IAM) module provides user account management, role-based access control (RBAC), permission management, and group management.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 User Management
|
||||
**FR-IAM-001**: System shall allow admins to create users
|
||||
- **Input**: Username, email, password, roles
|
||||
- **Output**: Created user with ID
|
||||
- **Validation**: Username uniqueness, valid email, strong password
|
||||
|
||||
**FR-IAM-002**: System shall allow admins to list users
|
||||
- **Output**: User list with username, email, roles, status
|
||||
- **Filtering**: By role, status, search
|
||||
|
||||
**FR-IAM-003**: System shall allow admins to view user details
|
||||
- **Output**: User properties, roles, groups, permissions
|
||||
|
||||
**FR-IAM-004**: System shall allow admins to update users
|
||||
- **Input**: User ID, updated properties
|
||||
- **Validation**: Valid updated values
|
||||
|
||||
**FR-IAM-005**: System shall allow admins to delete users
|
||||
- **Input**: User ID
|
||||
- **Validation**: Cannot delete own account
|
||||
|
||||
**FR-IAM-006**: System shall allow users to view own profile
|
||||
- **Output**: Own user properties, roles, permissions
|
||||
|
||||
**FR-IAM-007**: System shall allow users to update own profile
|
||||
- **Input**: Updated profile properties (email, password)
|
||||
- **Validation**: Valid updated values
|
||||
|
||||
### 2.2 Role Management
|
||||
**FR-IAM-008**: System shall allow admins to create roles
|
||||
- **Input**: Role name, description, permissions
|
||||
- **Output**: Created role with ID
|
||||
- **Validation**: Role name uniqueness
|
||||
|
||||
**FR-IAM-009**: System shall allow admins to list roles
|
||||
- **Output**: Role list with name, description, permission count
|
||||
|
||||
**FR-IAM-010**: System shall allow admins to view role details
|
||||
- **Output**: Role properties, assigned permissions, users with role
|
||||
|
||||
**FR-IAM-011**: System shall allow admins to update roles
|
||||
- **Input**: Role ID, updated properties
|
||||
|
||||
**FR-IAM-012**: System shall allow admins to delete roles
|
||||
- **Input**: Role ID
|
||||
- **Validation**: Role not assigned to users
|
||||
|
||||
**FR-IAM-013**: System shall allow admins to assign permissions to roles
|
||||
- **Input**: Role ID, permission ID
|
||||
- **Action**: Add permission to role
|
||||
|
||||
**FR-IAM-014**: System shall allow admins to remove permissions from roles
|
||||
- **Input**: Role ID, permission ID
|
||||
- **Action**: Remove permission from role
|
||||
|
||||
### 2.3 Permission Management
|
||||
**FR-IAM-015**: System shall list available permissions
|
||||
- **Output**: Permission list with resource, action, description
|
||||
|
||||
**FR-IAM-016**: System shall display permission details
|
||||
- **Output**: Permission properties, roles with permission
|
||||
|
||||
### 2.4 Group Management
|
||||
**FR-IAM-017**: System shall allow admins to create groups
|
||||
- **Input**: Group name, description
|
||||
- **Output**: Created group with ID
|
||||
|
||||
**FR-IAM-018**: System shall allow admins to list groups
|
||||
- **Output**: Group list with name, description, member count
|
||||
|
||||
**FR-IAM-019**: System shall allow admins to view group details
|
||||
- **Output**: Group properties, members, roles
|
||||
|
||||
**FR-IAM-020**: System shall allow admins to update groups
|
||||
- **Input**: Group ID, updated properties
|
||||
|
||||
**FR-IAM-021**: System shall allow admins to delete groups
|
||||
- **Input**: Group ID
|
||||
|
||||
**FR-IAM-022**: System shall allow admins to add users to groups
|
||||
- **Input**: Group ID, user ID
|
||||
- **Action**: Add user to group
|
||||
|
||||
**FR-IAM-023**: System shall allow admins to remove users from groups
|
||||
- **Input**: Group ID, user ID
|
||||
- **Action**: Remove user from group
|
||||
|
||||
### 2.5 User-Role Assignment
|
||||
**FR-IAM-024**: System shall allow admins to assign roles to users
|
||||
- **Input**: User ID, role ID
|
||||
- **Action**: Assign role to user
|
||||
|
||||
**FR-IAM-025**: System shall allow admins to remove roles from users
|
||||
- **Input**: User ID, role ID
|
||||
- **Action**: Remove role from user
|
||||
|
||||
### 2.6 Authentication
|
||||
**FR-IAM-026**: System shall authenticate users
|
||||
- **Input**: Username, password
|
||||
- **Output**: JWT token on success
|
||||
- **Validation**: Valid credentials
|
||||
|
||||
**FR-IAM-027**: System shall manage user sessions
|
||||
- **Output**: Current user information, session expiration
|
||||
|
||||
**FR-IAM-028**: System shall allow users to logout
|
||||
- **Action**: Invalidate session token
|
||||
|
||||
## 3. User Interface Requirements
|
||||
|
||||
### 3.1 IAM Dashboard
|
||||
- User management tab
|
||||
- Role management tab
|
||||
- Group management tab
|
||||
- Permission overview
|
||||
|
||||
### 3.2 User Management
|
||||
- User list with filtering
|
||||
- User creation modal
|
||||
- User detail view
|
||||
- User edit form
|
||||
|
||||
### 3.3 Role Management
|
||||
- Role list with permission count
|
||||
- Role creation modal
|
||||
- Role detail view with permission assignment
|
||||
- Role edit form
|
||||
|
||||
### 3.4 Group Management
|
||||
- Group list with member count
|
||||
- Group creation modal
|
||||
- Group detail view with member management
|
||||
- Group edit form
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/iam/users
|
||||
GET /api/v1/iam/users/:id
|
||||
POST /api/v1/iam/users
|
||||
PUT /api/v1/iam/users/:id
|
||||
DELETE /api/v1/iam/users/:id
|
||||
|
||||
POST /api/v1/iam/users/:id/roles
|
||||
DELETE /api/v1/iam/users/:id/roles
|
||||
POST /api/v1/iam/users/:id/groups
|
||||
DELETE /api/v1/iam/users/:id/groups
|
||||
|
||||
GET /api/v1/iam/roles
|
||||
GET /api/v1/iam/roles/:id
|
||||
POST /api/v1/iam/roles
|
||||
PUT /api/v1/iam/roles/:id
|
||||
DELETE /api/v1/iam/roles/:id
|
||||
|
||||
GET /api/v1/iam/roles/:id/permissions
|
||||
POST /api/v1/iam/roles/:id/permissions
|
||||
DELETE /api/v1/iam/roles/:id/permissions
|
||||
|
||||
GET /api/v1/iam/permissions
|
||||
|
||||
GET /api/v1/iam/groups
|
||||
GET /api/v1/iam/groups/:id
|
||||
POST /api/v1/iam/groups
|
||||
PUT /api/v1/iam/groups/:id
|
||||
DELETE /api/v1/iam/groups/:id
|
||||
|
||||
POST /api/v1/iam/groups/:id/users
|
||||
DELETE /api/v1/iam/groups/:id/users/:user_id
|
||||
```
|
||||
|
||||
## 5. Permissions
|
||||
- **iam:read**: Required for viewing users, roles, groups
|
||||
- **iam:write**: Required for creating, updating, deleting
|
||||
- **admin role**: Required for all IAM operations
|
||||
|
||||
## 6. Error Handling
|
||||
- Username already exists
|
||||
- Invalid email format
|
||||
- Weak password
|
||||
- Role not found
|
||||
- Permission denied
|
||||
- Cannot delete own account
|
||||
- Insufficient permissions
|
||||
|
||||
179
docs/alpha/srs/SRS-11-User-Interface.md
Normal file
179
docs/alpha/srs/SRS-11-User-Interface.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# SRS-11: User Interface & Experience
|
||||
|
||||
## 1. Overview
|
||||
User Interface & Experience module defines the requirements for the web-based user interface, navigation, responsiveness, and user experience.
|
||||
|
||||
## 2. Functional Requirements
|
||||
|
||||
### 2.1 Layout & Navigation
|
||||
**FR-UI-001**: System shall provide a consistent layout structure
|
||||
- **Components**: Header, sidebar navigation, main content area, footer
|
||||
- **Responsive**: Adapt to different screen sizes
|
||||
|
||||
**FR-UI-002**: System shall provide sidebar navigation
|
||||
- **Features**: Collapsible sidebar, active route highlighting, icon-based navigation
|
||||
- **Items**: Dashboard, Storage, Object Storage, Shares, Snapshots, Tape, iSCSI, Backup, Terminal, Monitoring, Alerts, System, IAM
|
||||
|
||||
**FR-UI-003**: System shall provide breadcrumb navigation
|
||||
- **Features**: Hierarchical navigation path, clickable breadcrumbs
|
||||
|
||||
**FR-UI-004**: System shall provide user profile menu
|
||||
- **Features**: User info, logout option, profile link
|
||||
|
||||
### 2.2 Authentication UI
|
||||
**FR-UI-005**: System shall provide login page
|
||||
- **Components**: Username input, password input, login button, error messages
|
||||
- **Validation**: Real-time validation feedback
|
||||
|
||||
**FR-UI-006**: System shall handle authentication errors
|
||||
- **Display**: Clear error messages for invalid credentials
|
||||
|
||||
**FR-UI-007**: System shall redirect authenticated users
|
||||
- **Action**: Redirect to dashboard if already logged in
|
||||
|
||||
### 2.3 Dashboard
|
||||
**FR-UI-008**: System shall provide system overview dashboard
|
||||
- **Components**: System status, metrics cards, recent activity, quick actions
|
||||
- **Refresh**: Auto-refresh metrics
|
||||
|
||||
**FR-UI-009**: System shall display system health indicators
|
||||
- **Components**: Health status badge, component status indicators
|
||||
|
||||
### 2.4 Data Display
|
||||
**FR-UI-010**: System shall provide table views
|
||||
- **Features**: Sorting, filtering, pagination, search
|
||||
- **Responsive**: Mobile-friendly table layout
|
||||
|
||||
**FR-UI-011**: System shall provide card-based layouts
|
||||
- **Features**: Status indicators, quick actions, hover effects
|
||||
|
||||
**FR-UI-012**: System shall provide master-detail views
|
||||
- **Features**: List on left, details on right, selection highlighting
|
||||
|
||||
### 2.5 Forms & Modals
|
||||
**FR-UI-013**: System shall provide form inputs
|
||||
- **Types**: Text, number, select, checkbox, radio, textarea, file
|
||||
- **Validation**: Real-time validation, error messages
|
||||
|
||||
**FR-UI-014**: System shall provide modal dialogs
|
||||
- **Features**: Overlay, close button, form submission, loading states
|
||||
|
||||
**FR-UI-015**: System shall provide confirmation dialogs
|
||||
- **Features**: Warning messages, confirm/cancel actions
|
||||
|
||||
### 2.6 Feedback & Notifications
|
||||
**FR-UI-016**: System shall provide loading states
|
||||
- **Components**: Spinners, skeleton loaders, progress indicators
|
||||
|
||||
**FR-UI-017**: System shall provide success notifications
|
||||
- **Display**: Toast notifications, inline success messages
|
||||
|
||||
**FR-UI-018**: System shall provide error notifications
|
||||
- **Display**: Toast notifications, inline error messages, error pages
|
||||
|
||||
**FR-UI-019**: System shall provide warning notifications
|
||||
- **Display**: Warning dialogs, warning badges
|
||||
|
||||
### 2.7 Charts & Visualizations
|
||||
**FR-UI-020**: System shall provide metric charts
|
||||
- **Types**: Line charts, bar charts, pie charts, gauge charts
|
||||
- **Libraries**: Recharts integration
|
||||
|
||||
**FR-UI-021**: System shall provide real-time chart updates
|
||||
- **Refresh**: Auto-refresh chart data
|
||||
|
||||
### 2.8 Responsive Design
|
||||
**FR-UI-022**: System shall be responsive
|
||||
- **Breakpoints**: Mobile (< 640px), Tablet (640px - 1024px), Desktop (> 1024px)
|
||||
- **Adaptation**: Layout adjustments, menu collapse, touch-friendly controls
|
||||
|
||||
**FR-UI-023**: System shall support dark theme
|
||||
- **Features**: Dark color scheme, theme persistence
|
||||
|
||||
### 2.9 Accessibility
|
||||
**FR-UI-024**: System shall support keyboard navigation
|
||||
- **Features**: Tab navigation, keyboard shortcuts, focus indicators
|
||||
|
||||
**FR-UI-025**: System shall provide ARIA labels
|
||||
- **Features**: Screen reader support, semantic HTML
|
||||
|
||||
## 3. Design Requirements
|
||||
|
||||
### 3.1 Color Scheme
|
||||
- **Primary**: #137fec (Blue)
|
||||
- **Background Dark**: #101922
|
||||
- **Surface Dark**: #18232e
|
||||
- **Border Dark**: #2a3b4d
|
||||
- **Text Primary**: White
|
||||
- **Text Secondary**: #92adc9
|
||||
- **Success**: Green (#10b981)
|
||||
- **Warning**: Yellow (#f59e0b)
|
||||
- **Error**: Red (#ef4444)
|
||||
|
||||
### 3.2 Typography
|
||||
- **Font Family**: Manrope (Display), System fonts (Body)
|
||||
- **Headings**: Bold, various sizes
|
||||
- **Body**: Regular, readable sizes
|
||||
|
||||
### 3.3 Spacing
|
||||
- **Consistent**: 4px base unit
|
||||
- **Padding**: 16px, 24px, 32px
|
||||
- **Gap**: 8px, 16px, 24px, 32px
|
||||
|
||||
### 3.4 Components
|
||||
- **Buttons**: Primary, secondary, outline, danger variants
|
||||
- **Cards**: Rounded corners, borders, shadows
|
||||
- **Inputs**: Rounded, bordered, focus states
|
||||
- **Badges**: Small, colored, with icons
|
||||
|
||||
## 4. User Experience Requirements
|
||||
|
||||
### 4.1 Performance
|
||||
- **Page Load**: < 2 seconds initial load
|
||||
- **Navigation**: < 100ms route transitions
|
||||
- **API Calls**: Loading states during requests
|
||||
|
||||
### 4.2 Usability
|
||||
- **Intuitive**: Clear navigation, obvious actions
|
||||
- **Consistent**: Consistent patterns across pages
|
||||
- **Feedback**: Immediate feedback for user actions
|
||||
- **Error Handling**: Clear error messages and recovery options
|
||||
|
||||
### 4.3 Discoverability
|
||||
- **Help**: Tooltips, help text, documentation links
|
||||
- **Search**: Global search functionality (future)
|
||||
- **Guides**: Onboarding flow (future)
|
||||
|
||||
## 5. Technology Stack
|
||||
|
||||
### 5.1 Frontend Framework
|
||||
- React 18 with TypeScript
|
||||
- Vite for build tooling
|
||||
- React Router for navigation
|
||||
|
||||
### 5.2 Styling
|
||||
- TailwindCSS for utility-first styling
|
||||
- Custom CSS for specific components
|
||||
- Dark theme support
|
||||
|
||||
### 5.3 State Management
|
||||
- Zustand for global state
|
||||
- TanStack Query for server state
|
||||
- React hooks for local state
|
||||
|
||||
### 5.4 UI Libraries
|
||||
- Lucide React for icons
|
||||
- Recharts for charts
|
||||
- Custom components
|
||||
|
||||
## 6. Browser Support
|
||||
- Chrome/Edge: Latest 2 versions
|
||||
- Firefox: Latest 2 versions
|
||||
- Safari: Latest 2 versions
|
||||
|
||||
## 7. Error Handling
|
||||
- Network errors: Retry mechanism, error messages
|
||||
- Validation errors: Inline error messages
|
||||
- Server errors: Error pages, error notifications
|
||||
- 404 errors: Not found page
|
||||
|
||||
Reference in New Issue
Block a user