> ## Documentation Index
> Fetch the complete documentation index at: https://acm-aa28ebf6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Architecture

> Go API server, Python subprocess IPC, and Cloudflare R2 storage

## System Overview

The SuperBox backend is composed of three runtime components that work together:

1. **Go API (Gin)** - handles all REST requests from the frontend and CLI; delegates storage and security work to Python subprocess helpers
2. **Python helpers** - `s3_helper.py` (R2 IPC bridge) and `security_helper.py` (5-stage scan runner), invoked by the Go API via `exec.Command`
3. **Cloudflare Worker + Durable Object** - stateless edge proxy + stateful session runtime for MCP execution

```mermaid theme={null}
graph TB
 FE[Frontend / CLI] -->|REST + JWT| API[Go API - Gin]
 API -->|exec.Command| S3H[s3_helper.py]
 API -->|exec.Command| SEC[security_helper.py]
 S3H -->|boto3 S3-compat| R2[Cloudflare R2]
 SEC -->|SonarCloud / Tool Discovery / Snyk / GitGuardian / Bandit| SCAN[External scanners]
 FE -->|POST /mcp| W[Cloudflare Worker]
 W --> DO[McpSession DO]
 DO --> R2
```

## Go API Layer

**Framework:** Gin (Go 1.26)\
**Auth:** Firebase JWT middleware on all write endpoints

### Route groups

```go theme={null}
v1 := router.Group("/api/v1")
{
 v1.GET("/servers",listServers)
 v1.GET("/servers/:name", getServer)
 v1.POST("/servers",  authMiddleware, createServer)
 v1.PUT("/servers/:name",  authMiddleware, updateServer)
 v1.DELETE("/servers/:name", authMiddleware, deleteServer)
 v1.GET("/auth/device",  deviceAuthStart)
 v1.POST("/auth/device", deviceAuthPoll)
}
```

### Middleware stack

1. CORS
2. Logger (request / response)
3. Recovery (panic to 500)
4. Firebase auth (write endpoints)
5. Rate limiter

## Python Subprocess Helpers

The Go API delegates R2 operations to Python subprocesses (via boto3), since the Go S3-compat SDK does not fully support Cloudflare R2 quirks.

### s3\_helper.py

Handles all R2 operations: `get_object`, `put_object`, `delete_object`, `list_objects`.

```python theme={null}
# Called by Go as:
# python s3_helper.py get <bucket> <key>
# python s3_helper.py put <bucket> <key> <json-body>
```

Environment variables consumed: `CLOUDFLARE_R2_ENDPOINT`, `CLOUDFLARE_R2_ACCESS_KEY_ID`, `CLOUDFLARE_R2_SECRET_ACCESS_KEY`, `CLOUDFLARE_R2_BUCKET_NAME`.

### security\_helper.py

Runs the 5-stage security pipeline on a given repository URL:

1. SonarCloud analysis
2. Tool discovery (clone repo, regex scan for `@*.tool()` decorators)
3. Snyk dependency scan
4. GitGuardian secret detection
5. Bandit Python scan

Returns a structured JSON security report that the Go API stores alongside server metadata.

## Data Models

### Server metadata (stored in R2 as `{server-name}.json`)

```json theme={null}
{
  "name": "weather-server",
  "version": "1.0.0",
  "description": "Get current weather for any city",
  "author": "user@example.com",
  "lang": "python",
  "entrypoint": "main.py",
  "repository": {
 "type": "git",
 "url": "https://github.com/user/weather-server"
  },
  "tools": [
 { "name": "get_weather", "description": "Fetch weather data for a city" }
  ],
  "pricing": { "currency": "INR", "amount": 0.0 },
  "security_report": {
 "status": "passed",
 "sonarcloud": { "bugs": 0, "vulnerabilities": 0 },
 "snyk": { "critical": 0, "high": 0 },
 "gitguardian": { "secrets_found": 0 },
 "bandit": { "high": 0, "medium": 0 }
  }
}
```

## Authentication Flow

```mermaid theme={null}
sequenceDiagram
 participant C as CLI / Frontend
 participant A as Go API
 participant FB as Firebase Auth

 C->>A: Request with Authorization: Bearer <token>
 A->>FB: Validate JWT
 FB-->>A: User UID + claims
 A->>A: Authorise action
 A-->>C: Response
```

Device flow (for CLI `superbox auth login`):

```mermaid theme={null}
sequenceDiagram
 participant CLI
 participant A as Go API
 participant FB as Firebase

 CLI->>A: GET /auth/device (request device code)
 A-->>CLI: device_code + verification_uri
 Note over CLI: User opens browser, logs in
 CLI->>A: POST /auth/device (poll with device_code)
 A->>FB: Check if user completed auth
 FB-->>A: ID token
 A-->>CLI: JWT stored in ~/.superbox/auth.json
```