@wazir-dev/cli 1.0.0

package/expertise/architecture/foundations/index.md

@@ -0,0 +1,25 @@
+# Directory Purpose
+
+The `foundations` directory contains the core principles and philosophies of software architecture, focusing on structure, modularity, and maintainability.
+
+# Key Concepts
+
+- Principles of clean code and design
+- Aligning software with business domains
+- Managing system complexity
+- Cloud-native application standards
+
+# File Map
+
+- `architectural-thinking.md` — mindset and approach to system design
+- `coupling-and-cohesion.md` — managing dependencies and module focus
+- `design-principles-solid.md` — SOLID, DRY, and YAGNI principles
+- `domain-driven-design.md` — bounded contexts, aggregates, and ubiquitous language
+- `separation-of-concerns.md` — dividing systems into distinct features
+- `twelve-factor-app.md` — methodology for modern cloud-native apps
+
+# Reading Guide
+
+If designing module boundaries → read `domain-driven-design.md` and `coupling-and-cohesion.md`
+If writing object-oriented code → read `design-principles-solid.md`
+If deploying to the cloud → read `twelve-factor-app.md`

package/expertise/architecture/foundations/separation-of-concerns.md

@@ -0,0 +1,472 @@
+# Separation of Concerns — Architecture Expertise Module
+
+> Separation of Concerns (SoC) is the practice of dividing a system so that each part addresses one distinct responsibility, making each part independently understandable, changeable, and replaceable. It is a prerequisite for maintainable systems at any scale — not because it enforces tidiness, but because it controls the blast radius of change.
+
+> **Category:** Foundation
+> **Complexity:** Simple
+> **Applies when:** Any project where code responsibilities need to be organized to enable independent change
+
+---
+
+## What This Is (and What It Isn't)
+
+### Dijkstra's Original Formulation
+
+Edsger Dijkstra introduced the term in his 1974 paper "On the role of scientific thought." His framing was epistemic, not structural: "It is what I sometimes have called 'the separation of concerns', which, even if not perfectly possible, is yet the only available technique for the effective ordering of one's thoughts." The point was about *mental focus* — the ability to think about one thing at a time by factoring a problem into parts that can be reasoned about independently.
+
+The architectural implementation of SoC is downstream of this insight: if you want to *think* about the database layer independently from the business rules, you must also *code* them independently. Structure follows thought.
+
+### Three Dimensions of Separation
+
+**Horizontal (Layered) Concerns**
+Separates the system by technical role. Presentation handles display. Business logic handles rules. Data access handles persistence. Each layer knows about the layer below it but not above. This is the most familiar form — MVC, three-tier architecture, and clean architecture are all horizontal separations. The classic web stack (HTML/CSS/JavaScript) is a canonical example: HTML handles content structure, CSS handles presentation, JavaScript handles behavior. Each can be changed without rewriting the others.
+
+**Vertical (Feature/Module) Concerns**
+Separates the system by business capability rather than technical role. An "orders" module contains its own presentation, business logic, and data access — all vertically sliced. Microservices and modular monoliths are vertical separations. Netflix's decomposition into hundreds of independent services (catalog, streaming, recommendations, billing) is vertical SoC: each service owns its full stack for one bounded capability.
+
+**Aspect-Oriented (Cross-Cutting) Concerns**
+Some behaviors genuinely span all other concerns: logging, authentication, caching, transaction management, error handling. These are called cross-cutting concerns because they cannot be neatly assigned to a single layer or module — they appear everywhere. Aspect-Oriented Programming (AOP) addresses this by defining an "aspect" (the what) and "pointcuts" (the where) separately from the core business code. Spring AOP in Java, for example, allows you to declare "log entry and exit for every method in the service layer" in one place rather than 200 places.
+
+### What SoC Is NOT
+
+**Not folder structure.** Moving files into subdirectories does not create separation. If `services/UserService.js` still directly queries the database and renders HTML, the folders are cosmetic.
+
+**Not "one class, one purpose."** SoC operates at the boundary level — concern boundaries are defined by what varies independently and what needs to be understood independently. A class serving a single well-bounded concern may have dozens of methods.
+
+**Not the same as SOLID's Single Responsibility Principle.** SRP says a class should have one reason to change. SoC is a broader architectural principle about which *parts of the system* are cognitively and technically independent. SRP is one implementation strategy for SoC at the class level, but SoC applies at module, service, layer, and system levels where SRP does not.
+
+**Not about minimizing coupling at all costs.** SoC accepts that concerns must communicate. The goal is to make the communication explicit, narrow, and stable — not to eliminate it. A well-separated system has clear interfaces between concerns, not zero connections.
+
+**Not a goal in itself.** Separation that does not enable independent change, independent testing, or independent understanding is not SoC — it is indirection. The test is always: "Can I change or reason about this concern without touching the others?"
+
+---
+
+## When to Use It
+
+### The Primary Signal: Change Propagation
+
+The strongest signal that SoC is needed is when a single logical change requires edits in many unrelated files. When you fix a business rule and must also change database queries and update UI rendering in the same commit, concerns are entangled. When a one-line business logic change becomes a 10-file PR, separation is overdue.
+
+### Specific Triggers
+
+**Multiple teams touching the same files.** If the frontend team and backend team both edit `app.js`, the file is doing too many things. At two-team scale, separating presentation from business logic becomes a coordination mechanism, not just a code quality preference.
+
+**Testing is impossible without the whole system.** When unit tests require database connections because business logic is tangled with data access, separation is the prerequisite for testability. The inability to test a business rule in isolation is a structural problem, not a test-writing problem.
+
+**The same logic appears in multiple layers.** If validation logic appears in the UI, in the API controller, and in the database layer, it will diverge. Centralizing it in one place (the business/domain layer) eliminates the synchronization problem.
+
+**Reasoning about one change requires understanding everything.** When a developer must hold the entire codebase in their head to make a small change, the cognitive cost is a symptom of insufficient separation. Dijkstra's original insight applies directly: if you cannot focus on one thing, the structure is working against you.
+
+### Real Costs of Poor SoC
+
+**The Big Ball of Mud.** Brian Foote and Joseph Yoder's 1997 paper described this pattern by name: systems where no dominant architectural structure exists, where changes ripple unpredictably, where developers are afraid to touch anything. The paper noted that this is the most common architecture pattern in production systems — not by design, but by entropy.
+
+**Satellite embedded systems.** Research on embedded real-time satellite software (AOCS, thermal regulation, power management) found that without explicit concern separation, cross-subsystem dependencies caused certification failures: a change to the thermal regulation subsystem invalidated assumptions in the attitude control subsystem because shared state was not cleanly isolated. The cost was not code quality — it was re-certification cycles measured in months.
+
+**Large-scale monoliths.** Companies that delayed concern separation in monolithic codebases (the "majestic monolith" that grew ungoverned) faced migration costs in the millions of engineering hours. The canonical pattern: a startup builds fast with entangled concerns, reaches 50-100 engineers, and discovers that deploy times are 45 minutes, any change breaks something unrelated, and a full rewrite becomes the only option. The rewrite is the tax on deferred SoC.
+
+### Team and Project Size Thresholds
+
+- **Solo developer, <3 months:** Light separation. Keep related code co-located. Defer to "extract when it hurts."
+- **2-5 developers, 3-12 months:** Separate data access from business logic. Introduce explicit interface contracts at concern boundaries.
+- **5+ developers or multiple teams:** Enforce vertical separation by module or domain. Cross-cutting concerns must be centralized (logging, auth, error handling).
+- **Microservices threshold:** Only cross service boundaries when deployment independence is required. Premature service extraction (splitting before the concern boundary is stable) creates distributed monoliths — all the cost, none of the benefit.
+
+---
+
+## When NOT to Use It
+
+This section is as important as the preceding one. The failure mode of understanding SoC only as "separate more" produces systems that are harder to work with than the entangled code they replaced.
+
+### The Premature Abstraction Trap
+
+The maxim "duplication is far cheaper than the wrong abstraction" (Sandi Metz) applies directly. Separating a concern before its boundaries are understood creates an abstraction that *looks* like a contract but *is* a constraint. Every module that depends on a premature abstraction inherits its incorrect assumptions. Untangling a bad abstraction is more expensive than untangling duplicated code, because duplication can be deleted — a bad abstraction must be unwound from every dependent.
+
+The pattern: a developer sees two functions with similar structure and extracts a shared abstraction. Six months later, one of the two use cases diverges. Now the abstraction must be parameterized, bent, or worked around. The abstraction has become a maintenance burden instead of a simplification.
+
+### Over-Separation: Death by Indirection
+
+A practical example of over-separation: a developer follows "clean architecture" strictly for a 200-line CRUD application. The result: a `UserController`, a `UserService`, a `UserRepository`, a `UserRepositoryInterface`, a `UserDomainModel`, a `UserDTO`, a `UserMapper`, and a `UserValidator` — eight files for what is, functionally, "store and retrieve a user." Reading a simple query now requires tracing through six layers of indirection.
+
+This is the "astronaut architect" anti-pattern (Joel Spolsky's term): architects who abstract so high above the actual code that they lose contact with what the system actually does. The indirection does not serve independent change — the business logic, the data model, and the API contract all change in lockstep, because the domain is simple. The separation creates navigation overhead without separation benefit.
+
+**The Proliferation of Code anti-pattern** (formally named in software engineering literature) describes objects that exist only to invoke another object. A `LoggingServiceFacadeFactory` that does nothing but call `new LoggingService()` adds a layer of indirection with zero semantic content. These appear in over-separated systems as the architect fills in the "gaps" between layers with glue objects.
+
+### When Co-Location Beats Separation
+
+**The Locality Principle.** Code that changes together should live together. If every feature change requires editing five files across five directories, the separation is fighting the natural grain of the system. Feature-sliced vertical architectures often outperform strictly layered architectures for co-located development: `features/checkout/` containing its own components, logic, and queries is easier to navigate than `components/Checkout.tsx`, `services/checkoutService.ts`, `repositories/orderRepository.ts`, and `types/checkout.ts` spread across a tree.
+
+**Simple scripts and utilities.** A 50-line data transformation script does not need a repository layer, a service layer, and a domain model. Co-location is correct here. The tax of separation exceeds the benefit when the system is small enough to hold in one screen.
+
+**Prototypes and proof-of-concept code.** Separation in a prototype is premature investment in code that may be thrown away. Prototype code should optimize for speed of iteration. The concern separation of production code is a deliberate choice, not a quality signal — applying it prematurely to exploration code wastes time and creates false permanence.
+
+**When the "concern" is not stable.** Separation creates a contract — an interface that downstream code depends on. If the concern boundary itself is uncertain (you do not yet know whether "user authentication" and "user authorization" will be handled by one system or two), stabilizing the boundary prematurely forces a refactor later. Wait until the boundary is stable before formalizing it.
+
+### The False Abstraction Anti-Pattern
+
+A false abstraction is any interface, base class, or adaptor that exists without a second implementation and has no realistic prospect of one. `IUserRepository` implemented by exactly one class, `UserRepository`, is not SoC — it is ceremony. The interface provides no actual separation because there is nothing to swap behind it. The added indirection makes the code harder to read and the stack traces harder to follow, with no compensating benefit.
+
+Rule of thumb: an abstraction is justified when you have (or can clearly foresee) at least two implementations, or when the interface boundary is required for testing (a mock/stub will be the second implementation). One class, one interface, no test benefit = false abstraction.
+
+### When Integration Is the Right Answer
+
+Some problems are integrative by nature. A reporting module that must aggregate data from orders, users, products, and inventory cannot be cleanly separated — it is, by definition, a cross-cutting read model. Forcing it through strict separation creates N+1 query problems, unnecessary DTO mapping, and performance overhead. Read models and reporting layers are legitimately allowed to reach across concern boundaries, because their purpose is to integrate.
+
+---
+
+## How It Works
+
+### Identifying Concerns
+
+A "concern" in SoC is not a synonym for "class" or "function." It is a dimension along which the system can change. The identification question is: "What would have to change if X changed?" If changing the database schema requires also changing the API response format, schema and API format are not separate concerns — they are entangled.
+
+Practical identification technique: draw a change matrix. For each type of foreseeable change (new business rule, new UI design, new data store, new third-party API, new compliance requirement), list which code modules must change. Modules that must change together are either correctly co-located or incorrectly entangled — the distinction is whether the co-change is *semantic* (they represent the same concern) or *accidental* (one leaked into the other).
+
+### Stable vs. Volatile Concerns
+
+Not all concerns deserve equal separation investment. Stable concerns — things unlikely to change — do not need to be isolated defensively. Volatile concerns — things likely to change independently — must be isolated aggressively.
+
+Common stability profiles:
+- **Stable:** Core business rules (what an order is, what constitutes a valid transaction), domain entities.
+- **Volatile:** External API contracts (third-party services change), UI rendering (design systems evolve), infrastructure specifics (cloud provider, database engine).
+- **Variable by context:** Authentication mechanism (stable in B2B SaaS, volatile when adding OAuth providers), caching strategy (stable until scale changes).
+
+Robert Martin's Stable Dependencies Principle: stable modules should not depend on volatile modules. Your domain model should not depend on your database schema. Your business rules should not depend on your HTTP framework.
+
+### Interface Contracts at Concern Boundaries
+
+Concern boundaries must be formalized as contracts. In statically typed languages, these are interfaces or abstract types. In dynamically typed languages, they are documented protocols (explicit duck typing). The contract specifies what one concern promises to another — and nothing more. Leaking internal implementation details through a contract defeats the separation.
+
+A well-formed contract at a concern boundary has three properties:
+1. **Minimal**: exposes only what the downstream concern needs, not what the upstream concern happens to have.
+2. **Stable**: changes rarely, even when the implementation behind it changes often.
+3. **Explicit**: there is no implicit coupling (shared global state, implicit ordering dependencies, hidden side effects).
+
+### Cross-Cutting Concerns and AOP
+
+Cross-cutting concerns (logging, auth, caching, transactions, validation, error handling) are the hardest to separate cleanly because they genuinely belong everywhere. Three handling strategies:
+
+**Aspect-Oriented Programming (AOP).** Defines concerns as "aspects" applied to "joinpoints" (specific points in execution: method entry, method exit, exception throw). Spring AOP (Java/Kotlin), PostSharp (.NET), and similar frameworks allow declaring "wrap every service method with transaction management" in one file rather than 200. The core business code is unaware of the aspect; the aspect is applied by the framework at compile time (weaving) or runtime (proxy).
+
+**Decorator/Middleware Pattern.** Used in web frameworks universally. Express.js middleware, Django middleware, and ASP.NET filters are all decorator patterns for cross-cutting concerns. A request passes through an authentication middleware, then a logging middleware, then a rate-limiting middleware before reaching the handler. Each middleware is a separate concern, each independently testable, each independently removable.
+
+**Convention-Based Centralization.** For concerns that cannot be injected cleanly, establish a single entry point. All errors flow through one error handler. All logging is initiated from one logger factory. All external API calls pass through one HTTP client with retry logic and circuit breaking built in. The concern is not *separated from* the business code — the business code calls it explicitly — but it is *centralized* so changes to the concern require one edit.
+
+---
+
+## Trade-Offs Matrix
+
+| You Get | You Pay |
+|---------|---------|
+| Testability of individual concerns in isolation | Indirection overhead — more files, more layers to trace |
+| Independent deployment of separated modules | Integration testing burden — concerns must be tested together too |
+| Team autonomy — teams own their concern | Coordination overhead at concern boundaries (API contracts, versioning) |
+| Changeability — modify one concern without ripple effects | Discovery cost — finding where a behavior lives requires knowing the structure |
+| Replaceability — swap implementations behind interfaces | Mapping overhead — DTOs, adapters, and translators at every boundary |
+| Cognitive focus — reason about one thing at a time | Onboarding tax — new developers must learn the separation model before contributing |
+| Fault isolation — failures in one concern don't corrupt others | Latency in distributed systems — network calls replace in-process calls |
+| Compliance auditability — trace where sensitive data flows | Risk of premature separation — wrong boundaries are expensive to undo |
+| Parallel development — teams work independently | Integration friction — independently developed concerns must still fit together |
+| Evolutionary architecture — change one concern's technology independently | Abstraction leakage — underlying details often surface despite separation |
+
+---
+
+## Evolution Path
+
+### Stage 0: Co-Located Everything
+
+All logic in one file or one layer. Valid at project start — you do not yet know where the boundaries are. Do not fight this. The cost of wrong separation exceeds the cost of no separation at this stage.
+
+**Signal to move to Stage 1:** The file is growing beyond 300-400 lines, or two different *types* of changes are landing in the same file (e.g., UI changes and business rule changes both touch `App.js`).
+
+### Stage 1: Identify Stable vs. Volatile Concerns
+
+Before splitting code, map concerns. Answer: "What changes independently?" Draw the change matrix described above. Identify the most volatile boundary: typically data access vs. business logic, or UI vs. everything else.
+
+### Stage 2: Extract Along One Boundary
+
+Extract the single most valuable separation first. Usually: separate data access from business logic. Add an explicit interface at the boundary. Do not reorganize the whole codebase — extract one concern.
+
+**Migration pattern for legacy systems:** The Strangler Fig Pattern. New code respects the separation. Old code is refactored incrementally as it is touched. Never attempt a full-codebase separation in one pass — it creates a multi-month branch that can never be merged cleanly.
+
+### Stage 3: Enforce Boundaries with Tooling
+
+Separation without enforcement degrades. Teams under deadline pressure will import directly across concern boundaries. Enforce with:
+- **Dependency analysis tools**: `dependency-cruiser` (Node.js), `ArchUnit` (Java/Kotlin), `enforce-module-boundaries` (Nx for TypeScript monorepos), `import-linter` (Python).
+- **Package/module structure**: In languages with strong module systems (Go packages, Rust crates, Java modules), encode the separation in the build system. Crossing a boundary requires an explicit dependency declaration — accidental coupling becomes a build error.
+
+### Stage 4: Centralize Cross-Cutting Concerns
+
+Once horizontal/vertical separation is established, address cross-cutting concerns. Audit the codebase: where does logging appear? Where is authentication checked? Where is caching implemented? Centralize each one.
+
+### Signals That SoC Is Breaking Down
+
+- PRs for simple features touch 10+ files across multiple layers.
+- Test setup requires instantiating half the application.
+- The same business rule is implemented (slightly differently) in multiple places.
+- Developers cannot describe where a concern "lives" — the answer is "everywhere."
+- A change to one dependency (database driver, HTTP library) requires changes throughout the codebase.
+- Onboarding a new developer takes weeks before they can make any change safely.
+
+---
+
+## Failure Modes
+
+### Over-Separation: Death by Abstraction
+
+Described above in "When NOT to Use It." The measurable symptom: adding a new field requires editing 8 files (entity, DTO, mapper, repository, service, controller, test, migration). The diagnosis: the separation is at a finer granularity than the system's actual change rate. Fix: merge layers that always change together.
+
+A documented real-world example: enterprise Java systems in the early 2000s following J2EE's strict layering produced applications where a "Hello World" required 15 classes across 5 packages. The industry reaction was Spring Framework (2003), which preserved concern separation while eliminating the mandatory ceremony. The lesson: separation must be proportionate to the volatility of the concern.
+
+### Under-Separation: God Classes and Files
+
+The opposite failure. A single `UserManager` class that handles authentication, authorization, profile management, notification preferences, billing, and audit logging. When it breaks, nobody knows where to look. When it must change, every team is affected. When it must be tested, the entire dependency graph must be instantiated.
+
+God classes are not always the result of laziness — they often grow by accretion, each addition individually reasonable, the whole becoming unmaintainable. The diagnostic question: "How many different *types* of changes has this class received in the last 6 months?" More than 3-4 distinct types indicates it is doing too many things.
+
+### Leaky Abstractions
+
+Joel Spolsky's Law of Leaky Abstractions: "All non-trivial abstractions, to some degree, are leaky." A concern boundary that leaks internal details forces callers to know what they should not. An ORM that requires callers to understand N+1 queries leaks its database implementation details into the business layer. A "service" that returns database entity objects instead of domain objects leaks persistence concerns into the API layer.
+
+The fix is not to deny that abstractions leak, but to design the boundary so that the leak is minimal and the leaked knowledge is stable. Accept that HTTP details will sometimes surface in service layer tests — design the tests to be resilient to it rather than pretending the leak does not exist.
+
+### Incorrect Concern Identification
+
+The most insidious failure: the separations exist, but they are drawn at the wrong boundaries. A system that separates by technical role (MVC) when it should separate by business domain (DDD bounded contexts) will have correct-looking structure but constant cross-cutting changes. Every new feature requires changes in every layer because features are not aligned with layers.
+
+This is the argument for "vertical slicing" over pure horizontal layering in feature-rich applications: if features are independent, separate by feature. If technical roles are independent, separate by role. The wrong choice here produces a system that is well-separated in the wrong dimension — which is often worse than no separation, because the wrong structure creates confident-but-incorrect navigation.
+
+### Production Incidents Linked to Poor SoC
+
+**The Therac-25 radiation machine (1985-1987).** A software-controlled radiation therapy machine caused six documented overdose accidents, three fatal. Post-incident analysis found that race conditions in shared state occurred because safety-critical and UI concerns were not separated — a UI event could overwrite a safety interlock variable. The failure mode was direct entanglement of concerns that should have been isolated behind strict interfaces with safety guarantees.
+
+**Distributed monolith failures.** Teams that split a monolith into microservices without first identifying clean concern boundaries produce "distributed monoliths": services that cannot be deployed independently because they share databases, call each other synchronously in long chains, and have no independent business capability. The service boundaries are structural (separate processes) but not semantic (shared concerns). This architecture has the operational overhead of microservices and the coupling of a monolith — the worst of both worlds. The fix requires the SoC analysis that should have preceded the split.
+
+---
+
+## Technology Landscape
+
+### Layer Enforcement
+
+| Tool | Language/Ecosystem | What It Enforces |
+|------|--------------------|-----------------|
+| `dependency-cruiser` | Node.js/TypeScript | Import rules across modules, layers, features |
+| `ArchUnit` | Java/Kotlin | Package dependency rules, layer constraints |
+| `Nx enforce-module-boundaries` | TypeScript monorepos | Cross-project import rules |
+| `import-linter` | Python | Import contracts between packages |
+| `go mod` + internal packages | Go | `internal/` packages prevent external access |
+| Rust crate visibility | Rust | `pub`/`pub(crate)`/private module boundaries |
+
+### Aspect-Oriented Programming Frameworks
+
+| Framework | Language | Typical Uses |
+|-----------|----------|-------------|
+| Spring AOP | Java/Kotlin | Transactions, logging, security, caching |
+| AspectJ | Java | Full AOP (compile-time and load-time weaving) |
+| PostSharp | .NET/C# | Logging, caching, validation, exception handling |
+| `aspectlib` / `wrapt` | Python | Method interception, logging |
+| `go-aop` | Go | Limited AOP via interfaces |
+| Proxies / decorators | JavaScript/TypeScript | Logging, caching (no formal AOP framework) |
+
+### Feature Slicing Frameworks
+
+| Framework | Ecosystem | Approach |
+|-----------|-----------|---------|
+| Nx | TypeScript/JS monorepos | Enforced module boundaries, project graph |
+| Feature-Sliced Design (FSD) | Frontend (React/Vue) | Strict vertical feature + layer hierarchy |
+| Vertical Slice Architecture | .NET (MediatR) | One folder per feature with handler, command, query |
+| Domain-Driven Design | Language-agnostic | Bounded contexts as primary separation unit |
+
+### Module Boundary Checkers
+
+For enforcing that concern boundaries do not erode over time:
+- **SonarQube**: detects circular dependencies and package coupling metrics.
+- **Structure101**: visualizes and enforces architecture diagrams as code.
+- **Deptrac** (.php/multi-language): YAML-defined layer rules, CI integration.
+- **Checkstyle + custom rules**: Java import rule enforcement.
+
+---
+
+## Decision Tree
+
+```
+Is the behavior expected to vary independently of its neighbors?
+├── YES → Separate it.
+│         Does separating require more than 2 indirection layers?
+│         ├── YES → Question whether the layers are all necessary.
+│         │         Do all layers have at least 2 implementations (or test mocks)?
+│         │         ├── YES → The indirection is justified.
+│         │         └── NO  → Collapse redundant layers (false abstraction risk).
+│         └── NO  → Separate freely.
+│
+└── NO  → Keep it together.
+          Is this the second time you've needed to change these two things independently?
+          ├── YES → The boundary is becoming real. Begin extracting.
+          └── NO  → Wait. Co-locate. Revisit when you have more evidence.
+
+Are you handling a cross-cutting concern (logging, auth, caching, transactions)?
+├── YES → Centralize in an aspect, middleware, or single utility.
+│         Does your language/framework support AOP?
+│         ├── YES → Use AOP (Spring, AspectJ, PostSharp).
+│         └── NO  → Use middleware, decorators, or explicit call to centralized utility.
+│
+└── NO  → Proceed with horizontal or vertical separation.
+
+What is the project size?
+├── Solo / <3 months → Minimal separation. Extract data access from business logic.
+│                      No formal interfaces. No layers. Just functions and modules.
+│
+├── 2-5 devs / 3-12 months → Separate presentation, business, data. Interfaces at
+│                             data access boundary for testability. Feature folders.
+│
+├── 5+ devs / multi-team → Enforce vertical modules per domain/feature.
+│                          ArchUnit/dependency-cruiser in CI. Centralize cross-cutting.
+│
+└── Microservices scale → Only split service boundary when deployment independence
+                          is required AND the concern boundary is stable AND you
+                          have observed it change independently at least once.
+```
+
+### Size-Based Heuristics
+
+| Project Size | Team Size | Recommended Separation Depth |
+|-------------|-----------|------------------------------|
+| <5K lines | 1-2 devs | 1-2 layers (business + data access) |
+| 5K-50K lines | 2-10 devs | 3 layers + feature modules |
+| 50K-500K lines | 10-50 devs | Domain modules + enforced boundaries + centralized cross-cutting |
+| >500K lines | 50+ devs | Bounded contexts, separate deployable modules or services |
+
+---
+
+## Implementation Sketch
+
+### Entangled Code (Before)
+
+```
+src/
+  app.js          ← 800 lines: renders HTML, validates input,
+                    queries database, sends email, logs everything
+```
+
+A representative excerpt:
+```javascript
+// app.js — everything in one place
+app.post('/orders', async (req, res) => {
+  console.log(`[${new Date()}] POST /orders from ${req.ip}`);
+  if (!req.body.userId || !req.body.items) {
+    console.log('Validation failed');
+    return res.status(400).json({ error: 'Missing required fields' });
+  }
+  const user = await db.query('SELECT * FROM users WHERE id = ?', [req.body.userId]);
+  if (!user) return res.status(404).json({ error: 'User not found' });
+  const total = req.body.items.reduce((sum, item) => sum + item.price * item.qty, 0);
+  const order = await db.query('INSERT INTO orders ...', [...]);
+  await sendgrid.send({ to: user.email, subject: 'Order confirmed', ... });
+  console.log(`Order ${order.id} created`);
+  res.json({ orderId: order.id, total });
+});
+```
+
+Problems: logging is scattered, validation is inline, database is direct, email is hardcoded to SendGrid. Change any one thing and you touch this function.
+
+### Separated by Horizontal Layers
+
+```
+src/
+  routes/
+    orders.js         ← HTTP: parse request, call service, format response
+  services/
+    orderService.js   ← Business rules: validate, calculate total, orchestrate
+  repositories/
+    orderRepository.js  ← Data access: SQL queries only
+  notifications/
+    emailNotifier.js  ← Notification: email logic, SendGrid coupling here only
+  middleware/
+    logger.js         ← Cross-cutting: all logging centralized here
+    auth.js           ← Cross-cutting: authentication here only
+```
+
+Each file has one reason to change:
+- Routes change when the API contract changes.
+- Service changes when business rules change.
+- Repository changes when the database schema or engine changes.
+- EmailNotifier changes when the notification vendor changes.
+- Logger changes when the logging strategy changes.
+
+### Separated by Vertical Feature Slices
+
+For larger applications where features are the primary unit of change:
+
+```
+src/
+  features/
+    orders/
+      OrderRoute.js       ← HTTP handler for orders
+      OrderService.js     ← Order business rules
+      OrderRepository.js  ← Order data access
+      OrderNotifier.js    ← Order-specific notifications
+      order.test.js       ← All order tests co-located
+    users/
+      UserRoute.js
+      UserService.js
+      UserRepository.js
+      user.test.js
+  shared/
+    middleware/
+      logger.js           ← Cross-cutting: shared across features
+      auth.js
+    db/
+      connection.js       ← Shared infrastructure
+```
+
+Benefit over pure horizontal: a developer working on the orders feature navigates one directory. A new order requirement is implemented in one place. The feature can potentially be extracted to a separate service when it needs to scale independently.
+
+### Cross-Cutting Concern Before and After
+
+**Before (scattered logging):**
+```javascript
+// In UserService.js
+console.log('Creating user...');
+// In OrderService.js
+console.log('Creating order...');
+// In PaymentService.js
+console.log('Processing payment...');
+// 200 more instances across the codebase
+```
+
+**After (centralized via middleware/aspect):**
+```javascript
+// middleware/logger.js — one place
+function loggingMiddleware(req, res, next) {
+  const start = Date.now();
+  res.on('finish', () => {
+    logger.info({ method: req.method, path: req.path,
+                  status: res.statusCode, ms: Date.now() - start });
+  });
+  next();
+}
+
+// All services — no logging code
+class OrderService {
+  async createOrder(data) {
+    // Pure business logic. Logging applied at the middleware layer.
+    return this.orderRepository.save(new Order(data));
+  }
+}
+```
+
+The business logic is now readable without logging noise. The logging strategy can be changed in one file. The logging can be tested independently.
+
+---
+
+## Cross-References
+
+- **coupling-and-cohesion** — SoC and cohesion are complementary: high cohesion within a concern, low coupling between concerns. Coupling is the mechanism; SoC is the goal.
+- **layered-architecture** — The horizontal instantiation of SoC. Covers layer dependencies, anti-corruption layers, and enforcement.
+- **hexagonal-clean-architecture** — Domain-centric SoC. Ports and adapters enforce the boundary between business logic and everything volatile (databases, frameworks, UIs).
+- **domain-driven-design** — Provides the vocabulary for identifying vertical concern boundaries: bounded contexts, aggregates, and domain services map to separable concerns at the business level.
+- **design-principles-solid** — SRP is the class-level expression of SoC. Open/Closed Principle requires stable concern boundaries that can be extended without modification. Dependency Inversion is the mechanism for enforcing concern boundaries at compile time.
+
+---
+
+*Researched: 2026-03-08 | Sources: [Dijkstra, E.W. (1974) "On the role of scientific thought"; Foote & Yoder (1997) "Big Ball of Mud"; Spolsky, J. "The Law of Leaky Abstractions"; Metz, S. "The Wrong Abstraction"; Wikipedia — Separation of Concerns (https://en.wikipedia.org/wiki/Separation_of_concerns); Wikipedia — Aspect-Oriented Programming (https://en.wikipedia.org/wiki/Aspect-oriented_programming); Wikipedia — Cross-cutting concern (https://en.wikipedia.org/wiki/Cross-cutting_concern); Nalexn, A. "Separation of Concerns in Software Design" (https://nalexn.github.io/separation-of-concerns/); Number Analytics "Separation of Concerns in Practice" (https://www.numberanalytics.com/blog/separation-of-concerns-in-practice); arendjr.nl "Post-Architecture: Premature Abstraction Is the Root of All Evil" (https://www.arendjr.nl/blog/2024/07/post-architecture-premature-abstraction-is-the-root-of-all-evil/); Spring Boot Tutorial — SoC (https://www.springboottutorial.com/software-design-seperation-of-concerns-with-examples); Spring Boot Tutorial — AOP (https://www.springboottutorial.com/introduction-to-aspect-oriented-programming-and-cross-cutting-concerns); Jorganxhi, A. "How AOP Solves Cross-Cutting Concerns" (https://ardijorganxhi.medium.com/how-can-aspect-oriented-programming-aop-solve-cross-cutting-concerns-of-your-application-18332c0e2f9a); mortoray.com "The False Abstraction Anti-pattern" (https://mortoray.com/the-false-abstraction-antipattern/); ScienceDirect — Embedded real-time SoC (https://www.sciencedirect.com/article/pii/S1383762114000824)]*