Modular Monolith · DDD · Vertical Slices

The standard advice for a modular monolith is "extract services later". In practice, later is a multi-month project: new repositories, new pipelines, every in-process call rewritten as an HTTP client, retries and circuit breakers added at each call site, tracing wired from scratch.

This template deletes that project. Modules never reference each other. They talk through two contracts that already work across process boundaries (integration events and inter-module requests, both over RabbitMQ), so where a module runs is a deployment setting, not a code change.

# Everything in one process (the default in modules.json)
ModulesOptions__EnabledModules__0=*

# The same image, running only the catalogue module
ModulesOptions__EnabledModules__0=Products

flowchart LR
    subgraph mono["One process: EnabledModules = *"]
        direction TB
        M1[IAM]
        M2[Products]
        M3[Inventory]
        M4[Notifications]
    end
    subgraph split["Same image, two processes"]
        direction TB
        subgraph pa["EnabledModules = IAM"]
            S1[IAM]
        end
        subgraph pb["EnabledModules = Products, Inventory"]
            S2[Products]
            S3[Inventory]
        end
    end
    mono ==> BUS[("RabbitMQ")]
    split ==> BUS

The call site that works in-process works across processes without a single changed line, and the trace context travels with every message. A runnable two-process demo lives in docs/split-deployment-poc.md.

This is deployment isolation on demand, not full microservices. docs/ARCHITECTURE.md explains every decision, its trade-offs and where it stops.

A store owner adds a product to their store. Here is everything that happens, and everything you did not have to write:

sequenceDiagram
    autonumber
    actor Owner as Store owner
    participant API as Products endpoint
    participant Agg as Store aggregate
    participant DB as PostgreSQL
    participant Out as OutboxProcessor
    participant MQ as RabbitMQ
    participant Inv as Inventory consumer

    Owner->>API: POST /v1/stores/my/products
    API->>API: validate request, check Keycloak scope products:create-own
    API->>Agg: Product.Create, store.AddProduct
    Agg->>API: domain events raised
    API->>DB: SaveChangesAsync, one transaction
    Note over API,DB: product row + OutboxMessages row + AuditLog row
    Out->>DB: claim a batch (FOR UPDATE SKIP LOCKED)
    Out->>MQ: publish ProductCreatedIntegrationEvent
    MQ->>Inv: deliver, possibly more than once
    Inv->>Inv: FusionCache pre-filter, then transactional inbox
    Inv->>DB: create StockLevel, commit together with the inbox row

1. The endpoint is a single method chained with CombineAsync, TapAsync and MapAsync. A failure anywhere short-circuits into a localized ProblemDetails response.
2. The aggregate enforces the invariants and records what happened as versioned, frozen domain events.
3. The state change, the outbox row and the audit row commit atomically. There is no dual write and nothing to forget.
4. The outbox processor publishes at least once. The consumer deduplicates with a cache pre-filter and a database inbox, so a redelivery has no second effect.
5. If Inventory runs in another process, nothing above changes.

The Keycloak scope check, the rate limiter, the structured logs, the OpenTelemetry spans and the audit trail come from the platform, not from the feature.

You need the .NET 10 SDK, Docker, GNU Make and the EF Core CLI (dotnet tool install --global dotnet-ef).

git clone https://github.com/baranacikgoz/modular-monolith-ddd-vsa-webapi.git
cd modular-monolith-ddd-vsa-webapi

# 1. One shared Docker network, created once (skip if it already exists)
docker network create local_shared_network

# 2. Backing services. Keycloak imports the realm from keycloak/realm-modular-monolith.json on first start.
docker compose up -d mm.postgres mm.rabbitmq mm.redis mm.keycloak mm.aspire-dashboard

# 3. Create the database and apply every module's migrations (local development only)
make ef-update-all

# 4. Build and start the API on http://localhost:5001
docker compose up --build host

The API refuses to boot while a module has pending migrations (see Database changes), which is why step 3 comes first.

Sign in as the seeded system administrator. In development the SMS provider is Dummy and the one-time code is always 123456:

curl -s -X POST http://localhost:5001/otp/login \
  -H 'Content-Type: application/json' \
  -d '{"phoneNumber":"901111111111"}'

curl -s -X POST http://localhost:5001/tokens \
  -H 'Content-Type: application/json' \
  -d '{"phoneNumber":"901111111111","otp":"123456","deviceId":"00000000-0000-4000-8000-000000000001","clientId":"mobile-app-1"}'

The second call returns accessToken, refreshToken and their expiry times. Paste the access token into Swagger's Authorize button, or send it as Authorization: Bearer <token>. More seeded users, the email and password login and the whole Keycloak model are in keycloak/README.md. A fuller walkthrough with an IDE, a split deployment and the load test is in docs/getting-started.md.

Routes, scopes, events, requests, jobs and configuration for each module are in docs/modules.md.

Conventions rot under deadline pressure. These do not, because the build checks them:

Schema changes are reviewed, not applied by the application. The workflow:

1. make ef-add-Products name=AddPriceColumn          create the migration
2. make ef-script-Products from=<previous> to=<new>   generate idempotent SQL into migrations/Products/
3. commit the .cs migration and the .sql script together
4. your DBA or deploy sidecar applies the .sql
5. deploy. The app checks for pending migrations and refuses to start if any remain.

In test runs pending migrations are applied automatically. For local development use make ef-update-all, which creates the database and applies every module's migrations in one command.

Everything goes through the Makefile.

This repository treats AI agents as first-class contributors, because strict architecture is exactly what makes them useful.

• CLAUDE.md is the numbered rulebook an agent (or a new teammate) reads first: architecture, platform services, exemplar files to copy, persistence rules, testing rules and the options pattern.
• .claude/commands/ holds 15 slash commands that encode the workflow: plan-feature, scaffold-feature, scaffold-module, scaffold-test, execute-feature, add-integration-event, add-inter-module-request, manage-feature-flag, manage-migration, fix-bug, plan-refactor, execute-refactor, audit-architecture, verify-feature and update-dependencies.
• Two hooks in .claude/hooks/ stop an agent from creating a cross-module project reference, after a project file edit and again before a commit.
• A generated knowledge graph in graphify-out/ lets an agent answer "where does this live" without grepping the tree.

Details are in docs/ai-workflow.md. None of it is required: the code is ordinary .NET and works with any editor.

Issues and pull requests are welcome. CONTRIBUTING.md explains the workflow and the checks a change must pass. Report vulnerabilities privately as described in SECURITY.md.

This template is the backend foundation of randevufast.com, an online appointment platform for barbershops, salons and clinics in Turkey. A second production system built the same way is a dropshipping platform where a product supplier's sellers connect their Trendyol and Hepsiburada stores and sell the supplier's catalogue, with stock tracked across all of them.

• Architecture review. I read your codebase against the concrete rule set this repository enforces with tests and send a prioritised written report with file and line references.
• Adoption sprint. We fork the template together, replace the demo domain with your first real module, wire the guardrail tests into your pipeline and set up how you keep pulling template updates. The agent rulebook and commands come with it if your team uses AI coding agents. Scoped in days, not in outcomes.
• Team workshop. Write to me for the details.

Write to baran-acikgoz@outlook.com.

Apache License 2.0. See LICENSE.