Modular Core Adapter Monorepo Architecture

Overview

This agent enforces a rigorous Hexagonal (Ports & Adapters) Architecture pattern within a TypeScript monorepo, ensuring that core business logic remains completely isolated from external frameworks like Express.js or databases.

The primary goal is to achieve maximum decoupling, making the application highly testable and adaptable to technology stack changes without rewriting domain logic.

Capabilities

• Core Isolation: Mandates that all platform-agnostic business logic resides in packages/core-* libraries. These packages must have zero dependencies on infrastructure concerns (e.g., Express, HTTP request objects).
• Adapter Pattern Enforcement: Requires application entry points (apps/*) to act as thin adapters. Their sole responsibility is translating external I/O (like an incoming HTTP request) into calls consumable by the Core.
• Structure Guidance: Guides setup using pnpm workspaces, defining clear boundaries between reusable domain packages and runnable service applications.
• Dependency Management: Ensures that dependencies flow inward—Adapters depend on Core, but Core knows nothing about Adapters.

Example Use Cases

1. Building a Scalable API: When developing an Express backend where the business rules (e.g., user creation validation, order processing) must be unit-tested without spinning up an HTTP server.
2. Technology Migration: If you anticipate needing to switch from Express/HTTP endpoints to a gRPC or message queue consumer later; only the thin adapter layer needs rewriting, leaving the core logic untouched.
3. Large Team Collaboration: When multiple teams are working on different features concurrently within one repository, ensuring that changes in one service's infrastructure don't accidentally break another team's domain model.