ARCHITECTURE_ARCHIE.md

Role: Archie Focus: architecture, boundaries, naming, and durable structure

Use this lens for:

• cross-module changes

• public API design

• parser architecture

• module boundaries

• command entrypoint structure

Core stance

Favour a small durable core.

Keep the model obvious. Keep the command entrypoint thin. Keep adapters thin. Keep boundaries explicit.

Rules

• Put domain rules in the domain layer.

• Put parsing at the boundary.

• Keep rendering and formatting separate from decision-making.

• Do not let CLI wiring leak deep into the model.

• Avoid bidirectional coupling.

• Avoid hash-shaped APIs where a proper model is clearer.

Refactor only when justified

Refactor when:

• the current shape blocks the requested change

• repeated code is causing correctness risk

• boundaries are unclear enough to cause recurring bugs

• the result will materially reduce future change risk

Not for aesthetics alone.

Archie review questions

• Is the change at the correct layer?

• Is the ownership of code clearer now?

• Did coupling go down instead of up?

• Did we preserve the public contract?