Ontopix Engineering Handbook

This repository defines how we work, how we solve problems, and why we made specific architectural choices.

📽️ Quick Overview

Want a visual summary? Watch this video walkthrough that covers the essentials of our engineering handbook:

https://github.com/user-attachments/assets/01bab484-f4a7-40c0-8f08-f3b4e78f0265

What This Is

The Engineering Handbook is the single source of truth for:

• Principles — Core values and beliefs guiding ALL engineering decisions
• Patterns — Proven, reusable solutions to recurring problems
• Decisions — Architectural Decision Records (ADRs) documenting why we made specific choices
• Templates — Ready-to-use starting points for new work
• Resources — External tools, services, and platforms catalog

This handbook is designed to work equally well for:

• Humans — Engineers onboarding, making decisions, or resolving ambiguity
• AI Agents — Claude Code, Cursor, and other coding assistants needing clear operational context

Principles vs Patterns

Understanding the difference between Principles and Patterns is critical to using this handbook effectively.

Quick Reference

Principles (Abstract Philosophy)

What: Core values and beliefs that guide ALL engineering decisions at Ontopix.

Characteristics:

• Abstract and philosophical
• Apply universally across all contexts
• Rarely change (years between updates)
• Not prescriptive about implementation
• Guide decision-making

Examples:

