calypso/docs/BACKEND-FOUNDATION-COMPLETE.md

AtlasOS - Calypso Backend Foundation (Phase B Complete)

Summary

The backend foundation for AtlasOS - Calypso has been successfully implemented according to the SRS specifications. This document summarizes what has been delivered.

Deliverables

1. Repository Structure ✅

/development/calypso/
├── backend/
│   ├── cmd/calypso-api/          # Main application entry point
│   ├── internal/
│   │   ├── auth/                 # Authentication handlers
│   │   ├── iam/                  # Identity and access management
│   │   ├── audit/                 # Audit logging middleware
│   │   ├── tasks/                 # Async task engine
│   │   ├── system/                # System management (placeholder)
│   │   ├── monitoring/            # Monitoring (placeholder)
│   │   └── common/                # Shared utilities
│   │       ├── config/            # Configuration management
│   │       ├── database/          # Database connection and migrations
│   │       ├── logger/            # Structured logging
│   │       └── router/            # HTTP router setup
│   ├── db/migrations/             # Database migration files
│   ├── config.yaml.example        # Example configuration
│   ├── go.mod                     # Go module definition
│   ├── Makefile                   # Build automation
│   └── README.md                  # Backend documentation
├── deploy/
│   └── systemd/
│       └── calypso-api.service    # Systemd service file
└── scripts/
    └── install-requirements.sh   # System requirements installer

2. System Requirements Installation Script ✅

• Location: /development/calypso/scripts/install-requirements.sh
• Features:
  • Installs Go 1.22.0
  • Installs Node.js 20.x LTS and pnpm
  • Installs PostgreSQL
  • Installs disk storage tools (LVM2, XFS, etc.)
  • Installs physical tape tools (lsscsi, sg3-utils, mt-st, mtx)
  • Installs iSCSI initiator tools
  • Installs SCST prerequisites
  • Includes verification section

3. Database Schema ✅

• Location: /development/calypso/backend/internal/common/database/migrations/001_initial_schema.sql
• Tables Created:
  • users - User accounts
  • roles - System roles (admin, operator, readonly)
  • permissions - Fine-grained permissions
  • user_roles - User-role assignments
  • role_permissions - Role-permission assignments
  • sessions - Active user sessions
  • audit_log - Audit trail for all mutating operations
  • tasks - Async task state
  • alerts - System alerts
  • system_config - System configuration key-value store
  • schema_migrations - Migration tracking

4. API Endpoints ✅

Health Check

• GET /api/v1/health - System health status (no auth required)

Authentication

• POST /api/v1/auth/login - User login (returns JWT token)
• POST /api/v1/auth/logout - User logout
• GET /api/v1/auth/me - Get current user info (requires auth)

Tasks

• GET /api/v1/tasks/{id} - Get task status by ID (requires auth)

IAM (Admin only)

• GET /api/v1/iam/users - List all users
• GET /api/v1/iam/users/{id} - Get user details
• POST /api/v1/iam/users - Create new user
• PUT /api/v1/iam/users/{id} - Update user
• DELETE /api/v1/iam/users/{id} - Delete user

5. Security Features ✅

Authentication

• JWT-based authentication
• Session management
• Password hashing (Argon2id - stub implementation, needs completion)
• Token expiration

Authorization (RBAC)

• Role-based access control middleware
• Three default roles:
  • admin: Full system access
  • operator: Day-to-day operations
  • readonly: Read-only access
• Permission-based access control (scaffold ready)

Audit Logging

• Automatic audit logging for all mutating HTTP methods (POST, PUT, DELETE, PATCH)
• Logs user, action, resource, IP address, user agent, request body, response status
• Immutable audit trail in PostgreSQL

6. Task Engine ✅

• Location: /development/calypso/backend/internal/tasks/
• Features:
  • Task state machine (pending → running → completed/failed/cancelled)
  • Progress reporting (0-100%)
  • Task persistence in database
  • Task metadata support (JSON)
  • Task types: inventory, load_unload, rescan, apply_scst, support_bundle

7. Configuration Management ✅

• YAML-based configuration with environment variable overrides
• Sensible defaults
• Example configuration file provided
• Supports:
  • Server settings (port, timeouts)
  • Database connection
  • JWT authentication
  • Logging configuration

8. Structured Logging ✅

• JSON-formatted logs (production)
• Text-formatted logs (development)
• Log levels: debug, info, warn, error
• Contextual logging with structured fields

