# rjmad1/rajajeevanloopengineering architecture

> Architecture diagram of the GitHub repository rjmad1/rajajeevanloopengineering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rjmad1/rajajeevanloopengineering
- Repository: https://github.com/rjmad1/rajajeevanloopengineering

## Overview

1. **Repository role**
   - This repo is not just an application; it is a **framework + runtime + content pack** for executing structured AI-agent “loops.”
   - It combines human-readable loop specifications, governance standards, templates, and a small Java execution engine that validates and tracks phase transitions.

2. **Primary architecture boundary: content vs runtime**
   - The repository splits cleanly into two layers:
     - **Specification/content layer:** `shared/`, `loops/`, `templates/`, `examples/`, `recipes/`, and `docs/`
     - **Execution/runtime layer:** `code/` plus container/bootstrap tooling
   - That boundary matters: the markdown/schema assets define what a loop is, while the Java code enforces how loop state changes are accepted or rejected.

3. **Loop specification and governance layer**
   - `shared/` contains cross-cutting contracts, standards, naming, metrics, versioning, and schemas.
   - `loops/` contains the actual loop catalogs grouped by purpose:
     - `core/` for discovery/planning/implementation/verification/reflection
     - `engineering/` for bug fixing, refactoring, test generation, docs, code review
     - `platform/` for validation and contract checks
     - `governance/` for ADRs, compliance, release readiness
   - This layer is the source of truth for workflow design and auditability.

4. **Runtime Java engine**
   - `code/` is a standalone Java 21+ Gradle project.
   - The runtime classes are organized around a state-machine model:
     - `LoopDefinition` and `LoopSpecCompiler` in `spec/`
     - `LoopPhase`, `LoopInstance`, `LoopStateMachine`, `TransitRequest`, `TransitResponse` in `engine/`
     - `TelemetryService` in `telemetry/`
   - The runtime’s job is to load/compile loop definitions and enforce valid lifecycle transitions.

5. **State machine and transition enforcement**
   - The central execution boundary is `LoopStateMachine`.
   - It appears to validate transitions between phases such as implementation, verification, reflection, etc., and to track whether a loop instance is in a valid state.
   - `TransitRequest`/`TransitResponse` are the main data-transfer objects for submitting and evaluating a requested state transition.

6. **API/server boundary**
   - `LoopEngineServer` exposes the runtime as a **language-neutral REST API**.
   - The README identifies the key endpoints:
     - `POST /api/v1/loops/transit`
     - `GET /api/v1/loops/{loopId}/status`
     - `GET /health`
   - This is the integration boundary for external agents, CI/CD jobs, or shell clients.

7. **Telemetry and observability**
   - `TelemetryService` is a distinct subsystem for recording engine activity.
   - In architecture terms, this sits beside the state machine rather than inside the loop spec layer, so metrics/trace data can be gathered without changing loop definitions.
   - The repo’s shared metrics docs suggest telemetry is part of the governance and validation model, not an afterthought.

8. **Bootstrapping and portability tools**
   - The repository includes scripts for **porting the loop framework into another repo**:
     - `bootstrap.py`
     - `interactive-bootstrap.ps1`
     - `port-loops.ps1`
     - `loop-control.sh`
   - These tools are operational scaffolding: they copy specs, templates, container config, and the Java engine into a target project.

9. **Container and local-dev environment**
   - `.devcontainer/` and `Dockerfile` indicate first-class containerized development/runtime support.
   - The README says the container runs the loop engine on port 8080 and is designed with reduced privileges.
   - This makes deployment and local verification part of the architecture, not separate tooling.

10. **Build and test boundary**
    - `code/build.gradle`, `gradlew`, and the test tree under `code/src/test/java/...` show the runtime is built and validated independently.
    - Tests are organized per subsystem:
      - engine tests
      - spec compiler tests
      - telemetry tests
    - That mirrors the production boundaries and supports diagramming the verification flow around each component.

