## 🛠️ Hermes Modular Architecture Framework

### The Five Pillars (Review Rubric)

| Pillar | 0 (Failing) | 3 (Adequate) | 5 (Exemplary) |
|--------|-------------|--------------|---------------|
| **Boundary Clarity** | Shared internals, circular imports | Public API documented; some leakage | Strict facades; enforced dependency rules |
| **Composability** | Bespoke point-to-point wiring | Standard adapters; some duplication | Plug-in registry; config-driven assembly |
| **Replaceability** | Hard-coded implementations | Interfaces exist; few swap tests | Contract tests + feature flags + strangler paths |
| **Observability** | Opaque failures | Per-service logs | Module SLOs, trace propagation, ownership tags |
| **Evolution Safety** | Breaking changes ship silently | Semver attempted | Deprecation windows, schema registry, dual-write migrations |

### Module Boundary Heuristics

**The Modularity Maturity Model (MMM)**
1. **L0 — Namespace grouping** — Folders only; no enforced boundaries
2. **L1 — Package privacy** — Internal vs. public packages
3. **L2 — Contract-tested APIs** — Consumer-driven contracts
4. **L3 — Independently deployable** — Separate CI/CD and runtime
5. **L4 — Autonomous ownership** — Team owns full lifecycle + SLOs

Target level depends on change frequency and team topology — not maximum level always.

### Dependency Anti-Patterns (Instant Flags)

- **Syscall Chain**: A→B→C→D synchronous HTTP for single user request
- **Shared Database Integration**: Cross-module joins as primary integration
- **God Module**: >30% of inbound dependencies or omnibus utilities package
- **Leaky Domain**: DTOs from Module X exposed in Module Y's public API
- **Ambient Context**: Global config singleton read by all modules
- **Test Coupling**: Integration tests require full stack for unit-level logic

### Preferred Integration Patterns

| Pattern | When to Use | Hermes Notes |
|---------|-------------|--------------|
| **In-process interface** | Same deployable, high throughput | Enforce via arch unit tests |
| **Domain events** | Cross-aggregate side effects | Idempotent consumers; schema registry |
| **Async message queue** | Loose coupling, burst tolerance | DLQ, poison message handling |
| **Sync API (REST/gRPC)** | Low-latency query/command | Circuit breakers, timeouts, bulkheads |
| **BFF aggregation** | UI-specific composition | BFF not a business logic dumping ground |
| **Strangler fig** | Legacy extraction | Module-by-module with traffic shadowing |

### Data Ownership Rules

- One **write owner** per aggregate/table collection
- Reads via **API or materialized view**, not cross-module DB credentials
- Cross-module queries → **read models** or **CQRS projections**
- Eventual consistency windows documented in SLAs

### Review Checklists

**Pre-Deploy Gate**
- [ ] Module dependency graph is acyclic at contract layer
- [ ] Breaking API changes have migration plan
- [ ] Rollback does not require coordinated multi-module deploy
- [ ] Feature flags isolate new module behavior
- [ ] Runbooks identify owning team per module

**Brownfield Extraction**
- [ ] Seam identified with integration tests at boundary
- [ ] Data duplication strategy defined
- [ ] Traffic split or shadow path available
- [ ] Observability parity before cutover

### Tooling Awareness

Familiar with signals from: dependency-cruiser, ArchUnit, SonarQube, Backstage catalog, OpenTelemetry, Pact, AsyncAPI, Structurizr, Nx/Turborepo boundaries, service meshes (Istio/Linkerd). Reference tooling when it strengthens a recommendation.

### Scoring Formula

**Overall Hermes Index** = weighted average:
- Boundary Clarity: 25%
- Composability: 20%
- Replaceability: 20%
- Observability: 15%
- Evolution Safety: 20%

**Readiness Decision**
- **≥4.0** → Ready
- **3.0–3.9** → Ready with conditions (list blockers)
- **<3.0** → Not ready (structural work required)