# CLAUDE.md — LetsBe Hub

## Purpose

You are the engineering assistant for the LetsBe Hub.
This is the central licensing and telemetry service for the LetsBe Cloud platform.

The Hub provides:

- **License Management**: Issue and validate per-instance license keys
- **Instance Activation**: Verify licenses during client installation
- **Telemetry Collection**: Receive anonymized usage data from instances
- **Client Management**: Track organizations and their deployments

## Privacy Guarantee

**CRITICAL**: The Hub NEVER stores sensitive client data.

Allowed data:
- Instance identifiers
- Tool names
- Duration metrics
- Aggregated counts
- Error codes (not messages)

NEVER stored:
- Environment variable values
- File contents
- Request/response payloads
- Screenshots
- Credentials
- Stack traces or error messages

The `app/services/redactor.py` enforces this with an ALLOW-LIST approach.

## Tech Stack

- Python 3.11
- FastAPI
- SQLAlchemy 2.0 (async)
- PostgreSQL
- Alembic migrations
- Pydantic v2

## API Endpoints

### Public Endpoints

```
POST /api/v1/instances/activate
  - Validates license key
  - Returns hub_api_key for telemetry
  - Called by client bootstrap scripts
```

### Admin Endpoints (require X-Admin-Api-Key header)

```
# Clients
POST   /api/v1/admin/clients
GET    /api/v1/admin/clients
GET    /api/v1/admin/clients/{id}
PATCH  /api/v1/admin/clients/{id}
DELETE /api/v1/admin/clients/{id}

# Instances
POST   /api/v1/admin/clients/{id}/instances
GET    /api/v1/admin/clients/{id}/instances
GET    /api/v1/admin/instances/{instance_id}
POST   /api/v1/admin/instances/{instance_id}/rotate-license
POST   /api/v1/admin/instances/{instance_id}/rotate-hub-key
POST   /api/v1/admin/instances/{instance_id}/suspend
POST   /api/v1/admin/instances/{instance_id}/reactivate
DELETE /api/v1/admin/instances/{instance_id}
```

## Key Types

### License Key
Format: `lb_inst_<32_hex_chars>`
Example: `lb_inst_a1b2c3d4e5f6789012345678901234567890abcd`

Stored as SHA-256 hash. Only visible once at creation.

### Hub API Key
Format: `hk_<24_hex_chars>`
Example: `hk_abc123def456789012345678901234567890abcd`

Used for telemetry authentication. Stored as SHA-256 hash.

## Development Commands

```bash
# Start services
docker compose up --build

# Run migrations
docker compose exec api alembic upgrade head

# Create new migration
docker compose exec api alembic revision --autogenerate -m "description"

# Run tests
docker compose exec api pytest -v

# API available at http://localhost:8200
```

## Coding Conventions

- Everything async
- Use the redactor for ALL telemetry data
- Never log sensitive data
- All exceptions should be caught and return proper HTTP errors
- Use constant-time comparison for secrets (secrets.compare_digest)