• SOLID principles (Single Responsibility, Open/Closed, etc.)
• DRY (Don't Repeat Yourself)
• KISS (Keep It Simple, Stupid)
• Security by design
• Automation over manual work

Think of principles as: "Our engineering philosophy and values"

Patterns (Concrete Solutions)

What: Proven, reusable solutions to recurring problems.

Characteristics:

• Concrete and actionable
• Solve specific problems
• Evolve as technology changes
• Prescriptive about implementation
• Can be directly applied

Examples:

• Use AGENTS.md as AI agent entrypoint
• Use Taskfile for operational contracts
• Place infrastructure in .infra/ directory
• JWT tokens for authentication

Think of patterns as: "How we implement our philosophy"

The Relationship

Principles (Why)
    ↓
Patterns (What & How)
    ↓
Implementation (Actual Code)

Example Flow:

1. Principle: "Automation over manual work"
2. Pattern: "Use Taskfile for all repository operations"
3. Implementation: Taskfile.yaml in specific repository

Decision Flow

When facing an engineering decision:

┌─────────────────────┐
│   New Challenge     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Check Principles    │  ← Does this align with our values?
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ Find/Create Pattern │  ← How do we solve this?
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   Implement         │  ← Write actual code
└─────────────────────┘

Principles

Our Core Engineering Principles define the abstract values that guide all our work:

1. Simplicity First — YAGNI, KISS, Occam's Razor
2. Code Quality & Maintainability — Write for comprehension by humans and AI agents
3. Security by Design — Defense in depth, Zero Trust, least privilege
4. Automation Over Manual Work — If you do it twice, automate it
5. Evidence Over Assumptions — Measure, don't guess
6. Human-AI Collaboration — AI agents as first-class citizens in development
7. Pragmatism Over Dogma — Context matters, use judgment
8. Ownership & Responsibility — You build it, you run it
9. Long-Term Thinking — Technical debt is real debt
10. Continuous Learning & Improvement — Stay curious, iterate on processes

👉 Read Full Principles

Patterns

Proven solutions to recurring problems at Ontopix.

Organizational Patterns (Mandatory)

These patterns define how we organize work and apply to ALL repositories:

*Required if applicable: Infrastructure Layout (for repos with infrastructure), Sandbox (for application repos)

Technical Patterns (Optional but Recommended)

These patterns define how we solve specific technical problems:

Technical patterns will be extracted from production implementations and added incrementally.

Quick Start

For New Engineers

Week 1: Understand the philosophy

1. Read Core Engineering Principles
2. Understand Principles vs Patterns (above)
3. Review the Decision Flow

Week 2: Learn the patterns 4. Read Organizational Patterns 5. Review Templates 6. Set up your first repository

Week 3: Understand the context 7. Browse ADRs to understand "why" 8. See how principles inform patterns

For Starting a New Repository

Minimum Viable Repository (5 required files):

my-new-repo/
├─ README.md          ← Human documentation
├─ AGENTS.md          ← AI agent entrypoint
├─ Taskfile.yaml      ← Operational interface
├─ .editorconfig      ← Editor consistency
└─ CODEOWNERS         ← Ownership definition

Setup Steps:

1. Copy templates from templates/
2. Follow Repository Structure Pattern
3. Create AGENTS.md from template
4. Define operations in Taskfile.yaml
5. If deploying infrastructure, follow Infrastructure Layout
6. If application, implement Sandbox

👉 See Templates

For AI Agents

When you enter an Ontopix repository:

1. Read AGENTS.md first — It is your mandatory entrypoint
2. Check for patterns — AGENTS.md references relevant patterns
3. Use Taskfile for operations — Never invoke tools directly
4. Surface pattern violations — Stop and ask if you detect discrepancies
5. Request human approval — For architecture, infrastructure, or contract changes

Decisions

Architectural Decision Records (ADRs) document why we made specific choices. ADRs are immutable historical records.

Available ADRs

👉 Browse All ADRs

Templates

Ready-to-use starting points for creating new repositories:

👉 See All Templates

Resources

Centralized catalog of external resources, tools, and service accounts used across Ontopix engineering.

Quick Access

🔐 Important Security Note

Resources documentation NEVER includes credentials. It documents:

• Where to find credentials (password manager, vault)
• Who manages access (team or person)
• How to request access (Slack channel, contact)

👉 View All Resources

How to Use This Handbook

When Should I Consult What?

Starting a project? → Check Principles → Apply Organizational Patterns → Use Templates

Solving a specific problem? → Browse Technical Patterns → Check related ADRs

Making an architectural decision? → Review Principles → Check existing ADRs → Create new ADR if needed

Need access to external services? → Check Resources for URLs, access info, and credential locations

Onboarding AI agents? → Point them to AGENTS.md pattern

Understanding "why"? → Read ADRs for historical context

Evolution and Contributions

Proposing Changes

To Principles (rare):

1. Create issue explaining why principle should change
2. Discuss with engineering leadership
3. Update principle documentation
4. Communicate organization-wide

To Patterns (common):

1. Identify problem with current pattern
2. Propose solution with evidence
3. Create PR with changes
4. Get review from engineering team
5. Update related ADRs if needed

To Add New Pattern:

1. Verify problem recurs 3+ times
2. Document solution following pattern structure
3. Provide real production examples
4. Create PR for review
5. Pattern becomes official after merge

Creating ADRs

When making architectural decisions:

1. Use ADR template
2. Document context, decision, alternatives, consequences
3. Place in decisions/ directory
4. Link from relevant patterns
5. ADRs are immutable after creation (history doesn't change)

FAQ

Q: What's the difference between principles and patterns? A: Principles are abstract values (SOLID, DRY). Patterns are concrete solutions (AGENTS.md, Taskfile). See Principles vs Patterns.

Q: Are all patterns mandatory? A: Organizational patterns are mandatory for all repos. Technical patterns are optional but recommended for specific problems.

Q: Can I deviate from patterns? A: Only with explicit justification documented in AGENTS.md or an ADR. Engineering leadership must approve.

Q: Where do I find implementation examples? A: Check Templates for starting points and pattern documentation for production examples.

Q: How do I know which pattern to use? A: Read AGENTS.md in the repository - it references relevant patterns for that specific project.

Q: What if a pattern conflicts with language conventions? A: Language conventions win, but document the exception in AGENTS.md.

Getting Help

• Have a question? → Create an issue
• Found a bug? → Create an issue
• Want to contribute? → Create a PR
• Need clarification? → Ask in engineering Slack

Remember: These are guidelines informed by experience, not rigid rules. Use judgment. Question dogma. Build great things.