Architecture — SplitApp Phase 3 (Modular Monolith)

This document is the architectural deep-dive for the Phase 3 refactor. The whole product lives under SplitApp.Modular/: one deployable, three internally isolated modules (Users, Trips, Expenses), MediatR for cross-module communication, schema-per-module Postgres isolation.

For the original course context, see also modularmonolith.md and phase3.md. The module-level README at SplitApp.Modular/README.md and the dedicated SplitApp.Modular/docs/ARCHITECTURE.md are the canonical references; this file is the high-level overview.

1. The picture

              ┌────────────────────────────────────────────────┐
              │           SplitApp.WebApp (host)               │
              │   Program.cs · Controllers · Areas/Admin       │
              │   Application/{Services, DTO, Mappers,         │
              │                 Persistence}                   │
              └────────────────────────────────────────────────┘
                       │           │           │
                       ▼           ▼           ▼
                ┌──────────┐ ┌──────────┐ ┌──────────┐
                │  Users   │ │  Trips   │ │ Expenses │
                │  Domain  │ │  Domain  │ │  Domain  │
                │  App     │ │  App     │ │  App     │
                │  Infra   │ │  Infra   │ │  Infra   │
                │  Api     │ │  Api     │ │  Api     │
                │  schema: │ │  schema: │ │  schema: │
                │   users  │ │   trips  │ │ expenses │
                └──────────┘ └──────────┘ └──────────┘
                     ▲           ▲           ▲
                     └─MediatR───┴─MediatR───┘
              ┌──────────────────────┐ ┌──────────────────────┐
              │  Shared.Contracts    │ │  Shared.Kernel       │
              │  IRequest/INotification│ │ BaseEntity, LangStr  │
              └──────────────────────┘ └──────────────────────┘

Each module = mini-Clean-Architecture (Domain ← Application ← Infrastructure, Api for REST). Each module owns its own DbContext scoped to its own Postgres schema. Cross-module function calls go through MediatR only — no direct <ProjectReference> between modules' Application / Infrastructure / Api layers.

2. Module layout

SplitApp.Modular/
├── SplitApp.sln
├── Directory.Build.props
├── src/
│   ├── SplitApp.WebApp/                                  ← composition root, host, admin Area
│   │   ├── Program.cs                                    ← AddXxxModule(...) wiring
│   │   ├── Application/                                  ← lifted phase-2 BLL
│   │   │   ├── Services/  (+ Admin/, Identity/)
│   │   │   ├── DTO/                                      ← BllDtos
│   │   │   ├── Mappers/                                  ← Domain ↔ BllDto factory mappers
│   │   │   ├── Persistence/AppUnitOfWork.cs              ← aggregates 3 module DbContexts
│   │   │   └── Persistence/CrossModuleNavigationLoader.cs
│   │   ├── Areas/Admin/, Areas/Identity/, Controllers/, Views/, Resources/
│   ├── Shared/
│   │   ├── SplitApp.Shared.Kernel/                       ← BaseEntity, IBaseRepo, IUoW, LangStr, IdentityHelpers
│   │   └── SplitApp.Shared.Contracts/                    ← MediatR IRequest / INotification
│   └── Modules/
│       ├── Users/
│       │   ├── SplitApp.Modules.Users.Domain/            ← AppUser, AppRole, AppRefreshToken
│       │   ├── SplitApp.Modules.Users.Application/       ← IIdentityService + JWT/refresh, MediatR handlers
│       │   ├── SplitApp.Modules.Users.Infrastructure/    ← UsersDbContext (schema "users"), repos, AddUsersModule
│       │   └── SplitApp.Modules.Users.Api/               ← /api/v1/identity/...
│       ├── Trips/                                         ← same 4-project layout, schema "trips"
│       └── Expenses/                                      ← same 4-project layout, schema "expenses"
└── tests/
    ├── SplitApp.Modules.{Users,Trips,Expenses}.Tests/    ← per-module unit tests
    └── SplitApp.WebApp.IntegrationTests/                  ← architecture invariants + smoke

3. Reference rules (compiler-enforced + arch-test verified)

Domain-level caveat: to keep view-rendering parity from phase 2 (mappers reading Trip.DefaultCurrency.Code, TripParticipant.User.FirstName, etc.), entity classes still declare cross-module navigation properties — annotated [NotMapped] so EF never crosses Postgres schemas. To make those property types compile, three Domain-to-Domain <ProjectReference>s exist:

