# Architecture

## Core platform components

- Networking: VPC + Service Networking peering range
- Apigee Organization: top-level container
- Apigee Instances: runtime instances per region
- Environments: dev/test/prod
- EnvGroups: hostnames mapped to environments

## Dependency ordering

1. Networking and API enablement
2. Apigee Organization
3. Apigee Instances
4. Environments and instance attachments
5. EnvGroups and envgroup attachments

## Reference diagrams

### Single-region baseline

```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#D9F0FF","primaryTextColor":"#0F172A","secondaryColor":"#FFE1D6","tertiaryColor":"#E6FFFA","lineColor":"#334155","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
flowchart LR
  User((Client)) -->|HTTPS| Edge["Public DNS and TLS certs"]
  Edge -->|Private access| LB["Ingress ILB or Gateway"]
  LB --> Apigee["Apigee X Runtime"]
  Apigee -->|mTLS private| PSC["Private Service Connect"]
  PSC --> Backends["GCP services or private backends"]
  Apigee --> Logs["Cloud Logging"]
  Apigee --> Mon["Cloud Monitoring"]
```

### Multi-region HA

```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#E0F2FE","primaryTextColor":"#0F172A","secondaryColor":"#FCE7F3","tertiaryColor":"#ECFCCB","lineColor":"#334155","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
flowchart LR
  User((Client)) --> DNS["Global DNS and traffic policy"]
  DNS --> R1["Region A ingress"]
  DNS --> R2["Region B ingress"]
  R1 --> A["Apigee X Instance A"]
  R2 --> B["Apigee X Instance B"]
  A --> Backends["Private backends"]
  B --> Backends
  A --> Obs["Central observability"]
  B --> Obs
```

### CI/CD + Policy

```mermaid
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#DCFCE7","primaryTextColor":"#0F172A","secondaryColor":"#FEF3C7","tertiaryColor":"#EDE9FE","lineColor":"#334155","fontFamily":"Inter, ui-sans-serif, system-ui"}}}%%
flowchart LR
  Dev["Developer"] --> PR["Pull request"]
  PR --> CI["CI: fmt, validate, security"]
  CI -->|pass| Plan["Terraform plan"]
  Plan --> Review["Approval gate"]
  Review --> Apply["Terraform apply"]
  Apply --> Drift["Scheduled drift detection"]
  CI --> Policy["OPA or Conftest policy set"]
  Policy --> CI
```