architecture-paradigm-modular-monolith

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Chinese

When you desire team autonomy similar to that of microservices, but without the operational overhead of a distributed system.
When release velocity is slowed by tangled dependencies between internal modules.
When a monolithic architecture is simpler to operate today, but there is a clear need to evolve toward a service-based model in the future.

Identify Modules: Define module boundaries that align with distinct business capabilities or Bounded Contexts from Domain-Driven Design.
Encapsulate Internals: Use language-level visibility modifiers (e.g., public/private), separate packages, or namespaces to hide the implementation details of each module.
Expose Public Contracts: Each module should expose its functionality through well-defined facades, APIs, or events. Forbid direct database table access or direct implementation calls between modules.
Enforce Architectural Fitness: Implement automated tests that fail the build if forbidden dependencies or package references are introduced between modules.
Plan for Evolution: Continuously track metrics such as change coupling and deployment scope to make informed decisions about if and when to split a module into a separate service.

An Architecture Decision Record (ADR) that maps module boundaries and defines the rules for any shared code.
Formal contract documentation (e.g., OpenAPI specs, event schemas) for every interaction point between modules.
Automated dependency checks and dedicated CI/CD jobs for each module to enforce boundaries.

Regression to a "Big Ball of Mud":
- Mitigation: Without strict enforcement, module boundaries will inevitably erode. Treat any boundary violation as a build-breaking error and maintain a disciplined approach to code reviews.
Shared Database Hotspots:
- Mitigation: High contention on a shared database can become a bottleneck. Introduce clear schema ownership, use view-based access to restrict data visibility, or implement data replication strategies to reduce coupling.

退化回「大泥球」架构：
- 缓解方案：如果没有严格的强制规则，模块边界必然会逐渐失效。将任何边界违规视为会导致构建失败的严重错误，在代码评审中保持严格的纪律。
共享数据库热点问题：
- 缓解方案：共享数据库的高争用会成为瓶颈。引入清晰的schema所有权规则，使用基于视图的访问控制来限制数据可见性，或者实现数据复制策略来降低耦合。

Skill not loading Check YAML frontmatter syntax and required fields

Token limits exceeded Use progressive disclosure - move details to modules

Modules not found Verify module paths in SKILL.md are correct

Skill加载失败 检查YAML frontmatter语法和必填字段是否正确

超过Token限制 使用渐进式披露策略——将详情迁移到模块中

找不到模块 校验SKILL.md中的模块路径是否正确