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
Pattern Authoring	How patterns are written and how the library coheres	✅ Required*
Repository Context Directory	Cross-session repo knowledge is lost between sessions and contributors	✅ Recommended
Roadmap and Epic Planning	Medium-term direction is disconnected from independently deliverable work	🧪 Emerging
Infrastructure Layout	Where to put Terraform/IaC	✅ Required*
AWS Resource Tagging	Consistent AWS resource tagging	✅ Required*
AWS Bedrock Inference Profiles	Cost-attributed, tagged Bedrock model invocation	✅ Required*
Sandbox Environments	Safe local development	✅ Required*
Local AWS Sandbox	Emulating AWS services locally with LocalStack	✅ Required*
Git Conventions	Inconsistent git workflows	✅ Required
GitHub Actions	CI/CD setup and patterns	✅ Required
Service Structure	Canonical shape of an Ontopix backend service	✅ 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: Pattern Authoring (when authoring or editing a pattern in this handbook), Infrastructure Layout (for repos with infrastructure), AWS Tagging (for repos provisioning AWS resources), Bedrock Inference Profiles (for services invoking AWS Bedrock), Sandbox (for application repos), Local AWS Sandbox (for repos with AWS-dependent local sandboxes), Service Structure (for backend services), 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
Python Project Structure	Inconsistent Python project layout and tooling	✅ Active
Python Test Organization	Unstructured, hard-to-navigate Python test suites	✅ Active
Lambda Deploy	Standard Lambda code deployment from CI/CD	✅ Active
Rich Search on AWS Amplify	Sophisticated search/filtering when DynamoDB alone is not enough	🧪 Emerging
LLM Requests	Fragile, expensive, or unparseable LLM invocations	✅ 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

Authoring Patterns

How a pattern is written — its anatomy, classification, cross-linking, and how the library evolves — is defined by a single pattern: Pattern Authoring. It is the source of truth and this index does not restate it. In short:

Promote a solution to a pattern once you have solved the same problem 3+ times, or to set a deliberate organizational standard.
Follow the canonical anatomy — front-matter, the Status/Type header block, and the fixed section order. See Anatomy of a Pattern.
Evolve patterns in place. No -v2 files, no archive copies — delete superseded content; git history is the archive. See Evolution & Coherence.
Register every new pattern in this index.

Org-level patterns change the standard for every Ontopix repository — review the escalation rules in AGENTS.md before merging.

Related: Principles | Decisions | Templates