11. **Documentation and operational knowledge**
    - `docs/` contains architecture, compatibility, traceability, validation, migration, and troubleshooting material.
    - This is unusually important in this repo: the docs are part of the framework’s operating model because the loops are intended to be auditable, governed workflows.
    - `examples/` provides sample run artifacts that demonstrate expected outputs and lifecycle traces.

12. **End-to-end data flow**
    - Authoring flow: loop definitions and standards are written in markdown/schema files.
    - Compilation flow: `LoopSpecCompiler` converts those definitions into runtime-ready `LoopDefinition` structures.
    - Execution flow: clients send transition requests to the REST API.
    - Enforcement flow: `LoopStateMachine` validates the transition and returns a response/status.
    - Observability flow: `TelemetryService` records engine activity.
    - Packaging flow: Docker/devcontainer/bootstrap scripts make the same framework portable to other repositories.

13. **How to draw the architecture**
    - A good diagram would show three main zones:
      - **Authoring/knowledge zone**: `shared`, `loops`, `templates`, `docs`, `examples`
      - **Execution zone**: Java engine (`spec`, `engine`, `telemetry`)
      - **Integration/deployment zone**: REST API, shell client, bootstrap scripts, Docker/devcontainer
    - The key arrows are from loop specs into the compiler/state machine, and from external clients into the REST API.

