This document provides essential context for AI coding assistants working within this repository.
It outlines architectural principles, constraints, naming conventions, and deployment workflows for applications built on the Atlantis Platform by 63Klabs and deployed to AWS using serverless services.
All code and infrastructure generated by AI must follow these standards.
This repository contains the application-specific code and infrastructure for a serverless workload deployed on AWS as a CloudFormation application stack.
It does not contain shared storage, networking, or pipeline infrastructure. Those are maintained separately by platform engineers.
It does contain a buildspec and scripts for deployment and testing. The application stack itself is defined in a CloudFormation template. All deployment scripts and templates are stored in application-infrastructure as that is where the pipeline will expect them to be located.
Applications deployed via this repository follow the Golden Path for cloud development:
- Serverless-first architecture
- Event-driven design
- Modular stacks
- CI/CD pipelines per branch
- Infrastructure as Code (CloudFormation/SAM)
Shared templates for S3, DynamoDB, caching, networking (CloudFront/Route53), and pipelines come from:
- Atlantis Platform Template Repo: https://github.com/63Klabs/atlantis-sam-templates
Scripts for configuring and Deploying automated CodePipeline stacks come from:
- Atlantis SAM Configuration Repo: https://github.com/63Klabs/atlantis-sam-config-scripts
The organization deploying the application is reponsible for their own organizion-wide copy of a SAM configuration repository. The SAM Config repository manages samconfig files and deployed infrastructure using scripts, expanding the capabilities of sam deploy. While a samconfig file may be kept in this repository for development deployment, actual deployments should occur using the scripts to ensure proper tagging, resource mangement, and automation.
AI MUST NOT generate code that:
- Modifies or duplicates platform templates
- Rebuilds shared infrastructure (e.g., Route53, CloudFront, global logging policies, or cross-account roles)
- Creates account-level policies or resources meant for administrators
- Introduces deployment strategies that differ from the Atlantis SAM Configuration strategy of a central
samconfigrepository.
Atlantis Platform Template are flexible and extendable.
For example, if extended permissions are needed for deploying an application stack, the Pipeline stack can be configured with managed policies.
-
According to the organization's guidlines, create Managed Policies and add them to the pipeline using the following:
CloudFormationSvcRoleIncludeManagedPolicyArnsCodeBuildSvcRoleIncludeManagedPolicyArnsPostDeploySvcRoleIncludeManagedPolicyArns
-
DO NOT edit or suggest edits the upstream Atlantis Platform Templates.
-
DO Review the Pipeline template or supporting templates (network, storage, etc) to understand how they can be configured to meet the needs of the application.
This repository only defines resources specific to this application. It should not include:
- Shared storage buckets
- Global DynamoDB tables
- Account-level CloudFront or Route53 resources
- Organization-wide logging policies
- Any infrastructure maintained by central platform engineering
These belong in separate stacks controlled by administrators.
It is acceptable to define S3 and DynamoDB within an application stack if architectually it makes sense for each instance to maintain it's own resources rather than share a partitioned resource with other instances of the same application or other applications.
All resource names must follow:
Prefix-ProjectId-StageId-Resource
S3 buckets have alternatives:
Prefix-ProjectId-StageId-AccountId-Region-an (specific deployment instance, no Resource identifier, Regional bucket)
Prefix-ProjectId-AccountId-Region-an (shared instance, no Resource identifier, Regional bucket)
Prefix-ProjectId-StageId-Resource (not preferred)
Or, if the organization requires an additional S3OrgPrefix identifier:
S3BucketNameOrgPrefix-Prefix-ProjectId-StageId-AccountId-Region-an (specific deployment instance, no Resource identifier, Regional bucket)
S3BucketNameOrgPrefix-Prefix-ProjectId-AccountId-Region-an (shared instance, no Resource identifier, Regional bucket)
S3BucketNameOrgPrefix-Prefix-ProjectId-StageId-Resource (not preferred)
Where:
- S3BucketNameOrgPrefix = organization prefix for all S3 buckets (lowercase)
- Prefix = team or org identifier (lowercase)
- ProjectId = short identifier for the application (lowercase)
- StageId = test, beta/stage, prod (lowercase)
- Resource = Purpose of resource: Users, Sessions, Queue, Orders, etc. (Pascal Case, Only first letter of Acronyms are capital)
AI must respect these naming conventions in all generated example code, IAM roles, and infrastructure.
These names will be provided to the CloudFormation template as parameters (Prefix, ProjectId, and StageId, S3BucketNameOrgPrefix).
Correct example:
Lambda: acme-person-api-test-GetPerson
StepFunction: acme-schedules-prod-Refresh
DynamoDB: acme-schedules-prod-Sessions
DynamoDB: acme-schedules-test-ApiResponseCount
S3: acme-orders-test-123456789012-xy-east-1-an
S3: acorp-acme-orders-123456789012-xy-east-1-an
S3: acorp-acme-orders-logs-123456789012-xy-east-1-an
Use S3 Regional bucket name spaces unless otherwise requested.
In some cases, a short Resource name (lower case) may be included after ProjectId-StageId if it helps identify the purpose of the bucket beyond the typical project identifier.
However, since bucket names are limited to 63 characters, and -AccountId-Region-an takes up about a third of that, and S3BucketNameOrgPrefix-Prefix-ProjectId-StageId can also take up a substantial amount, include a Resource descriptor only if necessary (e.g. multiple buckets in the same stack, or multiple buckets across shared Project stacks)
AI must follow these rules when generating IAM policies:
- Never use AWS managed policies such as
AWSLambdaFullAccess,AmazonS3FullAccess, orLambdaAll. - Always generate tight, resource-scoped permissions using ARNs that follow the naming convention.
- Policies must limit both actions and resources.
Correct:
Action:
- s3:PutObject
Resource:
- !Sub arn:aws:s3:::${Prefix}-${ProjectId}-${StageId}-output/* Incorrect:
Action: s3:*
Resource: "*"The following branches correspond to automated AWS Pipelines:
| Branch | Stage Id | Environment Type |
|---|---|---|
| test | test | TEST |
| beta | beta | PROD |
| main | prod | PROD |
The use/naming of a beta or staging stage is up to the project owner. However, when deployed, it functions like a production environment.
Production environments (PROD) will have gradual deployments, longer log retention, and CloudWatch Alarms and Dashboards.
Non-production environments (TEST) will have immediate deployments, shorter log retention, more verbose logs, and fewer resources that could incur costs that are only needed at the production level (such as Alarms and Dashboards).
Merge sequence:
dev → test → beta → main
AI-generated deployment instructions must follow this workflow.
- Pipeline Stack configuration and deployments are done exclusively through Atlantis Platform scripts.
- Scripts are centrally maintained and cloned internally through the organization's Atlantis SAM Configuration repository.
- Application Infrastructure changes must be deployed through the CI/CD pipeline using GitOps—not manual deployments.
- Conditional logic should be built into the template and any environment variables based on the Deployment Environment (TEST/PROD)
- Tests, Builds, and Deployment must be automated and provided in the buildspec.yml file used by the Pipeline.
- A
samconfigfile local to the application's repository may only be used for development purposes. - CloudFormation stacks deployed by SAM are the first choice. If complex or programmatic logic requires the use of AWS CDK or AWS SDK, the SDK or CDK MUST manage BOTH deployment and a clean tear down. The SDK or CDK MUST also include the tags (resolving any placeholders) found in
application-infrastructure/template-configuration.json. (See theapplication-infrastructure/build-scripts/update_template_configuration.pyscript for an example of how placeholders are resolved from environment variables.) - AWS CLI commands may be provided as instructions to:
- Copy files to S3
- Set SSM Parameters
- Query resources (read-only)
AI suggestions must not recommend:
- Manual AWS Console deployments
- Creating custom pipeline YAML/JSON
- Editing CodePipeline templates
- Using Terraform
- Using AWS CLI, AWS CDK, AWS SDK without proper tagging and clean-up
AI should suggest using AWS-managed services before writing custom code:
- EventBridge
- S3 event notifications
- SNS / SQS
- Step Functions
- DynamoDB
- API Gateway
Avoid large monolithic libraries; prefer event-driven, loosely coupled services.
AI must follow these rules:
- Do not package the AWS SDK for production deployment (already available in Lambda)
- Favor native language libraries
- Node.js built-in
crypto - Python
hashlib,datetime,json, etc.
- Node.js built-in
- Avoid large third-party libraries unless absolutely necessary
AI-generated functions or methods should include:
- Unit test scaffolding
- Meaningful test cases
- Mocking of AWS SDK calls
- Clear separation of business logic from handler code
- Use encryption at rest and in transit (KMS, HTTPS, S3 defaults)
- Enforce least privilege
- Ensure no secrets or credentials appear in code or logs
- Recommend Secrets Manager or SSM Parameter Store
- Avoid hardcoding environment variables that contain sensitive data
- Validate all inputs (API or event)
- Sanitize logs
AI tools should assume:
- This application runs in a serverless, event-driven model
- Infrastructure is defined via CloudFormation/SAM
- CI/CD is fully automated and CodePipeline is configured and maintained separately
- Naming conventions and permissions are strictly enforced
- The application will be long-lived and require maintainability and cost efficiency
AI should not assume:
- Use of EC2, EKS, or persistent servers
- Unrestricted IAM roles
- Direct access to VPC-bound enterprise systems unless explicitly provided
- Experimental architectures that break platform guardrails
It must:
- Fit within a modular architecture
- Follow naming conventions
- Respect the separation of stacks
- Avoid privileged or global resources
- Include appropriate IAM scoping
- Be consistent across test/beta/prod
Documentation and Tests must be kept up to date.
At the end of a spec-driven workflow, or after major changes are complete, ensure the following are updated:
- ARCHITECTURE.md
- DEPLOYMENT.md
- CHANGELOG.md
- docs/admin-ops (for Admins, Ops, Cloud Engineers, Cloud Architects)
- docs/developer (for Developers and Maintainers of the application who add features, fix bugs, and provide enhancements)
- docs/end-user (for Consumers of any API, web pages, or other products this application or service produces)
- Use serverless, event-driven, modular architectures.
- Follow strict naming:
Prefix-ProjectId-StageId-*. - Apply least privilege IAM policies—never AWS-managed policies.
- Never modify Atlantis platform templates.
- Expect automated deployments to be handled through GitOps; no manual deployments.
- Keep dependencies small; use AWS-native services.
- Include unit tests for new functions.
- Keep shared infrastructure out of this repo.
- Keep documentation and tests up to date.