Modular Monolithic Architecture — Project Scaffolder
Generate production-ready Modular Monolith projects with proper module boundaries, internal APIs, shared kernel, and infrastructure following industry best practices.
Overview
A Modular Monolith is a single deployable application organized into loosely coupled, highly cohesive modules — each representing a bounded context. It combines monolithic simplicity (single deployment, ACID transactions, in-process calls) with microservices-style modularity (clear boundaries, team autonomy, independent development).
This skill scaffolds complete projects with:
- Module isolation: Each module owns its domain, data access, and API surface
- Inter-module communication: Via public contracts/interfaces, never internal details
- Shared kernel: Cross-cutting concerns (auth, logging, events) in a shared layer
- Database-per-module schema: Logical isolation within a single RDBMS
- Migration-ready boundaries: Modules can be extracted to microservices later
Workflow
Step 1: Gather Requirements
If the user hasn't specified, ask for:
- Language/Framework (e.g., C#/ASP.NET Core, Java/Spring Boot, TypeScript/NestJS, Python/Django, Go)
- Project name
- Business modules (e.g., Product, Order, Payment, Shipping, Notification)
- Database preference (PostgreSQL, MySQL, SQL Server, SQLite for dev)
- Additional features: Event bus, API gateway, Docker, CI/CD
If the user provides $ARGUMENTS, parse them: $ARGUMENTS[0] = language/framework, $ARGUMENTS[1] = project name, remaining = module names.
Step 2: Generate Project Structure
Read the architecture references for the chosen framework:
- For detailed structure patterns, see references/project-structures.md
- For module design patterns, see references/module-design.md
- For comparison and decision guide, see references/architecture-guide.md
- For event-driven patterns and event bus design, see references/event-driven-patterns.md
- For inter-module communication and contract versioning, see references/api-versioning-communication.md
- For concrete scaffold examples, see examples/dotnet-scaffold.md and examples/nestjs-scaffold.md
Generate the project following these critical rules:
Module Rules
- Each module gets its own directory with internal layers (Domain/Application/Infrastructure/API)
- Modules communicate ONLY through public contracts (interfaces/DTOs) — never reference another module's internal types
- Each module has its own database schema or migration folder
- Each module registers its own services/dependencies
- No circular dependencies between modules
Shared Kernel Rules
- Contains ONLY cross-cutting concerns: base entities, common value objects, event bus interfaces, auth abstractions
- Must be thin — if it grows large, something belongs in a module
- Never contains business logic specific to any module
Infrastructure Rules
- Single entry point (Program.cs / main.ts / main.py / main.go)
- Composition root wires all modules together
- Database context/session is shared but schemas are isolated
- Event bus for async inter-module communication (in-process, upgradeable to message broker)
Step 3: Generate Code
For each module, generate:
- Domain layer: Entities, value objects, domain events, repository interfaces
- Application layer: Use cases/commands/queries, DTOs, validation
- Infrastructure layer: Repository implementations, database configuration, migrations
- API layer: Controllers/handlers, request/response models, module registration
Also generate:
- Shared kernel: Base classes, event bus, common abstractions
- Host/entry point: Composition root, middleware, configuration
- Tests: Module unit tests, integration tests, contract tests, and architecture boundary tests — see references/testing-strategies.md
- Observability: Module-scoped logging, health checks, and tracing setup — see references/observability.md
- Docker (if requested): Dockerfile + docker-compose with database
- README.md: Architecture overview, how to run, how to add modules (use examples/README-template.md)
Step 4: Validate
After generation:
- Verify no module directly references another module's internal types
- Confirm each module has its own schema/migration folder
- Check that the shared kernel contains no business logic
- Ensure the project builds/compiles successfully
- Run any generated tests
Validation scripts are available in scripts/ for CI integration:
scripts/validate-boundaries.sh <modules-dir>— detects cross-module boundary violationsscripts/validate-shared-kernel.sh <shared-dir> <modules-dir>— ensures shared kernel doesn't reference modulesscripts/check-circular-deps.sh <modules-dir>— detects circular dependencies between modules
Step 5: Migration Guidance
If the user asks about extracting modules to microservices, see references/migration-to-microservices.md for a detailed step-by-step guide covering:
- When to extract (evidence-based signals)
- Pre-extraction checklist
- Creating the service, swapping the implementation, adding resilience
- Rollback strategy
Key Principles to Enforce
| Principle | What It Means | How to Enforce |
|---|---|---|
| High Cohesion | Module contains everything for its domain | Domain + Application + Infrastructure + API per module |
| Low Coupling | Modules don't depend on each other's internals | Communication only via shared contracts/interfaces |
| Single Responsibility | Each module has one bounded context | One business domain per module directory |
| Encapsulated Data | Module owns its data | Separate DB schema per module, no cross-module queries |
| Explicit Dependencies | All module dependencies are visible | Module registration file listing required contracts |
| Domain-Driven Design | Modules align with business domains | Named after business capabilities, not technical layers |
Example Invocations
/modular-monolith dotnet ECommerceApp Product Order Payment Shipping
/modular-monolith spring-boot MyShop catalog basket checkout
/modular-monolith nestjs SaasApp tenant billing notification
/modular-monolith go FinanceApp accounts transactions reportingWhen NOT to Use This
Suggest microservices instead if the user describes:
- Teams needing completely independent deployment cadences
- Requirements for polyglot tech stacks (Python ML + Go APIs + Java enterprise)
- Extreme per-service scaling requirements
- Already having Kubernetes infrastructure and DevOps maturity
Suggest a simple monolith if:
- Solo developer or very small team (1-3 devs)
- Prototype/MVP with unclear domain boundaries
- Application with fewer than 3 distinct business domains