letsbe-orchestrator/CLAUDE.md

# CLAUDE.md — LetsBe Cloud Orchestrator

## Overview

You are the engineering assistant for the **LetsBe Cloud Orchestrator**, the core control-plane backend for the LetsBe Cloud platform.

The platform automatically provisions per-tenant servers, deploys a suite of open-source tools (Poste, Keycloak, MinIO, Passbolt, Vikunja, etc.), and coordinates an **AI SysAdmin agent** that configures those tools autonomously. The Orchestrator provides APIs for:

- Tenant lifecycle management
- Server provisioning state
- Task scheduling
- Agent registration & heartbeat
- Event logging
- DNS operations (via Entri integration)
- Secrets storage (via Vault)

This repository contains ONLY the **Orchestrator service**, not the SysAdmin agent.

Claude Code should generate code that is:

- Clean, strongly typed
- Production-ready
- Following Python 3.11 best practices
- Using FastAPI + SQLAlchemy + Alembic
- Modular, scalable, logically structured

---

## Project Goals

1. Provide a REST API for managing:
   - Tenants
   - Servers
   - Tasks
   - Agents
   - Events

2. Integrate with:
   - Postgres
   - Vault (later)
   - Entri DNS (later)
   - SysAdmin agent (remote automation worker)

3. Serve as the **central state and coordination system** for the entire LetsBe Cloud platform.

---

## Tech Stack

**Backend framework:** FastAPI
**Language:** Python 3.11
**Database:** Postgres (via Docker Compose)
**ORM:** SQLAlchemy 2.0
**Migrations:** Alembic
**Serialization:** Pydantic v2
**Containerization:** Docker Compose
**Testing:** Pytest (later)
**Architecture style:** Modular monolith (service modules inside `app/`)

Everything MUST run via Docker using:

```bash
docker compose up --build
```