ADR-0001: Pattern Library Organization

Status: Accepted

Date: 2025-12-16

Deciders: Engineering Leadership

Context

Ontopix needs to organize engineering knowledge in a way that:

• Scales as the organization grows
• Reduces duplication across repositories
• Works well for both humans and AI agents
• Separates stable principles from evolving patterns
• Enables pattern discovery and reuse

We considered organizing all engineering knowledge in a single repository versus separating concerns into multiple layers.

Decision

We will organize engineering knowledge into three distinct levels:

Level 0: Engineering Handbook (this repository)

Purpose: Define organizational principles, contracts, and conventions

Contains:

• Core engineering principles (agents, sandbox, taskfile, infrastructure)
• Mandatory contracts (AGENTS.md, Taskfile.yaml)
• Repository templates
• Long-lived architectural decisions

Characteristics:

• Slow-changing
• Applies to all repositories
• Defines "how we work"

Level 1: Engineering Patterns (separate repository)

Purpose: Document reusable technical solutions to recurring problems

Contains:

• Implementation patterns (authentication flows, rate limiting, caching strategies)
• Terraform modules
• Code templates
• Framework-specific patterns
• Best practices for specific technologies

Characteristics:

• Medium-changing
• Referenced by repositories
• Defines "how we solve problems"

Level 2: Repository Documentation

Purpose: Explain specific codebases and their context

Contains:

• Repository-specific README
• Architecture for this specific system
• Local patterns unique to this codebase
• API documentation

Characteristics:

• Fast-changing
• Local to repository
• Defines "how this system works"

Rationale

Why Separate Patterns from Handbook?

Different Lifecycles:

• Handbook: Principles change rarely (months/years)
• Patterns: Evolve frequently as technology changes (weeks/months)
• Separation prevents handbook churn

Different Audiences:

• Handbook: Everyone, always (onboarding, decision-making)
• Patterns: Specific problems, as needed (implementing features)

Different Usage:

• Handbook: Read to understand "how we work"
• Patterns: Reference when solving specific problems

Scalability:

• Patterns grow with technology diversity
• Handbook remains focused and concise
• Separation prevents pattern library from overwhelming core principles

Why Three Levels?

Avoids Duplication:

• Patterns live in one place (Level 1)
• Repositories reference patterns, don't duplicate them
• Changes to patterns propagate automatically

Clear Ownership:

• Level 0: Engineering leadership
• Level 1: Pattern authors and maintainers
• Level 2: Repository maintainers

Discoverability:

• Patterns grouped by domain in one repository
• Easier to browse and search
• Cross-repository pattern reuse is visible

Consequences

Positive

Reduced Cognitive Load:

• Engineers know where to look for what
• Handbook stays focused and readable
• Patterns organized by problem domain

Better Maintenance:

• Patterns evolve independently
• Handbook principles remain stable
• Clear ownership boundaries

Improved Discoverability:

• Dedicated pattern library is browsable
• Search focused on patterns when needed
• Cross-repository reuse is visible

AI Agent Clarity:

• Agents reference patterns by URL
• Clear hierarchy of information
• Reduced token usage (reference, don't duplicate)

Negative

Multiple Repositories:

• Need to maintain multiple repos
• Cross-repository links can break
• Requires discipline to avoid duplication

Navigation Overhead:

• Engineers need to know which level to check
• Additional repository to learn
• Links between levels must be maintained

Mitigations

Clear Documentation:

• Handbook explains three-level model prominently
• Each level clearly defines its scope
• Templates include pattern references

Stable URLs:

• Patterns use versioned URLs when stability matters
• Breaking changes communicated clearly
• Pattern deprecation process defined

Tooling:

• Pattern library has search and browse capabilities
• AGENTS.md templates include pattern reference sections
• Automated link checking (future)

Alternatives Considered

Alternative 1: Single Monolithic Handbook

Rejected because:

• Would become unwieldy as patterns grow
• Different lifecycles cause maintenance burden
• Hard to navigate for specific problems
• Agents would need to read entire handbook

Alternative 2: Patterns in Individual Repositories

Rejected because:

• Leads to duplication and divergence
• Hard to discover existing patterns
• No central place to learn Ontopix patterns
• Inconsistency across repositories

Alternative 3: Wiki or Confluence

Rejected because:

• Not version-controlled
• Not easily referenced by agents
• Tends to become stale
• Harder to enforce standards

References

• Repository Structure Pattern
• AI Agent Entrypoint Pattern
• All Patterns

Success Criteria

This decision is successful if:

• Engineers can quickly find relevant patterns
• Repositories consistently reference patterns instead of duplicating them
• Handbook remains focused and readable
• Pattern library grows without overwhelming handbook
• AI agents effectively reference patterns without duplication