# Architecture

`mini-platform-control-plane` models a small local management plane.

The terminology follows this shape:

```text
Fleet -> Environment -> Workload
```

For this project, `Fleet` is mostly conceptual at first. The first concrete
resources are environments, workloads, and operations.

## Recommended Start

Start local-first:

1. gRPC-only API.
2. In-memory storage.
3. Fake cloud provider.
4. Fake Kubernetes applier.
5. Temporal, MongoDB, Helm, and real Kubernetes adapters added later.

This keeps the first milestones focused on Go rather than infrastructure.

## Package Boundaries

```text
cmd/mpctl                  CLI entrypoint
cmd/control-plane          gRPC API server
cmd/worker                 Temporal worker

api/proto                  protobuf contracts
internal/domain            core model and validation
internal/service           application use cases
internal/storage           storage interfaces and implementations
internal/provider          cloud provider abstraction
internal/orchestration     Temporal workflows and activities
internal/transport/grpc    gRPC handlers
internal/helm              Helm rendering adapter
internal/kube              Kubernetes apply adapter
internal/observability     logging, metrics, and tracing
internal/config            configuration loading
test/e2e                   local end-to-end tests
deploy                     Docker, Compose, and Kubernetes assets
```

The domain and service packages must not depend on Cobra, gRPC, Temporal,
MongoDB, Helm, or Kubernetes packages. Those dependencies belong in adapter
packages.

## Initial Architecture Decision

Use gRPC first and add an HTTP gateway later only if it teaches a useful lesson.

Use in-memory storage first. Add MongoDB after the storage contract is stable.
A file-backed store is optional, but it is not needed for the first learning
path.