Core Architectural Patterns in LoopX: A Capability‑First, Extension‑Driven Design

LoopX implements a capability‑first, extension‑driven architecture that cleanly separates core product logic from optional add‑ons through bounded contexts, layered control‑plane/runtime separation, and projection‑driven state management.

LoopX is an open‑source AI platform built for extensibility and maintainability. Its codebase follows disciplined architectural patterns that enable third‑party contributions without core modifications. This article examines the seven primary patterns that define LoopX's structure, with references to actual source files and implementation details from the huangruiteng/loopx repository.

---

Understanding LoopX Architectural Patterns

LoopX's design philosophy centers on strong encapsulation and loose coupling. Rather than monolithic modules, functionality decomposes into self-contained units with explicit contracts, lifecycle management, and isolated test suites.

The architecture draws from domain‑driven design, event‑sourcing, and plugin‑system patterns—adapted for an AI‑centric control plane that orchestrates agents, benchmarks, and automated workflows.

---

1. Capability‑Oriented Design

In LoopX, capabilities are the fundamental unit of public‑facing functionality. Each capability owns its contract, validation rules, and runtime behavior.

• Location: loopx/capabilities/ directory
• Structure: Each capability contains contract/, models/, and test files
• Registration: Capabilities register via loopx/capability_registry

Capabilitites are not plugins—they are core, permanent features with strict contracts. The folder hierarchy itself documents the system's functional domain.

# loopx/capabilities/example_capability/__init__.py

from .contract import ExampleContract

def register():
    from loopx.capability_registry import register_capability
    register_capability("example", ExampleContract)

The capability registry enforces schema validation and lifecycle hooks, ensuring that no capability can destabilize others during initialization or teardown.

---

2. Extension System for Optional Add‑Ons

Where capabilities define core features, extensions provide optional, swappable implementations. The extension system lives in loopx/extensions/ and uses a lightweight plugin registry.

Extensions include:

• Providers: External service integrations
• Adapters: Interface implementations for specific environments
• Plugins: Third‑party feature additions

# loopx/extensions/__init__.py

def load_extension(name: str):
    """Load an extension by name without modifying core code."""
    module = importlib.import_module(f"loopx.extensions.{name}")
    module.register()

This pattern achieves binary substitutability: extensions compile and test independently, then load at runtime. Core modules remain unaware of extension specifics—only the registry interface.

---

3. Layered Control‑Plane / Runtime Separation

LoopX strictly divides orchestration from execution:

Layer	Responsibility	Key Modules
Control Plane	Planning, quota enforcement, status tracking, todo projection	loopx/control_plane/
Runtime	Agent execution, benchmark running, worker management	loopx/runtime/

This separation prevents execution failures from corrupting orchestration state. The control plane maintains projections and issues commands; the runtime reports outcomes without direct state mutation.

For example, quota enforcement happens entirely in the control plane. The runtime receives pre‑validated execution tokens and cannot bypass limits even if compromised.

---

4. Domain‑Driven Bounded Contexts

Each capability and extension forms a bounded context with:

• Encapsulated data models (models/)
• Explicit contracts (contract/)
• State machine definitions
• Isolated test suites (e.g., tests/test_<capability>_runtime.py)

This pattern eliminates implicit dependencies. Cross‑context communication occurs only through:

• Published language (shared contract types)
• Domain events (async, decoupled)
• The capability registry (synchronous, controlled)

The test isolation is strict: a capability's tests mock all external contexts, ensuring regressions stay contained.

---

5. Projection‑Driven Todo System

LoopX stores state as immutable projections—derived views computed from event streams. The Todo system consumes these projections rather than direct state.

from loopx.projection import get_projection
from loopx.todo import Todo

proj = get_projection("agent_state")
if proj.needs_review:
    Todo.create(kind="review", payload=proj.id)

Benefits of this pattern:

• Auditability: Every Todo has a traceable lineage to source events
• Observability: Projections expose system state without exposing internals
• Replay safety: Projections rebuild deterministically from event logs

The projection layer in loopx/projection/ handles schema versioning and migration, while loopx/todo/ manages prioritization, assignment, and completion workflows.

---

6. Self‑Repair / Self‑Healing Loops

LoopX includes autonomous maintenance through the loopx-self-repair skill in loopx/skills/loopx-self-repair/. This component:

1. Monitors test failures, lint errors, and behavioral regressions
2. Generates patches for rules, tests, or documentation
3. Proposes changes via the standard PR workflow

The self‑repair loop treats the codebase as mutable infrastructure. It extends the control plane's planning capability to the repository itself, blurring the line between application and development automation.

---

7. Worktree / PR Hygiene Workflow

All changes—human or automated—follow a disciplined Git workflow defined in AGENTS.md:

• Clean worktrees: Experimental work isolates to separate Git worktrees
• Mandatory PRs: No direct pushes to main; all changes undergo review
• Automated validation: CI gates enforce tests, linting, and contract compatibility

This workflow pattern enforces temporal decoupling: agents can prepare changes asynchronously while the control plane continues operating on known‑good states.

---

Summary

LoopX's architectural patterns work together to create a maintainable, evolvable AI platform:

• Capability‑oriented design modularizes core features with strict contracts
• Extension system enables third‑party contributions without core changes
• Layered separation isolates orchestration from execution failures
• Bounded contexts enforce encapsulation and test independence
• Projection‑driven state provides auditability and observability
• Self‑repair loops automate codebase maintenance
• Worktree workflow ensures disciplined, review‑backed evolution

These patterns reflect mature domain‑driven design adapted for AI systems where code, agents, and automation interact as peers.

---

Frequently Asked Questions

What is the difference between a capability and an extension in LoopX?

A capability is a core, permanent feature with strict contracts in loopx/capabilities/. An extension is optional, swappable functionality in loopx/extensions/ that loads at runtime. Capabilities define what LoopX does; extensions define how it connects to specific environments or services. Extensions compile independently and register through a plugin interface, while capabilities are compiled into the core distribution.

How does LoopX prevent extensions from destabilizing core functionality?

Extensions interact with core modules solely through the capability registry and published contracts. The runtime loads extensions in isolated import contexts, and the control plane validates all extension‑issued commands against capability schemas. Additionally, extensions cannot mutate control‑plane state directly—they operate on projections and emit events, with the control plane deciding state changes. This defensive architecture contains faults to the extension's execution scope.

Why does LoopX use projections instead of direct database access?

Projections provide immutable, versioned views computed from event streams rather than mutable database rows. This enables: (1) complete audit trails for compliance and debugging, (2) deterministic replay for testing and recovery, and (3) decoupled read models where the Todo system and other consumers evolve independently of storage implementation. The projection layer in loopx/projection/ abstracts these mechanics from business logic.

Can the self‑repair skill modify its own code?

Yes. The self‑repair skill in loopx/skills/loopx-self-repair/ operates on the full repository including itself, but all changes follow the worktree/PR workflow. It cannot self‑apply patches directly—it must propose changes, pass CI validation, and receive review (automated or human) before merge. This reflexive constraint prevents uncontrolled self‑modification while enabling genuine autonomous improvement.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}