9. Systemd Integration ✅

• Systemd service file provided
• Runs as non-root user (calypso)
• Security hardening (NoNewPrivileges, PrivateTmp, ProtectSystem)
• Automatic restart on failure
• Journald integration

Architecture Highlights

Clean Architecture

• Clear separation of concerns
• Domain boundaries respected
• No business logic in handlers
• Dependency injection pattern

Error Handling

• Explicit error types
• Meaningful error messages
• Proper HTTP status codes

Context Propagation

• Context used throughout for cancellation and timeouts
• Database operations respect context

Database Migrations

• Automatic migration on startup
• Versioned migrations
• Migration tracking table

Next Steps (Phase C - Backend Core Domains)

The following domains need to be implemented in Phase C:

1. Storage Component (SRS-01)

   • LVM management
   • Disk repository provisioning
   • iSCSI target creation

2. Physical Tape Bridge (SRS-02)

   • Tape library discovery
   • Changer and drive operations
   • Inventory management

3. Virtual Tape Library (SRS-02)

   • MHVTL integration
   • Virtual tape management
   • Tape image storage

4. SCST Integration (SRS-01, SRS-02)

   • SCST target configuration
   • iSCSI target management
   • LUN mapping

5. System Management (SRS-03)

   • Service management
   • Log viewing
   • Support bundle generation

6. Monitoring (SRS-05)

   • Health checks
   • Alerting
   • Metrics collection

Running the Backend

Prerequisites

1. Run the installation script:

   sudo ./scripts/install-requirements.sh
   

2. Create PostgreSQL database:

   sudo -u postgres createdb calypso
   sudo -u postgres createuser calypso
   sudo -u postgres psql -c "ALTER USER calypso WITH PASSWORD 'your_password';"
   

3. Set environment variables:

   export CALYPSO_DB_PASSWORD="your_password"
   export CALYPSO_JWT_SECRET="your_jwt_secret_min_32_chars"
   

Build and Run

cd backend
go mod download
go run ./cmd/calypso-api -config config.yaml.example

The API will be available at http://localhost:8080

Testing Endpoints

1. Health Check:

   curl http://localhost:8080/api/v1/health
   

2. Login (create a user first via IAM API):

   curl -X POST http://localhost:8080/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d '{"username":"admin","password":"password"}'
   

3. Get Current User (requires JWT token):

   curl http://localhost:8080/api/v1/auth/me \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"
   

Known Limitations / TODOs

1. Password Hashing: Argon2id implementation is stubbed - needs proper implementation
2. Token Hashing: Session token hashing is simplified - needs cryptographic hash
3. Path Parsing: Audit log path parsing is simplified - can be enhanced
4. Error Messages: Some error messages could be more specific
5. Input Validation: Additional validation needed for user inputs
6. Rate Limiting: Not yet implemented
7. CORS: Currently allows all origins - should be configurable

Compliance with SRS

✅ Section 0: All authoritative specifications read and followed
✅ Section 1: Platform assumptions respected (Ubuntu 24.04, single-node)
✅ Section 2: Development order followed (Phase A & B complete)
✅ Section 3: Environment & requirements installed
✅ Section 4: Backend foundation created
✅ Section 5: Minimum deliverables implemented
✅ Section 6: Hard system rules respected (no shell execution, audit on mutating ops)
✅ Section 7: Enterprise standards applied (structured logging, error handling)
✅ Section 8: Workflow requirements followed

Files Created

Core Application

• backend/cmd/calypso-api/main.go
• backend/internal/common/config/config.go
• backend/internal/common/logger/logger.go
• backend/internal/common/database/database.go
• backend/internal/common/database/migrations.go
• backend/internal/common/router/router.go
• backend/internal/common/router/middleware.go

Domain Modules

• backend/internal/auth/handler.go
• backend/internal/iam/user.go
• backend/internal/iam/handler.go
• backend/internal/audit/middleware.go
• backend/internal/tasks/handler.go
• backend/internal/tasks/engine.go

Database

• backend/internal/common/database/migrations/001_initial_schema.sql

Configuration & Deployment

• backend/config.yaml.example
• backend/go.mod
• backend/Makefile
• backend/README.md
• deploy/systemd/calypso-api.service
• scripts/install-requirements.sh

---

Status: Phase B (Backend Foundation) - ✅ COMPLETE
Ready for: Phase C (Backend Core Domains)