rl-docs-hub

Home · Apps · rl-main-infra

---

Repository Structure Standard

rl-main-infra is the platform Infrastructure-as-Code repo for the production AWS estate. It should not be treated as a single-workload repo.

The structure standard exists to keep five concerns clearly separated:

1. shared platform foundation
2. shared ingress / edge capabilities
3. workload modules
4. docs / runbooks / status artifacts
5. inventory / discovery / migration artifacts

Standard intent

The repo must stay readable as more workloads are added. The core rule is simple:

• reusable AWS building blocks belong in platform areas
• workload-specific composition belongs in workload areas
• import / cutover / migration code is isolated as transitional code
• docs and runbooks are not mixed into source modules
• discovery and inventory artifacts remain separate from authored IaC code

Naming transition rule

Use PBX in:

• documentation
• new workload folders
• new module names
• new config blocks where compatibility does not require otherwise

Keep OpenCX only as a legacy alias tied to existing code/config names that are already in use.

Practical naming policy

• user-facing docs: PBX
• new workload folder: src/workloads/pbx/
• new tags/config where safe: prefer pbx
• legacy references allowed only where compatibility matters: existing opencx module names, config keys, exports, or historical notes

Do not spread OpenCX into new docs or new folder/module names.

Recommended target layout

rl-main-infra/
├── inventory/
│   ├── discovery.json
│   ├── cloudflare/
│   └── route53/
├── scripts/
├── src/
│   ├── config/
│   │   ├── index.ts
│   │   ├── shared.ts
│   │   └── workloads/
│   │       ├── pbx.ts
│   │       ├── fed-proxy.ts
│   │       └── data-download.ts
│   ├── core/
│   │   ├── naming.ts
│   │   ├── tags.ts
│   │   ├── types.ts
│   │   └── discovery.ts
│   ├── platform/
│   │   ├── foundation/
│   │   ├── ingress/
│   │   ├── dns/
│   │   └── security/
│   ├── workloads/
│   │   ├── pbx/
│   │   ├── fed-proxy/
│   │   └── data-download/
│   ├── migrations/
│   │   ├── cloudfront/
│   │   ├── route53/
│   │   └── data/
│   └── index.ts
└── docs/
    ├── standards/
    ├── architecture/
    ├── runbooks/
    ├── migrations/
    └── status/

Structure rules

1) src/platform/foundation/

This area owns the shared platform baseline and import/reference modules for estate-wide AWS resources.

Examples:

• VPC / subnets / route tables / security-group baseline
• imported or referenced EC2/network/service primitives
• shared service import modules for ECS, ECR, API Gateway, S3
• account-wide baseline helpers used by multiple workloads

This area is for shared platform reality, not for one workload’s business intent.

2) src/platform/ingress/

This area owns reusable ingress and edge patterns.

Examples:

• CloudFront + S3 site pattern
• ALB + ECS service pattern
• ALB + EC2 service pattern
• NLB + EC2 service pattern
• WAF edge helpers

These modules should describe a transport/capability pattern, not a business workload.

3) src/workloads/

This area owns workload composition.

A workload folder answers questions like:

• how PBX is hosted
• how PBX web/admin ingress is assembled
• how PBX voice ingress is assembled
• what workload-specific DNS, cert, and security assumptions exist

Current/future examples:

• src/workloads/pbx/
• src/workloads/fed-proxy/
• src/workloads/data-download/

4) src/migrations/

This area owns temporary or high-churn transition code.

Examples:

• Route53 phased migration code
• CloudFront prep/cutover scaffolds
• one-off import helpers
• transitional data used only for staged migration execution

Migration code should be easy to find and easy to retire later.

5) inventory/

This area is for discovered or exported artifacts, not hand-authored architecture logic.

Examples:

• AWS discovery snapshots
• Cloudflare exports
• Route53 import batches
• generated migration data

Inventory is evidence/input material. It should not be confused with durable platform modules.

6) docs/

The repo-local docs should be separated by document type because they age differently.

• docs/standards/ → durable repo rules
• docs/architecture/ → workload/platform design notes
• docs/runbooks/ → operator procedures
• docs/migrations/ → transitional plans/status
• docs/status/ → dated execution notes

What should move now vs later

Adopt now

These rules should apply immediately even before a full refactor:

• new PBX code goes under src/workloads/pbx/
• new reusable ingress code goes under src/platform/ingress/
• new migration/cutover code goes under src/migrations/
• new docs go into categorized docs/ subfolders
• no new opencx naming unless compatibility requires it

Defer until previews are stable

These are worth doing later, not as a risky bulk rename:

• moving all current flat modules in one pass
• renaming legacy opencx modules/configs everywhere
• fully splitting config packages if it creates noisy churn
• retroactively reorganizing every older doc before new work can land

Final standard

rl-main-infra is a platform IaC repo.

That means:

• platform code = reusable shared capability
• workload code = PBX / fed-proxy / data-download composition
• migration code = temporary import/cutover execution logic
• inventory = discovered/exported artifacts
• docs/runbooks = operational and architectural documentation

If a new file does not clearly fit one of those buckets, the structure is probably wrong.