Skip to content

ARCHITECTURE_GUARDRAILS.md

Latest commit

 

History

History
96 lines (69 loc) · 2.88 KB

ARCHITECTURE_GUARDRAILS.md

File metadata and controls

96 lines (69 loc) · 2.88 KB
Raw

Architecture Guardrails

Use these rules to keep a POC easy for engineers to take over. The canonical architecture evidence belongs in a completed handoff file based on docs/templates/ENGINEER_HANDOFF.md.

Architecture Promise

A POC is architected well enough for review when a fresh engineer can identify:

  • Entry points.
  • Layer boundaries.
  • Data ownership.
  • External dependencies.
  • Typed input/output contracts.
  • Known exceptions and risks.

Required Artifacts

For handoff-bound POCs, maintain:

  • AGENTS.md or equivalent repository map.
  • docs/ARCHITECTURE.md with the project-specific layer map.
  • Design docs in docs/designs/<feature>/ before implementation.
  • Architecture boundary table.
  • Data model notes for persisted, session-only, and derived data.
  • ADRs or a decision log for major choices.
  • Handoff evidence in a completed engineer handoff packet.

Layer Boundaries

Keep boundary layers thin:

  • API/CLI handles request parsing and response formatting.
  • Services own business logic and orchestration.
  • Models define typed domain objects.
  • Infrastructure owns database and external API access.
  • Foundation owns config, logging, and security utilities.

Lower layers must not import from upper layers. Customize and keep tests/test_architecture.py aligned with the project structure.

Typed Boundaries

Parse external data at the boundary:

  • API requests and responses.
  • LLM outputs.
  • Config and env vars.
  • Database rows.
  • External API responses.
  • Tool-call payloads.

Avoid raw dict blobs across layers. If a dictionary crosses more than one function or layer, replace it with a dataclass or Pydantic model.

Size And Shape

Review and split when:

  • A source file approaches 500 lines.
  • A function does validation, business logic, persistence, and presentation.
  • A class has unrelated responsibilities.
  • A PR mixes feature work, refactors, formatting, generated files, and cleanup.

Use docs/VIBE_CODING_SMELLS.md for plain-language examples, especially god objects, mega files, hidden global state, premature abstractions, and unreviewable changes.

Logging And Errors

Required:

  • Use logger = logging.getLogger(__name__).
  • Log safe summaries, not full request bodies, prompts, secrets, or PII.
  • Include exc_info=True on warning/error logs that handle exceptions.
  • Return user-safe errors that do not leak internals.

Handoff Evidence

In the completed engineer handoff packet, record:

  • Architecture summary.
  • Entry points.
  • Directory or module map.
  • Data model.
  • Persisted, session-only, and derived data.
  • External boundaries and typed inputs/outputs.
  • Rollback/delete instructions, if relevant.

Related Docs

  • docs/ARCHITECTURE.md — Project layer map
  • docs/CONVENTIONS.md — Coding standards
  • docs/VIBE_CODING_SMELLS.md — Plain-language design smells
  • docs/templates/ENGINEER_HANDOFF.md — Template for canonical architecture evidence