How WorkWeave Router Enforces Unidirectional Imports: Layered Architecture Deep Dive

WorkWeave Router enforces unidirectional imports through a strict concentric ring architecture where packages may only import toward the core, validated by custom golangci-lint rules and mandatory code review against the AGENTS.md specification.

WorkWeave Router implements a rigid architectural boundary to maintain clean separation of concerns through unidirectional imports. This Go-based routing system organizes code into concentric rings, ensuring that business logic remains pure while infrastructure dependencies flow inward only. Understanding these enforcement mechanisms reveals how the codebase prevents circular dependencies and maintains compile-time safety across all layers.

The Layered Architecture Model

According to the project's design document AGENTS.md, WorkWeave Router adopts a concentric ring architecture where imports flow inward only【AGENTS.md#L20-L24】. This architectural invariant means packages may import any module closer to the core, but never packages farther out toward the presentation or adapter layers.

The "Hard rules" section explicitly defines these boundaries: inner-ring packages must not import presentation or adapter packages, adapters may only import inner-ring packages and never each other, and the composition root remains the sole location for concrete adapter wiring【AGENTS.md#L24-L28】.

Enforcement Mechanisms

The repository maintains these architectural invariants through automated tooling and manual review processes that validate every change against the inward-only rule.

Static Analysis with golangci-lint

The CI pipeline runs custom linters configured in .golangci.yml that detect layer violations during build time. When a developer attempts to import an outer-ring package from an inner-ring module, the linter generates errors like "layer violation: internal/router may not import internal/api" and blocks the pull request from merging.

Code Review and AGENTS.md Compliance

Human reviewers use a layer-aware checklist to verify import direction, particularly when adding new packages such as internal/providers/openaicompat or refactoring existing code in internal/api/openai. The AGENTS.md file serves as the canonical source of truth, with its diagram and hard-rule descriptions providing the definitive reference for allowed dependencies.

Package Structure and Import Rules

The codebase organizes functionality into three distinct categories with strict import constraints that preserve the unidirectional flow.

Inner-Ring Business Logic

Packages like internal/router, internal/translate, and internal/timing contain pure business logic without I/O dependencies. These modules may import each other freely but never reference concrete adapters such as internal/postgres or internal/api/openai.

Adapter Packages

Infrastructure implementations in internal/api/*, internal/postgres, and internal/providers/* import inner-ring packages to access pure types, but cannot import sibling adapters. This ensures the API layer depends on business logic, not vice versa, maintaining the dependency inversion principle.

The Composition Root

The file cmd/router/main.go serves as the exclusive composition root where concrete implementations are instantiated and wired together. No other package performs this wiring, maintaining the rule that implementations depend on abstractions inward, not outward.

Practical Code Examples

The following examples demonstrate valid and invalid import patterns within the WorkWeave Router codebase.

Valid inner-ring imports maintain direction toward the core:

// internal/router/planner/planner.go
package planner

import (
    "workweave/router/internal/router"   // allowed: same or inner layer
    "workweave/router/internal/timing"   // allowed: inner-ring utility
)

Attempting to import an adapter from business logic triggers enforcement:

// internal/router/planner/planner.go
package planner

import (
    "workweave/router/internal/api/openai" // ❌ forbidden: adapter layer
)

When the above violation is introduced, the CI linter flags the layer breach and prevents merge until the import is relocated to an appropriate adapter handler that imports internal/router/planner instead.

Summary

• Concentric Ring Architecture: WorkWeave Router organizes code into layers where dependencies flow strictly inward toward the core business logic【AGENTS.md#L20-L24】.
• Automated Enforcement: Custom golangci-lint rules in the CI pipeline detect and block import violations before code reaches production.
• Manual Verification: Reviewers consult AGENTS.md to validate that new packages respect the inward-only import direction and hard rules【AGENTS.md#L24-L28】.
• Composition Root Isolation: Only cmd/router/main.go may wire concrete adapters, preventing implicit dependencies throughout packages like internal/router and internal/translate.
• Pure Business Logic: Inner-ring packages remain free of I/O dependencies, ensuring testability and compile-time safety without hidden side effects.

Frequently Asked Questions

What happens if I accidentally import an outer-ring package from business logic?

The CI pipeline will reject your pull request with a layer violation error. The custom linter detects the breach and reports something like "layer violation: internal/router may not import internal/api", requiring you to move the import to an appropriate adapter package or refactor the dependency direction.

Can adapter packages import other adapters?

No. According to the hard rules in AGENTS.md, adapters may only import inner-ring packages and never each other【AGENTS.md#L24-L28】. If adapters in internal/api/openai and internal/providers/openaicompat need to communicate, they must do so through inner-ring abstractions defined in packages like internal/router or internal/timing.

Where should I instantiate concrete implementations like database connections?

All concrete implementation wiring occurs exclusively in cmd/router/main.go. This composition root is the only location allowed to create Postgres repositories, provider clients, or API handlers and connect them to business logic, ensuring the rest of the codebase remains agnostic to specific infrastructure details.

How does the ring architecture improve code maintainability?

By enforcing unidirectional imports, WorkWeave Router guarantees that business logic packages like internal/router/planner never depend on I/O-heavy adapter packages. This eliminates hidden side effects in pure functions, enables faster unit testing without mocks, and prevents circular dependency cycles that slow compilation and complicate refactoring.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}