> ## Documentation Index
> Fetch the complete documentation index at: https://playbook.smedleygroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture and Deployment Pipeline

> How the TalentIdPipeline-Infra-CDK app, pipeline and stacks fit together, and how a change reaches production.

This page covers how the infrastructure is structured as code, and how a change gets from a commit to live infrastructure.

![TalentIdPipeline-Infra-CDK deployed infrastructure. Box colour shows the deploying CloudFormation stack.](https://mintcdn.com/smedley_group/J4Qb1kGrTQEJOjVR/images/software/developer/estate/infra/talentidpipeline-infra-cdk/architecture.png?fit=max\&auto=format\&n=J4Qb1kGrTQEJOjVR\&q=85\&s=84f1b45ec0c2abdebf35d794aa8479f7)

> [!NOTE]
>
> The diagram source is the draw\.io file at `images/software/developer/estate/infra/talentidpipeline-infra-cdk/architecture.drawio`. To change the diagram, edit that source in draw\.io, re-export it as PNG to `architecture.png` in the same folder, and commit both.

## Overview

This repo is a single AWS CDK (Python) application. It does not deploy resources directly. Instead it defines a self-mutating CodePipeline that deploys everything. The whole estate's core infrastructure therefore flows through one pipeline, in one AWS account, in one region.

| Setting | Value |
| - | - |
| AWS account | `338232497876` |
| Region | `eu-west-2` (London) |
| Pipeline | `TalentId-CDKPipeline-Infra` |
| Source | CodeCommit `TalentIdPipeline-Infra-CDK`, branch `main` |

## High-Level Structure

The application is a single CDK app that builds a pipeline, which deploys a stage containing three stacks:

* The CDK app (`app.py`) contains the pipeline stack (`TalentIPipelineStack`, deployed as `TalentId-Infra-Pipeline`).
* The pipeline stack creates the CodeCommit source repo (`TalentIdPipeline-Infra-CDK`) and the self-mutating CodePipeline (`TalentId-CDKPipeline-Infra`).
* The pipeline runs one stage, named `Infra`, which deploys three stacks in dependency order: `TalentID-Infra-External-Dependencies`, then `TalentID-Infra`, then `TalentId-MongoInstance`.

## The CI/CD Pipeline

The pipeline is a CDK `CodePipeline` construct with the following characteristics:

* **Source:** the `main` branch of the CodeCommit repo `TalentIdPipeline-Infra-CDK`. The pipeline also creates this repo.
* **Synth step:** runs `npm install -g aws-cdk`, then `pip install -r requirements.txt`, then `npx cdk synth`.
* **Self-mutation** is enabled, so the pipeline updates itself from the latest code before deploying the stacks.
* Assets are published one at a time rather than in parallel.
* A dedicated S3 artifact bucket (`build-assets-talent-id-infra`) holds pipeline artifacts.

## The Three Stacks and Their Ordering

The single `Infra` stage deploys three stacks, with explicit dependencies so they roll out in the correct order:

1. **`TalentID-Infra-External-Dependencies`** resolves shared resources (buckets, IAM users, the API repo) and publishes their identifiers to SSM.
2. **`TalentID-Infra`** builds the VPC, security groups, the API Gateway VPC endpoint and SNS topics. It consumes the external-dependencies configuration and depends on stack 1.
3. **`TalentId-MongoInstance`** provisions the MongoDB EC2 instance into the VPC and security group created by stack 2, and depends on stack 2.

Configuration passes between stacks two ways: in process (the Infra stack hands its VPC and Lambda security group objects to the Mongo stack), and through SSM parameters under `/TalentId/Infra/` that downstream systems read at deploy time. See [Integration Surface and Configuration Contract](/software/developer/estate/infra/talentidpipeline-infra-cdk/integration).

## How a Change Reaches Production

**1. Merge to main**

A change is merged to `main` in the CodeCommit repo.

**2. Pipeline triggers**

`TalentId-CDKPipeline-Infra` triggers automatically.

**3. Synth**

The Synth step installs the CDK CLI and Python dependencies and runs `cdk synth`.

**4. Self-mutate**

The pipeline self-mutates, applying any change to the pipeline itself.

**5. Deploy**

The `Infra` stage deploys the three stacks in dependency order.

> [!WARNING]
>
> There is no manual approval gate. A merge to `main` flows straight through to the estate's most critical shared infrastructure. An approval action on the pipeline would enforce the "coordinate with the full team" guidance in practice.

## Why It Is Built This Way

* **Python CDK (off-standard).** The team's preferred IaC is TypeScript CDK. This repo is Python for historical reasons (originally built by Nick from AWS for TalentID). It works, but it raises the maintenance bar and is part of why [SG-Infra](/software/developer/estate/infra/sg-infra) is the go-forward pattern.
* **Single account, region and environment.** There is no separate dev or prod AWS environment in this app. Instead the one Mongo instance hosts many databases (the dev and prod databases for the systems that use it, of which `TalentId_DEV` and `TalentId_PROD` are examples), so dev and production data share the same hardware and network.
* **Self-mutating pipeline.** Convenient, because the pipeline maintains itself, at the cost of pipeline changes also being applied automatically.

## Key Files

| File | Role |
| - | - |
| `app.py` | App entry point; instantiates the pipeline stack |
| `sg_infra/pipeline_stack.py` | Creates the CodeCommit repo and the self-mutating CodePipeline; adds the `Infra` stage |
| `sg_infra/pipeline_stage.py` | The `Infra` stage; instantiates the three stacks and wires dependencies |
| `sg_infra/talent_id_utils.py` | Shared constants (account, region, CIDR) and the artifact bucket helper |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.