Architecture

OPPA is one CDK application, app.py, with three stacks: the application stack, the CD pipeline, and the CI project. Packages live in the same repository and share one uv workspace.

Runtime pieces

Piece Role

Piece	Role
`oppa-gatekeeper`	Idempotency check and lock release for an invite. Reads and writes the idempotency table.
`oppa-beeper`	Sends Slack, CloudWatch, and event-logger notifications. Runs inside the VPC.
`oppa-mailbox-checker`	Reads Gmail for Amazon invitation messages and stores the link. Runs inside the VPC. Depends on the Google API client in addition to the shared layer.
`oppa-common`	Shared library, installed as a Lambda layer (`public.ecr.aws/sam/build-python3.12`).
Amazon invite orchestrator	State machine started from the environment event bus. Calls the gatekeeper, then the three machines below.
Create account	State machine that drives Invitius account creation and records the result.
Two-factor authentication	State machine that drives Invitius 2FA setup.
Email lookup	State machine that waits until the mailbox checker has stored the invitation email.

oppa-gatekeeper

Idempotency check and lock release for an invite. Reads and writes the idempotency table.

oppa-beeper

Sends Slack, CloudWatch, and event-logger notifications. Runs inside the VPC.

oppa-mailbox-checker

Reads Gmail for Amazon invitation messages and stores the link. Runs inside the VPC. Depends on the Google API client in addition to the shared layer.

oppa-common

Shared library, installed as a Lambda layer (public.ecr.aws/sam/build-python3.12).

Amazon invite orchestrator

State machine started from the environment event bus. Calls the gatekeeper, then the three machines below.

Create account

State machine that drives Invitius account creation and records the result.

Two-factor authentication

State machine that drives Invitius 2FA setup.

Email lookup

State machine that waits until the mailbox checker has stored the invitation email.

Invitius does the browser automation. OPPA sends it work on the Invitius SQS queue and reads uploads from the shared S3 bucket.

Data and integrations

Resource Use

Resource	Use
Assistance table	Workflow and invitation records. Partition key `pk`, sort key `sk`, global secondary index `GSI1`. Point-in-time recovery is enabled. A DynamoDB stream uses `NEW_IMAGE`.
Idempotency table	One in-flight invite per supplier and marketplace. Items expire through the `expiration` TTL attribute.
Secrets Manager `oppa`	Runtime secret read by the beeper.
Secrets Manager `event_logger_auth_key`	Auth material for the event logger client.
Event bus `pyb-notifications`	Slack notification events.
Environment event bus	Starts the orchestrator. The name follows the environment (`development`, `staging`, or `default` in production).

Assistance table

Workflow and invitation records. Partition key pk, sort key sk, global secondary index GSI1. Point-in-time recovery is enabled. A DynamoDB stream uses NEW_IMAGE.

Idempotency table

One in-flight invite per supplier and marketplace. Items expire through the expiration TTL attribute.

Secrets Manager oppa

Runtime secret read by the beeper.

Secrets Manager event_logger_auth_key

Auth material for the event logger client.

Event bus pyb-notifications

Slack notification events.

Environment event bus

Starts the orchestrator. The name follows the environment (development, staging, or default in production).

Accounts: development and staging use 605668041275. Production uses 625663093496. Region is us-east-1.

Code map

Path Contents

Path	Contents
`app.py`	CDK entry point. Defines the CI stack, the CD stack, and the application stage.
`oppa-cdk`	Application stack, Lambda constructs, and the four state machines.
`oppa-common`	Shared models, the event-logger client, and the layer image.
`settings.toml`	Dynaconf settings. `PYB_ENV` selects the environment.

app.py

CDK entry point. Defines the CI stack, the CD stack, and the application stage.

oppa-cdk

Application stack, Lambda constructs, and the four state machines.

oppa-common

Shared models, the event-logger client, and the layer image.

settings.toml

Dynaconf settings. PYB_ENV selects the environment.