jv
/
mini-platform-control-plane
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
mini-platform-control-plane/docs/architecture.md

1.8 KiB
Raw Blame History

Architecture

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

The terminology follows this shape:

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

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.