Modules/Trips/SplitApp.Modules.Trips.Domain
   → Modules/Users/SplitApp.Modules.Users.Domain (for AppUser refs)
   → Modules/Expenses/SplitApp.Modules.Expenses.Domain (for Currency refs)
Modules/Expenses/SplitApp.Modules.Expenses.Domain
   → Modules/Users/SplitApp.Modules.Users.Domain (for AppUser refs)

This bends the strict "no direct references between modules" rule from phase3.md at the Domain level. Application, Infrastructure, Api projects remain isolated and use MediatR for actual function calls — only entity types are shared. Schema isolation, MediatR-only inter-module function calls, and per-module DbContext ownership are all preserved at runtime.

CrossModuleNavigationTests enforces the [NotMapped] rule: a mapped navigation across modules (where EF would actually try to traverse) fails the build.

4. Inter-module communication (MediatR)

Cross-module calls go through MediatR. Contracts live in SplitApp.Shared.Contracts/<Module>/{Queries|Events|Commands}/ and are records implementing IRequest<T> (sync queries/commands) or INotification (fan-out events). Handlers live in the owning module's Application or Infrastructure layer.

5. Schema isolation

Each module owns its own DbContext:

• UsersDbContext : IdentityDbContext<AppUser, AppRole, Guid> → schema users
• TripsDbContext : DbContext → schema trips
• ExpensesDbContext : DbContext → schema expenses

All three connect to the same physical Postgres database via the same ConnectionStrings:DefaultConnection. Cross-module SQL joins are forbidden — composition happens at the application layer through MediatR or the WebApp facade's CrossModuleNavigationLoader.

Cross-module entity references are bare Guid fields with no EF foreign-key constraints (e.g. Trip.CreatedById : Guid references users.AspNetUsers.Id only conceptually). Referential integrity is maintained by:

• Up-front MediatR validation queries (e.g. IsTripParticipantQuery before persisting an expense split)
• Domain-event cleanup on delete (UserDeletedEvent, TripDeletedEvent)

6. Composition root and lifted phase 2 BLL

SplitApp.WebApp is the only project that sees all three modules. It hosts the full phase 2 UI surface (101 Razor views, 21 MVC + Admin controllers, 10 REST API controllers, Identity Razor Register page) and lifts the entire phase 2 BLL layer into SplitApp.WebApp/Application/ under three buckets:

The lifted BLL services keep working unchanged: _uow.Trips.GetByIdAsync(...) behaves like phase 2. In reality AppUnitOfWork.Trips routes the query to TripsDbContext, and CrossModuleHydration fills cross-module navs (Trip.CreatedBy, Trip.DefaultCurrency) afterwards via separate single-shot batched queries against the foreign module's DbContext.

7. Phase 3 → phase 2 mapping (for context)

8. Architecture tests (run on dotnet test)

tests/SplitApp.WebApp.IntegrationTests/Architecture/:

1. ModuleBoundaryTests — no module's Application/Infrastructure/Api project has a <ProjectReference> to another module's project; no Shared.* project references a module.
2. DbContextSchemaIsolationTests — each DbContext only exposes DbSet<T> for entities that live in its own Domain project (plus a tiny framework allowlist).
3. CrossModuleNavigationTests — cross-module navigation properties are allowed only when annotated [NotMapped]. A plain mapped nav across modules (which would let EF cross schemas) fails the build.
4. HostBootSmokeTests — WebApplicationFactory<Program> boots the full host in Testing env (skipping per-module migrations) and verifies /, /Home/Index, and a 401 on unauthenticated API hits.

A failing architecture test means a developer just violated the modular-monolith invariant.

Total test count: 25 — Expenses (5) + Trips (7) + Users (4) + IntegrationTests (9). All passing on the current build.

9. Deployment

Production deployment: https://travel.rasmusj.com/

The repo's root Dockerfile + docker-compose.yml build and run phase 3 locally:

docker compose up --build

Per-module migrations run automatically on host startup. Sample data is seeded if DataInitialization:SeedData=true.

For per-module migration commands (dotnet ef migrations add ...) and the full URL map, see SplitApp.Modular/docs/ARCHITECTURE.md and SplitApp.Modular/README.md.

10. Why a modular monolith?

Future extraction path, if needed: Classic monolith → Modular monolith → Microservices. Each module already has its own schema, its own contracts, its own DbContext. Extracting a module into a separate service later means replacing in-process MediatR calls with HTTP/gRPC and domain events with a message broker — the code structure barely changes, only the transport layer.

See modularmonolith.md for the course material on the pattern.