Patterns

Engineering Patterns

Index of all patterns available in the Ontopix Engineering Handbook.

Production

For understanding the difference between Principles and Patterns, see the main README.

Organizational Patterns (Mandatory)

Pattern	Problem Solved	Status
Repository Structure	Inconsistent file organization	✅ Required
AI Agent Entrypoint	Agents don't know where to start	✅ Required
Taskfile Contract	Inconsistent operational interfaces	✅ Required
Infrastructure Layout	Where to put Terraform/IaC	✅ Required*
AWS Resource Tagging	Consistent AWS resource tagging	✅ Required*
Sandbox Environments	Safe local development	✅ Required*
Git Conventions	Inconsistent git workflows	✅ Required
GitHub Actions	CI/CD setup and patterns	✅ Required
CodeArtifact + GitHub Actions	Secure package management from CI/CD	✅ Recommended*
ECR + GitHub Actions	Container image build and push from CI/CD	✅ Recommended*

*Required if applicable: Infrastructure Layout (for repos with infrastructure), AWS Tagging (for repos provisioning AWS resources), Sandbox (for application repos), CodeArtifact (for repos publishing/consuming private packages), ECR (for repos deploying container images)

Technical Patterns (Optional but Recommended)

Pattern	Problem Solved	Status
Python Module Naming	Public vs internal API boundaries	✅ Active
Lambda Deploy	Standard Lambda code deployment from CI/CD	✅ Active
Authentication	User identity verification	🚧 Coming soon
Caching	Performance optimization	🚧 Coming soon
Rate Limiting	API protection	🚧 Coming soon
Error Handling	Consistent error responses	🚧 Coming soon

Pattern Template

When creating a new pattern, follow this structure:

# Pattern: [Name]

## Problem
[What problem does this solve?]

## Context
[When should you use this? When should you NOT?]

## Solution
[Detailed explanation of the pattern]

## Structure
[Code examples, file layouts, diagrams]

## Implementation
[Step-by-step guide]

## Applies Principles
[Which core principles does this embody?]

## Consequences
[Trade-offs, benefits, drawbacks]

## Examples
[Real-world usage from Ontopix repositories]

## Variations
[Different contexts or approaches]

## Related Patterns
[Links to complementary patterns]

## References
[ADRs, external resources]

Contributing Patterns

When to Create a Pattern

Create a pattern when you've solved the same problem 3+ times across different projects.

Good candidates:

✅ Recurring problems with proven solutions
✅ Common mistakes that need guidance
✅ Complex implementations that benefit from templates
✅ Solutions that apply across multiple projects

Not good candidates:

❌ One-off solutions
❌ Highly project-specific implementations
❌ Unproven or experimental approaches
❌ Simple problems with obvious solutions

Contribution Process

Write the pattern - Follow the structure above
Provide examples - Real code from Ontopix projects, not pseudo-code
Document trade-offs - Be honest about limitations
Link to principles - Show which principles this embodies
Create PR - Get review from engineering leadership
Update this index - Add your pattern to the appropriate section

Pattern Evolution

Patterns are living documents that evolve:

Versioning

When a pattern needs significant changes:

Keep old version for reference
Create new version with suffix: pattern-name-v2.md
Link between versions
Deprecate old version with migration guide

Deprecation

Mark pattern as deprecated in this index
Add deprecation notice to pattern file
Provide migration path to new pattern
Set sunset date (typically 6 months)
Remove after sunset date

Related: Principles | Decisions | Templates