# Key Data Flow Paths in LoopX: From Registry to Runtime State

> Explore LoopX data flow paths from registry to runtime state. Understand configuration to execution feedback loops for efficient development.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: deep-dive
- Published: 2026-08-13

---

**LoopX moves data from a JSON registry through runtime root resolution, goal validation, state refresh cycles, projection generation, and HTTP status endpoints to create a closed feedback loop between configuration and execution.**

The `huangruiteng/loopx` repository implements a runtime management system that transforms static configuration into monitored execution state. Understanding how data flows between the registry file, runtime directories, and projection layers is essential for extending the system or debugging execution mismatches. These paths demonstrate how LoopX maintains consistency between declared goals and actual runtime behavior.

## How LoopX Transforms Registry Files into Runtime Roots

The data flow begins when LoopX ingests the central registry configuration and determines where runtime artifacts will live.

### Loading and Resolving the Runtime Directory

In [`loopx/history.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/history.py), the function `load_registry` reads the JSON registry file, which contains the `common_runtime_root` key defining the base directory for all runtime data. This registry object is then passed to [`loopx/paths.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/paths.py), where `resolve_runtime_root` extracts the path from `registry["common_runtime_root"]` or defaults to `~/.codex/loopx` if unspecified. The function resolves this path relative to the project root and returns the absolute runtime root directory.

```python

# Simplified flow showing registry to runtime resolution

registry = load_registry(registry_path)                     # loopx/history.py

runtime_root = resolve_runtime_root(registry)               # loopx/paths.py

```

This resolution step anchors all subsequent file operations, ensuring that goal directories, state files, and projections are written to a consistent location regardless of where the command is executed.

## Goal Lifecycle and Archiving Workflows

Once the runtime root is established, LoopX manages individual goals through validation, archiving, and state transition logic defined in [`loopx/runtime.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/runtime.py).

### Validating and Archiving Goals via runtime.py

The `archive_runtime_goal` function orchestrates the movement of goal data from active runtime to archive storage. It first calls `validate_goal_id_path_segment` to ensure the goal ID is filesystem-safe, then checks `registry_goals` to confirm the goal exists in the registry. After verification, it relocates the goal directory to an archive location and returns a payload consumed by `render_archive_runtime_markdown` for generating human-readable summaries.

```python
payload = archive_runtime_goal(
    registry_path=repo_path / "registry.json",
    runtime_root_override=None,
    goal_id="my-goal",
    archive_root=None,
    allow_registered=False,
    execute=True,
)

```

Setting `execute=False` performs a dry-run, returning the projected `archive_path` without moving files, which is useful for CLI previews and automated safety checks.

## State Refresh and Projection Generation

After goals are active in the runtime directory, LoopX continuously refreshes execution state and builds shared projections that serve as the single source of truth for downstream consumers.

### Building Shared Runtime Projections

The [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) module drives this phase. It loads the current run file, parses the *active state* and *next-action* text, then invokes `build_shared_runtime_projection` to create a structured view of the runtime. This projection is persisted via `write_shared_runtime_projection` to the runtime root, where it becomes accessible to the status server and summary generators.

```python
projection = build_shared_runtime_projection(state, ...)   # state_refresh.py

write_shared_runtime_projection(runtime_root, projection) # state_refresh.py

```

### Detecting Action Mismatches

In [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py), the system compares the *active* next-action against the *recommended* action from the latest run. The function `next_action_projection_warning` uses helpers like `_action_projection_compare_text` and `actions_are_projection_aligned` to determine if the current state has drifted from the expected execution path.

```python
warning = next_action_projection_warning(
    active_state_next_action=active_next,
    latest_run_recommended_action=run_next,
)

```

When a mismatch is detected, the warning payload includes metadata about the divergence kind, enabling CLI tools to alert users or triggering automated remediation workflows.

## Serving Runtime Status via HTTP

LoopX exposes the internal projection state through HTTP endpoints defined in [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py). The `/status` endpoint reads the shared projection files from the runtime root and returns JSON-encoded status data, allowing external dashboards and CLI tools to poll for current execution state without direct filesystem access.

```python
@app.get("/status")
async def status():
    return load_shared_runtime_projection(runtime_root)   # status_server.py

```

This decouples the execution environment from observation tools, supporting distributed monitoring scenarios where the status server runs in a container or remote host.

## CLI Entry Points and Orchestration

The top-level entry point in [`loopx/entrypoint.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/entrypoint.py) forwards command-line arguments to `loopx.cli.main`, which routes to sub-commands like `loopx archive`, `loopx refresh`, or `loopx status`. This entry point acts as the traffic controller that instantiates the data flows described above based on user intent.

```python

# entrypoint.py

def main(argv=None):
    return cli_main(argv or sys.argv[1:])

```

By centralizing argument parsing and dispatch here, LoopX ensures consistent error handling and logging across all execution paths.

## Summary

- **Registry Resolution**: `load_registry` and `resolve_runtime_root` in [`loopx/history.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/history.py) and [`loopx/paths.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/paths.py) establish the filesystem foundation using `common_runtime_root` or the `~/.codex/loopx` default.
- **Goal Archiving**: `archive_runtime_goal` validates goal IDs against the registry, moves directories, and generates markdown summaries via `render_archive_runtime_markdown`.
- **State Projection**: `build_shared_runtime_projection` and `write_shared_runtime_projection` in [`loopx/state_refresh.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_refresh.py) convert raw run data into structured projections.
- **Mismatch Detection**: `next_action_projection_warning` in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) compares active and recommended actions using `_action_projection_compare_text`.
- **External Exposure**: [`loopx/status_server.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status_server.py) serves projections via HTTP `/status`, while [`loopx/entrypoint.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/entrypoint.py) wires CLI commands to these internal flows.

## Frequently Asked Questions

### How does LoopX determine where to store runtime data?

LoopX calls `resolve_runtime_root` in [`loopx/paths.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/paths.py), which checks the `common_runtime_root` key in the registry JSON file. If this key is missing or null, it defaults to `~/.codex/loopx` and resolves the path relative to the project root. This ensures that runtime directories are predictable and configurable per project.

### What happens during a dry-run archive operation?

When `archive_runtime_goal` receives `execute=False`, it performs validation steps—including checking `validate_goal_id_path_segment` and `registry_goals` membership—computes the target archive path, and returns a payload containing the projected destination. No filesystem moves occur, allowing users to preview the operation via `render_archive_runtime_markdown` before committing changes.

### How does LoopX detect when execution deviates from the plan?

The `next_action_projection_warning` function in [`loopx/state_projection.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/state_projection.py) compares the active state's next-action text against the latest run's recommended action using `actions_are_projection_aligned`. If the comparison fails, it returns a warning dictionary describing the mismatch kind, enabling the CLI or status consumers to surface drift alerts to users.