> ## 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.

# Integration Surface and Configuration Contract

> How other systems plug into this infrastructure: the shared buckets, IAM users, SNS topics, and the SSM parameters downstream systems consume.

This page describes how other systems plug into this infrastructure: the shared entry points (buckets, users, event topics) and the configuration values that downstream systems read to discover the infrastructure.

## The Integration Surface

Beyond the VPC and the database, this repo provisions or references the shared touch points that connect the estate together:

* **S3 buckets.** A timing data ingestion bucket (where timing data lands), an end of session reports bucket, and the MongoDB backups bucket. These buckets already existed and are referenced by the stack rather than created fresh, so the stack is tied to those specific bucket names.
* **IAM upload users.** Two IAM users, `AlphaTimingUser` and `RaceFacerUser`, give the external timing providers permission to upload into the ingestion bucket. This is how third party timing data physically enters the estate.
* **SNS topics.** A timing data topic (`TalentIDTimingDataTopic`) and a classification topic (`TalentIDClassifyTopic`). The ingestion bucket is wired so that creating an object raises an event onto the timing data topic. These topics are the event backbone that downstream TalentID processing subscribes to.
* **`TalentID-API` repository.** The stack also references the `TalentID-API` CodeCommit repository.

In short: timing data flows in through the ingestion bucket, an event is published to SNS, and downstream systems react and read or write the shared database.

## The Configuration Contract

Each stack publishes its key outputs to AWS Systems Manager Parameter Store. This is the contract that lets downstream systems find the infrastructure at deploy time without hard-coding ids.

| Parameter | Contents |
| - | - |
| `/TalentId/Infra/Configuration/ExternalDependencies` | Ingestion, reports and backup bucket names and ARNs; timing provider user names; the API repository name |
| `/TalentId/Infra/ConfigurationInfra` | VPC id; ingestion and reports bucket names and ARNs; Lambda security group id; timing data and classification topic ARNs; API Gateway VPC endpoint id |
| `/TalentId/Infra/Configuration/MongoDb` | The name of the Secrets Manager secret holding the MongoDB credentials |

Downstream systems read these parameters when they deploy. That makes the parameter names and contents an interface: renaming or removing a key, or changing a value's shape, can break dependent deployments. Treat them as a published contract.

> [!NOTE]
>
> SG-Infra is one of the consumers of this contract: it reads `/TalentId/Infra/ConfigurationInfra` to discover the shared VPC. See [SG-Infra Networking, Dependencies and Configuration Contract](/software/developer/estate/infra/sg-infra/networking-and-config).

## Why It Is Built This Way

* Publishing infrastructure ids to Parameter Store decouples downstream stacks from this one. They look up what they need at deploy time instead of carrying hard-coded values.
* The trade-off is that the contract is implicit. There is no versioning of the parameter shapes and no automatic check that consumers still match.
* Several referenced resources (the buckets, the users, the API repo) are pre-existing and referenced by fixed names, so the stack assumes those exact resources exist.

## Key Files

| File | Role |
| - | - |
| `sg_infra/talent_id_externaldependencies_stack.py` | References the buckets, users and API repo; publishes the external dependencies parameter |
| `sg_infra/talent_id_infra_stack.py` | Creates the SNS topics and bucket event notification; publishes the infra parameter |
| `sg_infra/talent_id_mongo_instance_stack.py` | Publishes the MongoDB parameter |
| `sg_infra/talent_id_utils.py` | The helper downstream code uses to read these parameters |


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