# Deployment Analysis Index Date: 2026-03-29 ## Purpose This index is the entrypoint for the deployment analysis set under `knowledge/deployment/`. Use it when you need to decide: - which document to read first - where a deployment concern is explained - what is already covered vs still partially mapped - which artifacts are now machine-regenerable and validated ## Document Set ### 1. Deployment Structure File: - `knowledge/deployment/deployment-structure-analysis.md` Primary questions answered: - What are the core deployment repositories - Which repo owns infra, application delivery, configuration, and orchestration - How environments are modeled across repos - What the source-of-truth boundaries are - Where rollback and structural risks sit Read this first when: - you need the big picture - you want repo ownership and deployment layers - you need environment mapping across the deployment stack ### 2. Region Lifecycle File: - `knowledge/deployment/region-lifecycle-analysis.md` Primary questions answered: - How `auto-deploy` opens a new region - How `auto-deploy` delegates to `app-delivery` - How region destroy works - How jobs, finalizers, ArgoCD registration, and infra follow-up changes are ordered Read this first when: - you are analyzing dedicated / next-gen / BYOC region rollout - you want to understand create vs destroy sequencing - you want cross-repo orchestration details ### 3. Service Deployment Topology File: - `knowledge/deployment/service-deployment-topology.md` Primary questions answered: - Which deployed services belong to which layer - Which app-delivery objects map to which source repos - What the main global-to-regional dependency chains are - What deployment ordering should follow service topology Read this first when: - you are planning rollout order for application services - you need to understand global vs regional control planes - you want to connect manifests to source repos and `service-mapping` ### 4. App-Delivery Object Mapping Supplement File: - `knowledge/deployment/app-delivery-object-mapping.md` - `knowledge/deployment/app-delivery-object-mapping.json` Primary questions answered: - Which `app-delivery` objects map directly to a source repo - Which objects belong to a shared source family - Which ones are deployment-only bundles or third-party platform components - Which mappings are exact repo ownership versus family-level package boundaries Read this first when: - you are looking up a specific `app-delivery` object - you want mapping confidence rather than topology narrative - you want to see current coverage gaps quickly - you need a machine-readable inventory for scripts, graphs, or validation ### 5. Deployment Graph File: - `knowledge/deployment/deployment-graph.json` Primary questions answered: - which core deployment objects map to which source repos - which high-signal service dependency chains drive rollout ordering - which layer and deployment phase each anchor object belongs to - how the current analysis can be consumed without parsing markdown Read this first when: - you need JSON graph edges for tooling - you want to script validation or visualization - you want a concise machine-readable summary of topology conclusions - you want the code-generated high-level anchor graph rather than raw manifest references ### 6. Deployment Environment Graph File: - `knowledge/deployment/deployment-environment-graph.json` Primary questions answered: - which `ApplicationSet` files deploy to which environments and clusters - which namespace each generated application targets - how many placements exist per object, cluster, and scope - which registry objects already connect to source-repo mappings and which remain unmapped Read this first when: - you need env-to-cluster placement data - you want to connect topology with real ArgoCD destinations - you want to script environment coverage checks - you need the top-level `ApplicationSet` view without bundle-aggregator `Application` noise ### 7. Deployment Manifest Graph File: - `knowledge/deployment/deployment-manifest-graph.json` Primary questions answered: - which deployment objects directly reference other deployment objects in manifest or config text - which dependencies are evidenced by `kubernetes:///...`, in-cluster DNS service names, or internal HTTP service URLs - which provider or ops bundles reference mapped deployment objects through public or load-balancer endpoints - which edges are already normalized back to mapped deployment objects and source repos - how much manifest-level evidence currently aligns with the environment graph coverage Read this first when: - you need direct evidence for service-to-service rollout order - you want a machine-readable dependency list with file-and-line evidence - you want a lower-level complement to the high-level `deployment-graph.json` ### 8. Deployment Object Environment Matrix File: - `knowledge/deployment/deployment-object-environment-matrix.json` Primary questions answered: - where each top-level deployment object is placed by environment, cluster, and namespace - which bundle-owned internal ApplicationSets inherit a top-level owner mapping - how root, dev, and staging scopes expand into concrete placements - which bundles contribute the most internal placement surface Read this first when: - you need object x environment x cluster coverage directly - you want to script placement lookups without re-expanding ApplicationSets - you need to connect bundle internals back to top-level ownership ### 9. Deployment Bundle Decomposition File: - `knowledge/deployment/deployment-bundle-decomposition.json` Primary questions answered: - which internal applications sit inside each bundle-style delivery package - how many scopes, environments, clusters, and namespaces each bundle component reaches - whether a bundle component also has a direct top-level mapping in the KB Read this first when: - you want to split a broad delivery family such as `clinic` or `nextgen-regional-control-plane` - you need an internal component inventory before deeper source-repo mapping - you want to compare bundle size and placement footprint ### 10. Deployment Validation Report File: - `knowledge/deployment/deployment-validation-report.json` Primary questions answered: - whether top-level registry objects all have mappings - whether manifest edges only point at known deployment objects - whether filtered repos leaked into generated ownership outputs - whether generated IDs are unique and bundle coverage is complete Read this first when: - you need a trust check before consuming the machine-readable artifacts - you want to know whether regeneration introduced contradictions - you need an explicit pass/warn/fail summary ### 11. Deployment Artifact Query Guide File: - `knowledge/deployment/deployment-artifact-query-guide.md` Primary questions answered: - which generated artifact answers an ownership, placement, dependency, or validation question - what the practical difference is between the compact graphs and expanded projections - what the current artifact set still does not fully answer Read this first when: - you want a quick artifact-to-question map - you do not want to infer file purpose from filenames alone - you need a user-facing entrypoint into the generated deployment outputs ### 12. Public Entrypoint Scan Files: - `knowledge/deployment/public-entrypoint-catalog.json` - `knowledge/deployment/public-entrypoint-scan.md` Primary questions answered: - which deployment objects expose ingress, gateway, HTTPRoute, GRPCRoute, or externally reachable load balancer surfaces - which hosts, paths, and backend services are visible directly from deployment manifests - which source owner and interface artifacts likely sit behind those exposed entrypoints - which exposures are explicit public DNS versus shared-gateway paths or unresolved load balancer endpoints Read this first when: - you are trying to identify externally reachable deployment objects - you need deployment-side evidence for user entrypoints - you want to connect public hosts and paths back to source repos and interface files ### 13. Public Service Catalog Files: - `knowledge/deployment/public-service-catalog.json` - `knowledge/deployment/public-service-catalog.md` Primary questions answered: - which deployment objects are the strongest current candidates for public or externally reachable services - how those services are exposed: confirmed external host, shared gateway path, or unresolved deployment exposure - which audience bucket a service most likely belongs to: regional API, tenant data API, observability, operator API, preview web, or unresolved candidate - which interface artifacts should be opened next to inspect the API surface Read this first when: - you want a smaller, more actionable set than the raw entrypoint scan - you are trying to answer which public services matter to users - you need a fast bridge from deployment entrypoints to repo interface inventories ## Generation And Validation Companions Files: - `construction/generate-deployment-derived-artifacts.py` - `construction/deployment-artifact-schema.md` - `construction/deployment-artifact-generation-plan.md` - `construction/deployment-artifact-validation-checklist.md` Use these when: - you want to regenerate the derived JSON artifacts instead of editing them manually - you need field-level schema definitions - you want a repeatable validation flow after `app-delivery` or KB updates - you need to rebuild both the old compact graphs and the newer matrix/decomposition outputs from one entrypoint ## Recommended Reading Order ### For Architecture Understanding 1. `deployment-structure-analysis.md` 2. `region-lifecycle-analysis.md` 3. `service-deployment-topology.md` 4. `app-delivery-object-mapping.md` 5. `deployment-graph.json` 6. `deployment-environment-graph.json` 7. `deployment-manifest-graph.json` 8. `deployment-object-environment-matrix.json` 9. `deployment-bundle-decomposition.json` 10. `deployment-validation-report.json` 11. `deployment-artifact-query-guide.md` 12. `public-entrypoint-scan.md` 13. `public-service-catalog.md` ### For Region Rollout Work 1. `region-lifecycle-analysis.md` 2. `deployment-structure-analysis.md` 3. `service-deployment-topology.md` 4. `deployment-graph.json` 5. `deployment-environment-graph.json` 6. `deployment-manifest-graph.json` 7. `deployment-object-environment-matrix.json` 8. `deployment-validation-report.json` 9. `deployment-artifact-query-guide.md` 10. `public-entrypoint-scan.md` 11. `public-service-catalog.md` ### For Service Rollout Work 1. `service-deployment-topology.md` 2. `app-delivery-object-mapping.md` 3. `deployment-structure-analysis.md` 4. `deployment-graph.json` 5. `deployment-environment-graph.json` 6. `deployment-manifest-graph.json` 7. `deployment-object-environment-matrix.json` 8. `deployment-bundle-decomposition.json` 9. `deployment-validation-report.json` 10. `deployment-artifact-query-guide.md` 11. `public-entrypoint-scan.md` 12. `public-service-catalog.md` ## Coverage Summary ### Well Covered - core deployment repos - environment mapping across deployment repos - `auto-deploy` region lifecycle - main global vs regional control-plane chains - core app-delivery objects with clear source repos - top-level object x environment x cluster placement coverage - bundle decomposition into internal ApplicationSets - machine-readable validation of mapping and graph integrity - code-regenerated high-level graph and top-level environment graph outputs - first-pass deployment-side scan for externally reachable entrypoints - first-pass public service catalog linked to interface artifacts ### Not Yet Fully Normalized - a service-to-region matrix for every environment and cloud - exhaustive manifest-level dependency coverage for every deployment object and bundle - full regeneration coverage for the older high-level `deployment-graph.json` and `deployment-environment-graph.json` - exact source-repo decomposition for every internal bundle component - exact host resolution for every shared-gateway exposure - exact route-to-interface matching for every public service candidate ## Quick Lookup Table | If you want to know... | Read... | | --- | --- | | who owns deployment infra vs app vs config | `deployment-structure-analysis.md` | | how a new region is created or destroyed | `region-lifecycle-analysis.md` | | what depends on what at the service level | `service-deployment-topology.md` | | where a specific `app-delivery` object likely comes from | `app-delivery-object-mapping.md` | | where a specific `app-delivery` object maps in JSON form | `app-delivery-object-mapping.json` | | where the current high-level topology graph lives in JSON | `deployment-graph.json` | | where env-to-cluster placements live in JSON | `deployment-environment-graph.json` | | where manifest-level dependency evidence lives in JSON | `deployment-manifest-graph.json` | | where object x environment x cluster placements live in JSON | `deployment-object-environment-matrix.json` | | where bundle internals are decomposed in JSON | `deployment-bundle-decomposition.json` | | where machine-readable validation results live | `deployment-validation-report.json` | | which artifact answers which question | `deployment-artifact-query-guide.md` | | which deployment objects have external hosts or gateway paths | `public-entrypoint-catalog.json` / `public-entrypoint-scan.md` | | which public or externally reachable services matter most | `public-service-catalog.json` / `public-service-catalog.md` | ## Current Gaps Worth Filling Next 1. Expand `deployment-manifest-graph.json` beyond the current service, addon, secret-store, Clinic-linked provider, and initial observability edges into the remaining addon and observability bundles. 2. Replace the remaining curated constants inside the generated high-level `deployment-graph.json` with deeper KB-derived generation rules where possible. 3. Decompose broad shared delivery families such as `clinic` and `nextgen-regional-control-plane` into exact source repos when the KB later contains those internal source repos. 4. Add `aws-shared-cd-prod` into KB-level deployment metadata if it is in scope. 5. Resolve shared-gateway public hosts and connect public service catalog entries to exact interface subsets instead of repo-level interface file hints.