The desired state of the platform

1 · Three principles

Open Ledger in Azure DevOps ↗

2 · Repository structure

ledger/
├── clusters/                              # Per-environment Argo CD Application manifests
│   ├── dev/                               # 65 services, organised by namespace
│   │   ├── root-app.yaml                  # App of Apps — discovers all YAMLs (recurse: true)
│   │   ├── business-services/             # Core APIs + gRPC (28 YAMLs)
│   │   ├── business-workers/              # Background workers (14 YAMLs)
│   │   ├── practice-trading/              # Practice trading (9 YAMLs)
│   │   ├── iam/                           # Keycloak, OpenFGA
│   │   ├── intelligence/                  # RAG AI
│   │   ├── mfe/                           # Micro-frontends (6 YAMLs)
│   │   └── web/                           # Web portals (5 YAMLs)
│   ├── qa/                                # rds-iam-mvp + Kyverno + NetworkPolicies
│   └── prod-wealth/                       # Ready, waiting for cluster deployment
│       └── root-app.yaml                  # syncPolicy: {} (manual only)
├── components/                            # Reusable Helm charts & Kustomize bases
│   ├── platform/
│   │   ├── charts/
│   │   │   ├── api-workload/              # REST API: deployment, service, ingress, HPA, NetworkPolicy
│   │   │   ├── grpc-workload/             # gRPC: deployment, service, HPA
│   │   │   ├── worker-workload/           # Background: deployment, KEDA ScaledObject
│   │   │   └── stateful-workload/         # StatefulSet: PVC, headless service, PDB
│   │   ├── forge-workload-lib/            # Shared Helm library
│   │   ├── kyverno-policies/base/         # Kustomize: 6 ClusterPolicies
│   │   ├── network-policies/base/         # Kustomize: baseline NetworkPolicies
│   │   └── argocd/                        # Argo CD Kustomize overlay
│   └── business-services/
│       └── rds-iam-mvp/chart/             # Service-specific chart (custom NetworkPolicy)
└── docs/

3 · Root App · App of Apps

Each environment has a root-app.yaml that tells Argo CD: "watch this directory, treat every YAML as an Application."

Two-phase handoff

1. Terraform (bootstrap) — the EKS module creates the initial Root App when the cluster is first deployed. ignore_changes = [yaml_body, yaml_incluster] ensures Terraform doesn't overwrite later changes.
2. Ledger (steady-state) — after bootstrap, the root-app.yaml in the Ledger is the source of truth. Both copies must stay in sync.

4 · Application manifest anatomy

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: rds-iam-mvp-dev              # Unique name (service + env)
  namespace: argocd
spec:
  project: default
  source:
    repoURL: git@ssh.dev.azure.com:v3/TaPP-Engine/Forge/ledger
    targetRevision: main
    path: components/platform/charts/api-workload    # Shared chart
    helm:
      values: |
        forge:
          environment: "dev"
          component: "rds-iam-mvp"
        image:
          repository: 303026955634.dkr.ecr.us-east-1.amazonaws.com/dev/rds-iam-mvp-app
          tag: "38076"                # ← Pipeline updates this
        serviceAccount:
          create: false               # Blueprint manages the SA
          name: "app-service-account"
        networkPolicy:
          enabled: false              # No Kyverno on dev
  destination:
    server: https://kubernetes.default.svc
    namespace: business-services
  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Key conventions

• image.tag is the only field the release pipeline changes. Immutable Build ID, no latest.
• serviceAccount.create: false — Blueprint creates the ServiceAccount via eks-identity. The chart references it by name.
• networkPolicy.enabled — false on dev (no Kyverno baseline), true on QA / Prod.
• path points to a shared chart. Only use a service-specific chart if you need custom templates (e.g. custom NetworkPolicy rules).

5 · Platform Helm charts

All charts inherit from forge-workload-lib — a shared Helm library that provides common templates for deployments, services, HPA and resource tiers.

Extension points · what devs can customise

Forbidden · platform-managed

• securityContext — non-root enforced by Kyverno (UID 1000)
• extraContainers — sidecars managed by platform
• hostPath — blocked by Kyverno

6 · Environment differences

7 · How to add a service

1. Blueprint first — deploy infrastructure via blueprint/accounts/<env>/us-east-1/services/eks/<namespace>/<name>/ (ecr, eks-identity, config, optionally secrets)
2. Create Application YAML — copy an existing manifest into clusters/dev/<namespace>/, update name, image.repository, forge.component
3. Add namespace — if the namespace is new, add it to services/eks/namespaces/terragrunt.hcl
4. Push to main — Root App auto-discovers and deploys within 30 seconds
5. Verify — check Argo CD UI for sync status and pod health