Skip to content

Event-Driven Service Modules

Principle

All Nextpoint service modules communicate through domain events published to AWS SNS. Modules never call each other directly — they publish facts about what happened and subscribe to facts they care about.

Why Events, Not Direct Calls

  1. Loose coupling — modules can evolve independently. Adding a new consumer doesn't require changing the publisher.
  2. Resilience — if a downstream module is down, messages queue in SQS. Processing resumes when the module recovers.
  3. Scalability — each module scales its SQS consumers independently based on queue depth.
  4. Auditability — events are immutable facts. They form a natural audit log of everything that happened in the system.

Why Modules, Not Microservices

We build service modules — self-contained boundaries that share infrastructure (AWS account, VPC, RDS cluster) but own their own domain logic and data schemas.

Benefits over microservices: - Shared RDS cluster reduces operational overhead - No service mesh or API gateway complexity - Deployment is simpler — CDK stack per module, shared networking - Team can own multiple modules without managing multiple runtimes

Trade-offs we accept: - Modules share a deployment boundary (AWS account) - Database-level isolation (per-case schema) rather than per-service databases - SNS/SQS coupling at the message contract level

Why SNS for Everything

We use SNS for both cross-module and intra-module events, differentiated by event type:

  • One transport to learn, deploy, and monitor
  • Intra-module events can be promoted to cross-module by adding subscribers
  • Consistent retry, DLQ, and observability patterns everywhere
  • SNS filter policies handle routing — no application-level message filtering needed

Constraints

  • Events are facts about the past — named in past tense (DocumentLoaded, not LoadDocument)
  • Events are immutable — once published, they cannot be changed
  • Event schemas are versioned contracts — breaking changes require a new event type
  • Handlers are idempotent — SNS/SQS guarantees at-least-once delivery, not exactly-once
Ask the Architecture ×

Ask questions about Nextpoint architecture, patterns, rules, or any module. Powered by Claude Opus 4.6.