Skip to content

Architecture Reference

Version: 0.2.6 Last Updated: 2025-12-02

Overview

This guide serves as the entry point to the particula architecture documentation. It provides references to detailed architectural resources and guidance on when to consult each.

Architecture Documentation Structure

The architecture documentation is organized as follows:

docs/Agent/architecture/
├── architecture_guide.md           # Detailed architectural documentation
├── architecture_outline.md         # High-level system overview
└── decisions/                      # Architecture Decision Records (ADRs)
    ├── README.md                   # ADR index and guidelines
    ├── template.md                 # Template for new ADRs
    └── template.md                 # Template for creating new ADRs

Quick Navigation

For New Contributors

Start here to understand the system:

  1. Architecture Outline: Quick overview of components and structure
  2. Architecture Guide: Detailed patterns and principles
  3. Decision Records: Historical context for key decisions

For Implementing Features

When implementing new features, consult:

  1. Architecture Guide: Ensure your design follows established patterns
  2. Architecture Outline: Understand module boundaries
  3. Code Style Guide: Follow coding conventions

For Making Architectural Decisions

When making significant architectural decisions:

  1. Review Architecture Guide for alignment with principles
  2. Review Decision Records for related past decisions
  3. Create a new ADR to document your decision
  4. Request architectural review using /architecture_review

For Code Reviews

When reviewing code for architectural concerns:

  1. Check alignment with Architectural Principles
  2. Verify adherence to Design Patterns
  3. Ensure avoidance of Anti-Patterns
  4. Reference Review Guide for review criteria

Primary Documentation

Architecture Guide

The comprehensive architectural documentation covering:

  • Architectural Principles: Core design principles guiding the system
  • System Architecture: High-level structure and component organization
  • Design Patterns: Standard patterns used throughout the codebase
  • Anti-Patterns: Approaches to avoid
  • Data Flow: How data moves through the system
  • Error Handling: Exception hierarchy and error strategies
  • Testing Architecture: Test organization and strategies
  • Performance & Security: Key considerations

When to Read: - Designing new modules or major features - Understanding system-wide patterns - Making architectural decisions - Conducting architecture reviews

Architecture Outline

A high-level overview providing:

  • System Overview: What the system does
  • Core Components: Main building blocks and their responsibilities
  • Module Structure: Directory organization
  • Technology Stack: Languages, frameworks, and key dependencies
  • Quick Reference: Design principles and common patterns
  • Extension Points: Areas designed for customization

When to Read: - First exploring the codebase - Understanding component responsibilities - Finding where to add new features - Getting oriented quickly

Architecture Decision Records (ADRs)

Historical record of significant architectural decisions:

  • Context: Why the decision was needed
  • Decision: What was chosen
  • Alternatives: What else was considered
  • Consequences: Trade-offs and outcomes

When to Read: - Understanding why things work the way they do - Reconsidering past decisions in new contexts - Learning from past trade-offs - Creating similar decisions

When to Create: - Making significant architectural changes - Choosing technologies or frameworks - Establishing new patterns - Changing system boundaries

See ADR README for guidelines on creating ADRs.

Integration with ADW

ADW commands reference these architecture documents to:

  • Understand Structure: Know where code belongs
  • Follow Patterns: Use established approaches
  • Respect Boundaries: Maintain module separation
  • Make Decisions: Create ADRs for significant changes

Relevant ADW Commands

  • /architecture_review: Review code for architectural consistency
  • /feature: Plan features using architectural patterns
  • /implement: Implement following architectural guidelines
  • /review: Check adherence to architecture

Maintaining Architecture Documentation

When to Update

Update architecture documentation when:

  • Adding Major Features: Update guide and outline with new patterns
  • Changing Module Structure: Update outline with new organization
  • Making Architectural Decisions: Create ADR, update guide
  • Deprecating Components: Update guide, create deprecation ADR
  • Introducing New Patterns: Add to design patterns section

How to Update

  1. Make Changes: Update relevant documentation files
  2. Create ADR: For significant decisions, create an ADR in decisions/
  3. Update Index: Add new ADRs to decisions/README.md
  4. Cross-Reference: Link related documents
  5. Review: Get architecture review before finalizing

Review Process

Architecture documentation changes should be reviewed by: - Technical leads - Senior engineers familiar with the system - Anyone who will be affected by the changes

Use /architecture_review to request review.

Questions?

If you're unsure about: - Where something belongs: Check Architecture Outline - What pattern to use: Check Architecture Guide - Why something was done: Check Decision Records - Whether to create an ADR: Check ADR Guidelines

When in doubt, ask for an architecture review or consult with technical leads.