Aoos-GPT infra conventions

This project's IaC is Pulumi (Python), not CDK or raw CloudFormation — infra/__main__.py is the one stack entry point. Don't introduce a second IaC tool (CDK, Terraform, a .yaml CFN template meant to be deployed directly) without checking with the user first; port CloudFormation into Pulumi resources instead, matching the pattern in infra/aws_config.py.

Layout

• infra/__main__.py — stack entry point. Deploys backend/mybot/api.py to App Runner (built from GitHub source, no Docker/ECR) and calls enable_aws_config().
• infra/aws_config.py — a self-contained module exposing one function, enable_aws_config() -> dict, called from __main__.py. Follow this pattern for any new independent concern (new file, one entry function, imported and called from __main__.py, outputs returned as a dict and pulumi.export-ed in __main__.py) rather than growing __main__.py into one large file.
• infra/requirements.txt — pins pulumi and pulumi-aws majors. Check the pinned pulumi-aws major before using a resource/arg shape from AWS provider docs — argument classes are codegenned and can differ between majors (e.g. aws.cfg.RecorderRecordingModeArgs needs pulumi-aws ~7+).

Conventions already in use — match these

• Config: pulumi.Config() for the stack's own settings (githubRepoUrl, openaiApiKey, ...) in __main__.py; pulumi.Config("awsConfig") (a namespaced config) for the AWS Config module's settings. Use config.require(...) for values with no sane default, config.get(...) or <default> for optional ones — mirror the CloudFormation template's own defaults when porting one.
• Secrets never go in plain env vars or resource args — write them to aws.secretsmanager.Secret + SecretVersion and reference the secret's ARN (runtime_environment_secrets / an IAM policy resource), not the value itself.
• Resources that must survive pulumi destroy (matching a CloudFormation DeletionPolicy: Retain) get pulumi.ResourceOptions(protect=True).
• Explicit depends_on is required wherever a resource only references a parent ARN and Pulumi can't infer the edge on its own (e.g. a recorder reading an S3 bucket policy that must exist first) — see aws_config.py for the pattern.
• aws.get_caller_identity() / aws.get_partition() for account ID and partition instead of hardcoding aws or an account number, so the stack stays portable to GovCloud/China partitions.

Known gotchas

• App Runner GitHub connection: pulumi up creates it PENDING; it needs a one-time manual authorization in the AWS Console (App Runner → GitHub connections → complete handshake) before a second pulumi up will actually build the service. This can't be automated from a Claude Code session — tell the user to do it, don't treat the stack as broken.
• AWS Config service-linked role is account-wide, not per-stack or per-region. If AWS Config has already been enabled once in this AWS account (by this stack in another region, or by something else), aws.iam.ServiceLinkedRole will fail on a second deploy. Set pulumi config set awsConfig:createServiceLinkedRole false in that case — don't just retry or add error-swallowing around it.
• AWS credentials are never available inside a Claude Code session here — pulumi preview/pulumi up can't actually be run from this sandbox. Validate changes with python3 -m py_compile infra/*.py and a careful read instead, and say explicitly that pulumi preview still needs to be run by the user with their own credentials before merging.

Adding a new AWS resource

1. If it's a new, separable concern, add a new infra/<name>.py module with one enable_<name>() (or similarly-named) entry function — don't bolt it onto aws_config.py or inline it in __main__.py.
2. Import and call it from __main__.py; pulumi.export anything the user would want to see after pulumi up (URLs, ARNs, bucket names).
3. Document any new pulumi config set keys this needs in the README's "Deploying the backend (Pulumi + AWS App Runner)" section, following the existing awsConfig:* keys as an example.
4. Run python3 -m py_compile on the changed files before calling the change done.