wardline CLAUDE.md

Wardline — Engineering Conventions

Wardline is an open source control-plane proxy that sits between AI agents and everything they call (MCP servers, LLM providers, other agents) — enforcing identity, policy, budget, and audit. Go, Apache 2.0.

These conventions apply to all code in this repo. Follow them exactly; they override default behavior.

Architecture: Clean Architecture, dependency rule inward

Four layers, dependencies point one direction only — outer depends on inner, never the reverse:

domain        → entities + interfaces only. No I/O, no frameworks, no imports outside stdlib.
usecase       → business logic (policy evaluation, budget checks, audit decisions).
               Depends on domain interfaces, never on adapters or infra directly.
adapter       → translates between usecase and the outside world (HTTP handlers,
               YAML/OPA loaders, log writers). Implements domain interfaces.
infra         → frameworks, network, filesystem, third-party SDKs. Wired at the
               outermost edge only (cmd/wardline/main.go).

A file in domain/ or usecase/ that imports net/http, a YAML library, or any adapter package is a violation — stop and fix the dependency direction, don't add an exception.

SOLID, applied concretely

• Single Responsibility — one package, one reason to change. If a package handles both policy matching and audit logging, split it.
• Open/Closed (the one that matters most here) — every pluggable engine (policy backend, identity issuer, budget meter) is a domain-defined interface, and adding a new backend means adding a new adapter, never editing the usecase that consumes it. Concrete example: policy.Engine interface has an OPA/Rego adapter today; Cedar arrives later as a second adapter, zero changes to usecase/policy_eval.go.
• Liskov — any implementation of a domain interface must be swappable without the caller changing behavior/assumptions. If a new policy.Engine impl needs the usecase to special-case it, the interface is wrong — fix the interface, not the caller.
• Interface Segregation — small, single-purpose interfaces (policy.Evaluator, audit.Writer, budget.Meter) over one large Engine god-interface. Consumers depend only on the methods they call.
• Dependency Inversion — usecases accept interfaces via constructor injection; concrete adapters are wired only in cmd/wardline/main.go. Never import an adapter package from usecase/.