How codelytv/inbox_outbox_pattern-course works
1. This repo is a set of two closely related sample applications: 01-outbox and 02-inbox. Each contains a full Next.js + TypeScript codebase that demonstrates event-driven modular monolith style design, with the difference being how domain events are propagated and processed.
2. The main runtime is a Next.js app. Its only HTTP-facing API shown in the tree is under src/app/api/mooc/..., which exposes course and user endpoints. These route handlers are the presentation boundary; they call application services in the src/contexts/... tree rather than business logic directly.
3. The domain is split into bounded contexts:
- mooc for courses and users
- shop for products, product reviews, and shop users
- retention for email and user-retention projections
- shared for reusable primitives, event abstractions, and infrastructure helpers
Each context follows the same layered structure: domain entities/value objects, application use cases, and infrastructure adapters.
4. Persistence is PostgreSQL, with schema setup scripts in databases/ and shared DB plumbing in src/contexts/shared/infrastructure/postgres. Repositories are implemented per aggregate/context, for example PostgresUserRepository, PostgresCourseRepository, PostgresShopUserRepository, and PostgresProductReviewRepository. The repo also uses separate schemas such as public, mooc, shop, and retention to isolate context data.
5. The shared layer provides the architectural backbone: base domain classes, identifiers/value objects, a clock, UUID generation, event interfaces, event serialization/deserialization, HTTP error wrappers, and dependency injection configuration (diod.config.ts). This is what keeps the feature contexts decoupled from framework and transport concerns.
6. The central business event is user registration. mooc/users/application/registrar/UserRegistrar creates and persists a User aggregate, which emits UserRegisteredDomainEvent. That event becomes the integration point for other contexts rather than direct cross-context calls.
7. In the outbox variant, events are first written durably to Postgres via PostgresOutboxEventBus and later published to RabbitMQ by a separate script (publish-outbox-to-rabbitmq.ts). This creates a clear boundary between transactional state changes and external message delivery. The retention/email context also has an outbox-backed email sender in the later outbox example (PostgresOutboxEmailSender).
8. RabbitMQ is the asynchronous integration bus between contexts. The repo includes scripts to configure RabbitMQ and to consume messages. Subscribers such as SendWelcomeEmailOnUserRegistered and RegisterShopUserOnUserRegistered react to UserRegisteredDomainEvent and update their own local models or trigger side effects.
9. The retention context shows two kinds of downstream reactions:
- email handling in retention/email, which builds and sends a WelcomeEmail
- user projection/update handling in retention/retention-user, which updates a local retention model
In the inbox variant, retention/total-registered-users adds a durable counter projection, illustrating consumer-side processing of possibly duplicated events.
10. The shop context is another independent consumer of the user event stream. shop/shop-user mirrors registered users into a shop-specific read model, while shop/products and shop/product-reviews are standard CRUD/search subdomains backed by Postgres. This makes the repo a good example of multiple bounded contexts sharing only events and contracts, not tables.
11. The project also includes operational and developer tooling that matters to the architecture: compose.yml for local infrastructure, Makefile for common tasks, GitHub Actions CI, HTTP request samples in etc/request, and scripts for seeding courses, stress-testing user creation, and debugging message consumption. These scripts are part of the delivery/verification flow, not core business logic.
12. Tests mirror the production structure almost one-to-one: there are unit tests for domain and application services, repository tests for Postgres adapters, and API tests for the Next.js routes. That mirrors the intended dependency direction: presentation and infrastructure are thin wrappers around application and domain layers.
13. If you draw the architecture, the important flows are: HTTP request → route handler → use case → repository/domain event → outbox or event bus → RabbitMQ → downstream subscriber → local context repository or external side effect. The key boundary is that each bounded context owns its own data and reacts to events instead of calling into other contexts directly.
Main entry points: rabbitmq/RabbitMqEventBus.ts RabbitMQ · ShopUser.ts Shop context · rabbitmq/RabbitMqEventBus.ts RabbitMQ · route.ts MOOC API
Components 27
01-outbox
Outbox-pattern sample app
- Next app · Next.js frontend, API routes, and scripts for the outbox variant
01-outbox/3-outbox_pattern/src/app/layout.tsx - MOOC API · HTTP presentation boundary for mooc courses and users
01-outbox/3-outbox_pattern/src/app/api/mooc/courses/route.ts - User registrar · Creates and persists users, emitting registration events
01-outbox/3-outbox_pattern/src/contexts/mooc/users/application/registrar/UserRegistrar.ts - Course queries · Course search and find use cases
01-outbox/3-outbox_pattern/src/contexts/mooc/courses/application/search/CourseSearcher.ts - User model · User aggregate, value objects, and UserRegistered event
01-outbox/3-outbox_pattern/src/contexts/mooc/users/domain/User.ts - Course model · Course aggregate and repository contract
01-outbox/3-outbox_pattern/src/contexts/mooc/courses/domain/Course.ts - Shop context · Independent shop domain with products, reviews, and mirrored users
01-outbox/3-outbox_pattern/src/contexts/shop/shop-user/domain/ShopUser.ts - Products · Product catalog search and persistence
01-outbox/3-outbox_pattern/src/contexts/shop/products/domain/Product.ts - Reviews · Product review creation and search
01-outbox/3-outbox_pattern/src/contexts/shop/product-reviews/domain/ProductReview.ts - Shop users · Shop-side user mirror and event-driven registration
01-outbox/3-outbox_pattern/src/contexts/shop/shop-user/application/register-on-user-registered/RegisterShopUserOnUserRegistered.ts - Retention context · Email and retention projections reacting to user events
01-outbox/3-outbox_pattern/src/contexts/retention/retention-user/domain/RetentionUser.ts - Welcome email · Builds and sends welcome email on user registration
01-outbox/3-outbox_pattern/src/contexts/retention/email/application/send-welcome-email/SendWelcomeEmailOnUserRegistered.ts - Retention user · Updates local retention user activity data
01-outbox/3-outbox_pattern/src/contexts/retention/retention-user/application/update-last-activity-date/UpdateLastActivityDateOnUserUpdated.ts - Shared kernel · Base domain types, events, HTTP helpers, DI, and Postgres plumbing
01-outbox/3-outbox_pattern/src/contexts/shared/domain/AggregateRoot.ts - Outbox bus · Durable Postgres outbox and RabbitMQ event delivery
01-outbox/3-outbox_pattern/src/contexts/shared/infrastructure/domain-event/PostgresOutboxEventBus.ts - RabbitMQ · Cross-context integration bus used by subscribers and scripts
01-outbox/3-outbox_pattern/src/contexts/shared/infrastructure/domain-event/rabbitmq/RabbitMqEventBus.ts - Postgres · Context-isolated database schemas and repository storage
01-outbox/3-outbox_pattern/src/contexts/shared/infrastructure/postgres/PostgresConnection.ts
02-inbox
Inbox-pattern sample app
- Next app · Next.js frontend, API routes, and scripts for the inbox variant
02-inbox/2-inbox_pattern/src/app/layout.tsx - MOOC API · HTTP presentation boundary for mooc courses and users
02-inbox/2-inbox_pattern/src/app/api/mooc/courses/route.ts - User registrar · Creates and persists users, emitting registration events
02-inbox/2-inbox_pattern/src/contexts/mooc/users/application/registrar/UserRegistrar.ts - Retention context · Email, retention projection, and durable consumer-side counters
02-inbox/2-inbox_pattern/src/contexts/retention/retention-user/domain/RetentionUser.ts - Total users · Durable count of registered users from consumed events
02-inbox/2-inbox_pattern/src/contexts/retention/total-registered-users/application/increment/IncrementTotalRegisteredUsersOnUserRegistered.ts - Welcome email · Builds and sends welcome email on user registration
02-inbox/2-inbox_pattern/src/contexts/retention/email/application/send-welcome-email/SendWelcomeEmailOnUserRegistered.ts - Shop users · Shop-side user mirror and event-driven registration
02-inbox/2-inbox_pattern/src/contexts/shop/shop-user/application/register-on-user-registered/RegisterShopUserOnUserRegistered.ts - Shared kernel · Base domain types, events, HTTP helpers, DI, and Postgres plumbing
02-inbox/2-inbox_pattern/src/contexts/shared/domain/AggregateRoot.ts - RabbitMQ · Cross-context integration bus used by subscribers and scripts
02-inbox/2-inbox_pattern/src/contexts/shared/infrastructure/domain-event/rabbitmq/RabbitMqEventBus.ts - Postgres · Context-isolated database schemas and repository storage
02-inbox/2-inbox_pattern/src/contexts/shared/infrastructure/postgres/PostgresConnection.ts
Connections 29
- Next app → MOOC API: serves · App exposes HTTP routes for mooc operations
- MOOC API → User registrar: calls · Route handlers delegate to user use cases
- MOOC API → Course queries: calls · Route handlers delegate to course use cases
- User registrar → User model: creates · Registrar builds aggregate and emits domain event
- Course queries → Course model: reads · Course use cases work through the course model
- User registrar → Outbox bus: publishes · Domain events are stored durably in the outbox
- Outbox bus → RabbitMQ: delivers · Separate publisher forwards outbox events to RabbitMQ
- RabbitMQ → Shop users: consumes · Shop user subscriber reacts to UserRegistered
- RabbitMQ → Welcome email: consumes · Retention email subscriber reacts to UserRegistered
- RabbitMQ → Retention user: consumes · Retention projection subscriber reacts to user updates
- Shop users → Shop context: updates · Mirrors registered users into shop-local model
- Welcome email → Retention context: uses · Email use case belongs to retention bounded context
- Retention user → Retention context: updates · Retains local activity projection
- Shop context → Products: contains · Shop product subdomain
- Shop context → Reviews: contains · Shop product review subdomain
- Shop context → Shop users: contains · Shop user mirror subdomain
- Shared kernel → Outbox bus: supports · Shared event abstractions back the outbox bus
- Shared kernel → Postgres: supports · Shared persistence helpers back repositories
- Next app → MOOC API: serves · App exposes HTTP routes for mooc operations
- MOOC API → User registrar: calls · Route handlers delegate to user use cases
- User registrar → RabbitMQ: publishes · Events go directly to RabbitMQ in inbox variant
- RabbitMQ → Welcome email: consumes · Email subscriber reacts to UserRegistered
- RabbitMQ → Shop users: consumes · Shop user subscriber reacts to UserRegistered
- RabbitMQ → Total users: consumes · Durable projection increments on UserRegistered
- Welcome email → Retention context: uses · Email use case belongs to retention bounded context
- Total users → Retention context: updates · Projection stored in retention context
- Shop users → Postgres: persists · Shop user mirror stored in local database
- Shared kernel → RabbitMQ: supports · Shared event abstractions back RabbitMQ integration
- Shared kernel → Postgres: supports · Shared persistence helpers back repositories