BAMS/ARCHITECTURE.md

# BAMS Architecture

## Overview

BAMS (Backup Appliance Management System) is a comprehensive management platform for backup appliances, providing unified control over storage, tape libraries, iSCSI targets, and Bacula integration.

## System Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Cockpit Web UI                        │
│                  (Cockpit Plugin)                        │
└──────────────────────┬──────────────────────────────────┘
                       │ HTTP/REST API
                       │
┌──────────────────────▼──────────────────────────────────┐
│              BAMS Backend Service (Go)                   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐│
│  │   Disk   │  │   Tape   │  │   iSCSI   │  │ Bacula  ││
│  │ Service  │  │ Service  │  │  Service │  │ Service ││
│  └────┬─────┘  └────┬─────┘  └────┬──────┘  └────┬────┘│
└───────┼─────────────┼──────────────┼──────────────┼─────┘
        │             │              │              │
┌───────▼─────┐ ┌─────▼─────┐ ┌─────▼──────┐ ┌─────▼─────┐
│    LVM      │ │   mtx     │ │    SCST    │ │  systemd  │
│    ZFS      │ │  sg_lib   │ │   iSCSI    │ │  bacula-sd│
└─────────────┘ └───────────┘ └────────────┘ └───────────┘
```

## Components

### 1. Backend Service (Go)

**Location**: `backend/`

**Structure**:
- `main.go` - Entry point, HTTP server setup
- `internal/api/` - REST API handlers and routing
- `internal/services/` - Business logic services
  - `disk/` - Disk repository management (LVM/ZFS)
  - `tape/` - Tape library management
  - `iscsi/` - iSCSI target management (SCST)
  - `bacula/` - Bacula integration
  - `logs/` - Logging and diagnostics
  - `audit/` - Audit logging
- `internal/config/` - Configuration management
- `internal/logger/` - Logging utilities
- `internal/utils/` - Helper functions

**Key Features**:
- RESTful API with JSON responses
- Graceful shutdown handling
- Request validation
- Error recovery middleware
- CORS support

### 2. Cockpit Plugin (Frontend)

**Location**: `cockpit/`

**Files**:
- `manifest.json` - Plugin metadata
- `index.html` - Main UI structure
- `bams.js` - JavaScript application logic

**Features**:
- Dashboard with real-time monitoring
- Storage repository management
- Tape library operations
- iSCSI target configuration
- Bacula status and control
- Log viewer

### 3. Configuration

**Location**: `configs/`

**Files**:
- `bams.service` - Systemd service file
- `config.yaml.example` - Configuration template
- `polkit.rules` - Polkit authorization rules

## Data Flow

### Disk Repository Creation

1. User creates repository via UI
2. Frontend sends POST to `/api/v1/disk/repositories`
3. Backend validates input
4. Disk service creates LVM volume or ZFS zvol
5. Repository metadata stored
6. Response returned to UI

### Tape Operations

1. User triggers inventory/load/unload
2. Frontend sends request to API
3. Tape service executes `mtx` commands
4. Results parsed and returned
5. UI updates display

### iSCSI Target Management

1. User creates/updates target
2. Backend validates IQN, portals, initiators
3. SCST configuration generated
4. Configuration applied via `scstadmin`
5. Status returned to UI

## Security

- **Authentication**: PAM/system users via Cockpit
- **Authorization**: Polkit rules for privileged operations
- **Audit Logging**: All configuration changes logged
- **Input Validation**: All user input validated
- **Error Handling**: Panic recovery middleware

## API Endpoints

### Dashboard
- `GET /api/v1/dashboard` - System overview

### Disk Repositories
- `GET /api/v1/disk/repositories` - List repositories
- `POST /api/v1/disk/repositories` - Create repository
- `GET /api/v1/disk/repositories/{id}` - Get repository
- `DELETE /api/v1/disk/repositories/{id}` - Delete repository

### Tape Library
- `GET /api/v1/tape/library` - Library status
- `POST /api/v1/tape/inventory` - Run inventory
- `GET /api/v1/tape/drives` - List drives
- `POST /api/v1/tape/drives/{id}/load` - Load tape
- `POST /api/v1/tape/drives/{id}/unload` - Unload tape
- `GET /api/v1/tape/slots` - List slots

### iSCSI Targets
- `GET /api/v1/iscsi/targets` - List targets
- `POST /api/v1/iscsi/targets` - Create target
- `GET /api/v1/iscsi/targets/{id}` - Get target
- `PUT /api/v1/iscsi/targets/{id}` - Update target
- `DELETE /api/v1/iscsi/targets/{id}` - Delete target
- `POST /api/v1/iscsi/targets/{id}/apply` - Apply configuration
- `POST /api/v1/iscsi/targets/{id}/luns` - Add LUN
- `DELETE /api/v1/iscsi/targets/{id}/luns/{lun}` - Remove LUN
- `GET /api/v1/iscsi/sessions` - List sessions

### Bacula
- `GET /api/v1/bacula/status` - SD status
- `GET /api/v1/bacula/config` - Get config
- `POST /api/v1/bacula/config` - Generate config
- `POST /api/v1/bacula/inventory` - Run inventory
- `POST /api/v1/bacula/restart` - Restart SD

### Logs & Diagnostics
- `GET /api/v1/logs/{service}` - Get logs
- `GET /api/v1/logs/{service}/stream` - Stream logs (WebSocket)
- `GET /api/v1/diagnostics/bundle` - Download support bundle

## Deployment

1. Build backend: `make build`
2. Install service: `make install`
3. Configure: Edit `/etc/bams/config.yaml`
4. Start service: `systemctl start bams`
5. Access via Cockpit web interface

## Dependencies

- **Go 1.21+**
- **Cockpit 300+**
- **SCST** (iSCSI target framework)
- **mtx** (tape library control)
- **LVM tools** (for LVM repositories)
- **ZFS tools** (for ZFS repositories, optional)
- **Bacula** (for backup integration)

## Future Enhancements

- WebSocket support for real-time log streaming
- Multi-tenant support
- High Availability
- Tape encryption management
- Cloud tiering
- Policy-based tape lifecycle