# Deployment Structure Analysis Outline

## Goal

Analyze the TiDB Cloud deployment structure in a way that is actionable for:

- understanding ownership boundaries between deployment repositories
- reconstructing environment topology and promotion flow
- tracing how a code or config change reaches runtime systems
- connecting deployment definitions with service dependency graphs
- identifying rollback boundaries and operational risks

This document is an analysis outline, not a conclusion document.
It defines what to inspect, what questions must be answered, and how to organize findings.

## Primary Scope

Start from the five core deployment-definition repositories listed in:

- `knowledge/deployment/deployment-repos.json`
- `knowledge/deployment/deployment-repos.md`

Current core repos:

1. `aws-shared-cd`
2. `app-delivery`
3. `auto-deploy`
4. `infra-cd`
5. `oneconfig`

## Why This Analysis Matters

Deployment structure is not just "where YAML or Pulumi code lives".
It is the full control path from change definition to runtime effect:

`source repo -> review/merge -> CI/CD system -> deployment repo -> cloud/Kubernetes/config target -> running services`

Without this structure, the knowledge base cannot reliably answer:

- where an environment is defined
- how a service gets deployed
- what config source controls runtime behavior
- what depends on what during rollout
- how to rollback safely

## Analysis Dimensions

The analysis should cover the following dimensions.

### 1. Repository Responsibility Boundaries

For each deployment repo, answer:

- What assets does it define: infra, cluster, app rollout, config, account, secrets reference, namespace, policy
- What is its scope: global, regional, per-environment, per-service, per-tenant
- What systems does it control directly
- What systems does it trigger indirectly
- What should not be changed in this repo because another repo owns it

Expected output:

- a responsibility matrix with one row per repo
- explicit ownership boundaries and overlap notes

### 2. Environment Mapping

Reconstruct how environments are modeled.

Answer:

- How are `dev`, `staging`, and `prod` represented
- Are branches, stacks, folders, namespaces, accounts, or regions used as the environment key
- Are there personal or ephemeral environments
- Which repos are environment-aware and which are environment-agnostic
- How does the same service differ across environments

Expected output:

- an environment mapping table
- a branch/stack/namespace/account mapping table

### 3. Change Flow and Delivery Path

Trace how a change moves through the system.

At minimum, cover these paths:

- infrastructure definition change
- application delivery change
- config-only change
- automated deployment trigger

Answer:

- What starts the workflow: merge, manual dispatch, Jenkins, GitHub Actions, cron, another repo
- What pipeline applies the change
- What target system receives the change
- Whether the flow is push-based or pull-based
- Where approvals or manual gates exist

Expected output:

- one end-to-end flow per change type
- a trigger matrix

### 4. Infrastructure vs Application vs Configuration Layers

Separate the deployment structure into control layers.

Recommended layer model:

1. cloud account / project layer
2. cluster / platform layer
3. workload delivery layer
4. runtime configuration layer
5. service runtime dependency layer

Answer:

- Which repo controls each layer
- Which layer consumes outputs from another layer
- What artifacts are handed off between layers

Expected output:

- a layered architecture diagram in text form
- inter-layer dependency notes

### 5. Service Topology and Deployment Dependencies

Connect deployment definitions with service-level dependency data from `knowledge/repos/{repo}/`.

Answer:

- Which services are deployed together
- Which services depend on shared infrastructure
- Which services must be deployed or started in sequence
- Which services are config-coupled through `oneconfig`
- Which repos appear independent in deployment code but are coupled at runtime

Expected output:

- a deployment dependency graph
- a runtime dependency cross-check list

### 6. Delivery Authority and Source of Truth

For every important deployment concern, identify the source of truth.

Examples:

- environment topology
- cluster definition
- account definition
- application rollout definition
- runtime config
- secrets reference path

Answer:

- Which repo is authoritative
- Which repos mirror or consume that definition
- Whether drift can happen

Expected output:

- a source-of-truth table
- drift-risk notes

### 7. Rollback Boundaries and Failure Domains

Deployment analysis is incomplete without rollback semantics.

Answer:

- How to rollback infra changes
- How to rollback app rollout changes
- How to rollback config changes
- Which actions are reversible, delayed, or destructive
- What is the blast radius of a failed change
- Where environment cross-contamination could occur

Expected output:

- a rollback matrix
- a failure-domain map

### 8. Operational and Governance Risks

Identify structural risks, not only code bugs.

Examples:

- one repo controls too many layers
- environment mapping is implicit rather than declared
- promotion logic depends on branch naming only
- config rollout and app rollout are decoupled without compatibility checks
- production depends on rarely updated but critical infrastructure repos
- multi-account or multi-region logic is under-documented

Expected output:

- a prioritized risk list
- missing-evidence items that require deeper scanning

## Recommended Analysis Order

To reduce ambiguity, analyze in this order:

1. `oneconfig`
2. `infra-cd`
3. `aws-shared-cd`
4. `app-delivery`
5. `auto-deploy`
6. related service repos and their `service-mapping` outputs

Rationale:

- `oneconfig` usually reveals the clearest environment and namespace model
- `infra-cd` and `aws-shared-cd` define the platform boundary
- `app-delivery` and `auto-deploy` explain the rollout mechanism
- service mappings validate whether deployment boundaries match runtime reality

## Evidence Sources

Use the following evidence in priority order.

### Repository-Level Evidence

- `knowledge/deployment/deployment-repos.json`
- `knowledge/deployment/deployment-repos.md`
- `knowledge/repos/{repo}/meta.json`
- local source trees under `~/coding/{repo}`

### In-Repo Signals to Inspect

- `README.md`
- workflow files under `.github/workflows/`
- Jenkins files or job definitions
- Pulumi entrypoints and stack configs
- shell entry scripts
- environment-specific directories
- manifest or chart directories
- config directory conventions
- release scripts

### Cross-Repo Evidence

- service `interfaces/` and `service-mapping/` outputs
- references between repos in docs or scripts
- branch conventions
- stack naming conventions

## Deliverable Format

The final deployment-structure write-up should contain:

1. `Summary`
2. `Responsibility Matrix`
3. `Environment Mapping`
4. `Change Flows`
5. `Layered Architecture`
6. `Dependency and Ordering`
7. `Rollback and Risk`
8. `Open Questions`

Recommended style:

- separate confirmed facts from inference
- attach evidence path for every non-obvious claim
- avoid generic statements such as "used for deployment" without naming target systems
- prefer tables over long prose for ownership and mapping sections

## Minimum Questions Per Repository

Ask these questions for every deployment repo:

1. What exact deployment artifact does this repo own
2. How does it distinguish environments
3. What applies changes from this repo
4. What runtime target receives those changes
5. What other repos must already be correct for this repo to work
6. How is rollback performed
7. What can break if this repo changes incorrectly

## Output Template

Use this template when producing the final analysis for a repo:

```md
## {repo-name}

### Responsibility
- ...

### Environment Model
- ...

### Delivery Flow
- trigger:
- pipeline:
- target:

### Dependencies
- upstream:
- downstream:

### Rollback
- ...

### Risks
- ...

### Evidence
- path/to/file
```

## Success Criteria

The analysis is successful when it can answer all of the following without reopening the source tree:

- where a deployment change should be made
- how that change reaches a specific environment
- what other repos or systems the change depends on
- how to validate the target runtime effect
- how to rollback if the change fails

If any of these remain unclear, the analysis should explicitly mark the gap as unresolved rather than smoothing over it.