rl-docs-hub

Home · Apps · rl-main-infra

---

Shared Ingress and Edge Patterns

rl-main-infra should model ingress as shared platform patterns first, then compose those patterns into workload modules.

This avoids a repo full of one-off files like pbx-alb.ts or pbx-cloudfront.ts when the underlying AWS pattern is reusable.

Pattern ownership rule

• reusable transport / edge capability → src/platform/ingress/
• workload-specific assembly of those capabilities → src/workloads/<workload>/

Standard pattern catalog

1) CloudFront + S3

Recommended module home: src/platform/ingress/cloudfront-s3-site.ts

Use for:

• static sites
• download portals
• installer distribution
• other S3-origin edge delivery use cases

Responsibilities:

• S3 origin wiring
• CloudFront cache/origin behavior defaults
• aliases and certificate attachment
• optional WAF integration
• outputs used later by Route53 aliasing

2) ALB + ECS

Recommended module home: src/platform/ingress/alb-ecs-service.ts

Use for:

• ECS-backed web/API services
• shared or dedicated ALB-hosted HTTP workloads

Responsibilities:

• ALB creation or attachment
• listener/listener-rule composition
• ECS target group attachment
• health-check settings
• workload-facing outputs for DNS and monitoring

Likely workload consumer:

• fed-proxy

3) ALB + EC2

Recommended module home: src/platform/ingress/alb-ec2-service.ts

Use for:

• HTTP(S) services hosted on EC2
• web/admin surfaces that should sit behind an ALB

Responsibilities:

• ALB creation or attachment
• SG wiring between ALB and EC2
• target group/listener config
• health-check path/port/protocol settings
• outputs for CloudFront or Route53 composition

Likely workload consumer:

• PBX web/admin ingress

4) NLB + EC2

Recommended module home: src/platform/ingress/nlb-ec2-service.ts

Use for:

• L4 TCP/UDP ingress to EC2-hosted workloads
• protocols that do not belong behind ALB or CloudFront

Responsibilities:

• NLB creation
• listener and target-group composition
• protocol-aware health-check choices
• outputs used by workload DNS composition

Likely workload consumer:

• PBX SIP/TLS ingress

PBX reference architecture

PBX is the first workload where the split between web ingress and voice ingress must be explicit.

Web/admin plane

CloudFront -> ALB -> PBX EC2

Why:

• PBX admin/client HTTP(S) traffic should follow the normal web edge pattern
• CloudFront certs live in us-east-1
• ALB and regional resources live in ap-southeast-1

Voice/trunk plane

NLB -> PBX EC2

Why:

• SIP/TLS is not an ALB/CloudFront workload
• voice ingress is an L4 concern
• RTP/media handling must be documented explicitly as a telephony exception, not hidden inside generic web-edge assumptions

Pattern composition rule for PBX

PBX should be represented as a workload folder, not as a stack of flat special-case modules.

Recommended shape:

src/workloads/pbx/
├── index.ts
├── host.ts
├── web-ingress.ts
├── voice-ingress.ts
├── dns.ts
└── types.ts

Where:

• host.ts owns PBX-host-specific EC2 assumptions
• web-ingress.ts composes ALB/CloudFront for PBX web access
• voice-ingress.ts composes NLB for SIP/TLS voice ingress
• dns.ts owns workload-specific aliases such as pbx.roylee.cloud

What not to do

Avoid these anti-patterns:

• embedding generic ALB + EC2 logic inside pbx-alb.ts
• embedding generic NLB logic inside a PBX-only helper when it could be shared
• treating CloudFront, ALB, NLB, and DNS as one giant special-purpose PBX file
• continuing to add new ingress modules flat under src/modules/

Decision guardrails

When adding a new ingress-related file, ask:

1. Can another workload use this without PBX naming in its interface?
   • if yes, it belongs under src/platform/ingress/
2. Does this file describe PBX business/workload composition?
   • if yes, it belongs under src/workloads/pbx/
3. Is this just for a migration/cutover window?
   • if yes, it belongs under src/migrations/

Naming rule reminder

For ingress docs and all new workload-facing modules:

• use PBX
• keep OpenCX only where an existing module/config/export still uses the legacy name for compatibility