Main entry points: [`code/src/main/java/com/rajajeevan/loop/engine/LoopStateMachine.java`](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopStateMachine.java) (State Machine), [`code/src/main/java/com/rajajeevan/loop/engine/LoopEngineServer.java`](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopEngineServer.java) (Loop API), [`code/src/test/java/com/rajajeevan/loop`](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/code/src/test/java/com/rajajeevan/loop) (Runtime Tests), [`shared`](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/shared) (Shared Contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_knowledge["Authoring & Knowledge"]
  node_shared["Shared Contracts<br/>specs & standards"]
  node_loops["Loop Catalog<br/>workflow specs"]
  node_templates["Templates"]
  node_docs["Docs"]
  node_examples["Examples<br/>run artifacts"]
  node_recipes["Recipes<br/>usage guides"]
end

subgraph group_runtime["Execution Runtime"]
  node_compiler["Spec Compiler<br/>runtime compiler"]
  node_definition["Loop Definition<br/>runtime model"]
  node_state["State Machine<br/>transition engine"]
  node_instance["Loop Instance<br/>execution state<br/>[LoopInstance.java]"]
  node_api["Loop API<br/>REST server"]
  node_request["Transit Request<br/>input dto"]
  node_response["Transit Response<br/>output dto"]
  node_telemetry["Telemetry<br/>observability"]
end

subgraph group_integration["Integration & Portability"]
  node_bootstrapcli["Bootstrap CLI<br/>runtime tool<br/>[BootstrapCli.java]"]
  node_build["Gradle Build<br/>build config<br/>[build.gradle]"]
  node_tests(("Runtime Tests<br/>verification suite"))
  node_devcontainer{{"Dev Container<br/>container setup<br/>[devcontainer.json]"}}
  node_dockerfile{{"Docker Image<br/>container build"}}
  node_porting["Porting Tools<br/>bootstrap scripts<br/>[bootstrap.py]"]
end

node_shared -->|"standards inform"| node_loops
node_shared -->|"schemas guide"| node_compiler
node_loops -->|"definitions compile to"| node_compiler
node_templates -->|"authoring support"| node_loops
node_docs -.->|"documents"| node_shared
node_examples -.->|"illustrate"| node_docs
node_recipes -.->|"reuse"| node_templates
node_compiler -->|"produces"| node_definition
node_definition -->|"drives"| node_state
node_instance -->|"managed by"| node_state
node_request -->|"submitted to"| node_api
node_api -->|"delegates to"| node_state
node_state -->|"returns"| node_response
node_state -->|"emits events"| node_telemetry
node_api -.->|"observes"| node_telemetry
node_build -->|"runs"| node_tests
node_tests -.->|"verifies"| node_state
node_tests -.->|"verifies"| node_compiler
node_tests -.->|"verifies"| node_telemetry
node_devcontainer -->|"uses"| node_dockerfile
node_dockerfile -->|"runs"| node_api
node_porting -->|"copies"| node_shared
node_porting -->|"copies"| node_templates
node_porting -.->|"invokes"| node_bootstrapcli
node_bootstrapcli -.->|"bootstraps"| node_api

click node_shared "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/shared"
click node_loops "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/loops"
click node_templates "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/templates"
click node_docs "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/docs"
click node_examples "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/examples"
click node_recipes "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/recipes"
click node_compiler "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/spec/LoopSpecCompiler.java"
click node_definition "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/spec/LoopDefinition.java"
click node_state "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopStateMachine.java"
click node_instance "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopInstance.java"
click node_api "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopEngineServer.java"
click node_request "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/TransitRequest.java"
click node_response "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/TransitResponse.java"
click node_telemetry "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/telemetry/TelemetryService.java"
click node_bootstrapcli "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/bootstrap/BootstrapCli.java"
click node_build "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/build.gradle"
click node_tests "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/code/src/test/java/com/rajajeevan/loop"
click node_devcontainer "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/.devcontainer/devcontainer.json"
click node_dockerfile "https://github.com/rjmad1/rajajeevanloopengineering/tree/main/Dockerfile"
click node_porting "https://github.com/rjmad1/rajajeevanloopengineering/blob/main/bootstrap.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shared,node_loops,node_templates,node_docs,node_examples,node_recipes toneBlue
class node_compiler,node_definition,node_state,node_instance,node_api,node_request,node_response,node_telemetry toneAmber
class node_bootstrapcli,node_build,node_tests,node_devcontainer,node_dockerfile,node_porting toneMint
```

## Components

### Authoring & Knowledge

Human-readable loop specs, governance standards, templates, examples, and documentation.

- [Shared Contracts](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/shared): specs & standards · Cross-cutting contracts, naming, metrics, governance, and schemas for the loop framework. · `shared`
- [Loop Catalog](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/loops): workflow specs · Core, engineering, platform, governance, and release loop definitions. · `loops`
- [Templates](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/templates): authoring templates · Reusable markdown templates for loops, checklists, reviews, skills, and status artifacts. · `templates`
- [Docs](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/docs): architecture docs · Reference and operating documentation for concepts, validation, migration, and traceability. · `docs`
- [Examples](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/examples): run artifacts · Sample artifacts showing expected loop outputs and lifecycle traces. · `examples`
- [Recipes](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/recipes): usage guides · Scenario-oriented guidance for applying the framework in different contexts. · `recipes`

### Execution Runtime

Java engine that compiles loop specs, enforces phase transitions, and records telemetry.

- [Spec Compiler](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/spec/LoopSpecCompiler.java): runtime compiler · Compiles loop definitions into runtime-ready LoopDefinition objects. · `code/src/main/java/com/rajajeevan/loop/spec/LoopSpecCompiler.java`
- [Loop Definition](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/spec/LoopDefinition.java): runtime model · Compiled representation of a loop used by the execution engine. · `code/src/main/java/com/rajajeevan/loop/spec/LoopDefinition.java`
- [State Machine](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopStateMachine.java): transition engine · Validates phase transitions and enforces loop lifecycle rules. · `code/src/main/java/com/rajajeevan/loop/engine/LoopStateMachine.java`
- [Loop Instance](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopInstance.java): execution state · In-memory/runtime state for an active loop instance. · `code/src/main/java/com/rajajeevan/loop/engine/LoopInstance.java`
- [Loop API](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/LoopEngineServer.java): REST server · Language-neutral REST boundary for transit requests, status queries, and health checks. · `code/src/main/java/com/rajajeevan/loop/engine/LoopEngineServer.java`
- [Transit Request](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/TransitRequest.java): input dto · Client-submitted transition request evaluated by the engine. · `code/src/main/java/com/rajajeevan/loop/engine/TransitRequest.java`
- [Transit Response](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/engine/TransitResponse.java): output dto · Result returned after transition validation and execution. · `code/src/main/java/com/rajajeevan/loop/engine/TransitResponse.java`
- [Telemetry](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/telemetry/TelemetryService.java): observability · Records engine activity and supports metrics-oriented governance. · `code/src/main/java/com/rajajeevan/loop/telemetry/TelemetryService.java`

### Integration & Portability

Bootstrap, container, and portability tooling that package the framework for local or external use.

- [Bootstrap CLI](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/src/main/java/com/rajajeevan/loop/bootstrap/BootstrapCli.java): runtime tool · Java command-line entry point for bootstrapping loop assets into another project. · `code/src/main/java/com/rajajeevan/loop/bootstrap/BootstrapCli.java`
- [Gradle Build](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/code/build.gradle): build config · Standalone Java 21+ build and test configuration for the runtime. · `code/build.gradle`
- [Runtime Tests](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/code/src/test/java/com/rajajeevan/loop): verification suite · Tests for the state machine, compiler, telemetry, and server behavior. · `code/src/test/java/com/rajajeevan/loop`
- [Dev Container](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/.devcontainer/devcontainer.json): container setup · Containerized development environment and startup scripts for the engine. · `.devcontainer/devcontainer.json`
- [Docker Image](https://github.com/rjmad1/rajajeevanloopengineering/tree/main/Dockerfile): container build · Container image definition for running the loop engine with reduced privileges. · `Dockerfile`
- [Porting Tools](https://github.com/rjmad1/rajajeevanloopengineering/blob/main/bootstrap.py): bootstrap scripts · Scripts for copying loop specs, templates, and runtime scaffolding into another repository. · `bootstrap.py`

## Connections

- Shared Contracts → Loop Catalog: standards inform · Shared contracts and governance standards shape the loop catalog.
- Shared Contracts → Spec Compiler: schemas guide · Schemas and contract docs define what the compiler accepts.
- Loop Catalog → Spec Compiler: definitions compile to · Loop markdown specifications are compiled into runtime definitions.
- Templates → Loop Catalog: authoring support · Templates help create consistent loop specifications and artifacts.
- Docs → Shared Contracts: documents · Documentation explains contracts, governance, and validation practices.
- Examples → Docs: illustrate · Examples demonstrate expected outputs described by the documentation.
- Recipes → Templates: reuse · Recipes reuse templates and show common ways to apply the framework.
- Spec Compiler → Loop Definition: produces · The compiler emits runtime-ready loop definitions.
- Loop Definition → State Machine: drives · Compiled definitions are the basis for state validation.
- Loop Instance → State Machine: managed by · The state machine governs the lifecycle of each loop instance.
- Transit Request → Loop API: submitted to · External clients send transition requests to the REST server.
- Loop API → State Machine: delegates to · The server forwards requests to the state machine for enforcement.
- State Machine → Transit Response: returns · The state machine produces a transition response after validation.
- State Machine → Telemetry: emits events · Transition activity is recorded for observability and governance.
- Loop API → Telemetry: observes · API operations are tracked for health and usage visibility.
- Gradle Build → Runtime Tests: runs · The Gradle build compiles and executes the runtime test suite.
- Runtime Tests → State Machine: verifies · Tests exercise transition rules and state-machine behavior.
- Runtime Tests → Spec Compiler: verifies · Tests exercise spec compilation behavior.
- Runtime Tests → Telemetry: verifies · Tests cover telemetry behavior.
- Dev Container → Docker Image: uses · Containerized development depends on the Docker image definition.
- Docker Image → Loop API: runs · The container is configured to run the engine API.
- Porting Tools → Shared Contracts: copies · Bootstrap tooling ports shared contracts and schemas into target repos.
- Porting Tools → Templates: copies · Bootstrap tooling ports templates into target repos.
- Porting Tools → Bootstrap CLI: invokes · Scripts coordinate with the Java bootstrap CLI for packaging work.
- Bootstrap CLI → Loop API: bootstraps · The CLI helps initialize or operationalize the runtime environment.