# reisidalt-f/reins-nlce architecture

> Architecture diagram of the GitHub repository reisidalt-f/reins-nlce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reisidalt-f/reins-nlce
- Repository: https://github.com/reisidalt-f/reins-nlce

## Overview

#### Purpose and delivery modes
Reins is a Java/Maven natural-language compilation engine: Markdown specifications are the source language, and an LLM produces target code through constrained tools. It is delivered as a Maven plugin, CLI, and embeddable Java library. Entry surfaces are `src/main/java/br/com/dizeno/reins/run/mojo/CompileMojo.java`, `src/main/java/br/com/dizeno/reins/run/cli/ReinsCli.java`, and `src/main/java/br/com/dizeno/reins/run/library/ReinsLibrary.java`; `ReinsRunner.java` composes runtime execution.

#### Configuration and invocation boundary
Configuration is loaded and validated into a shared model before any filesystem or LLM work. `src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java`, `src/main/java/br/com/dizeno/reins/run/config/ConfigValidator.java`, and `src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java` govern provider selection, scanning, targets, tooling permissions, tracking, and reasoning settings. Maven exposes compile, clean, and reasoning-note operations via `CompileMojo.java`, `CleanMojo.java`, and `AddReasoningNoteMojo.java`.

#### Source discovery and dependency ordering
Markdown inputs are discovered from configured roots, then parsed into a reference graph whose ordering drives compilation and contextual attachments. Key boundaries are `src/main/java/br/com/dizeno/reins/source/scanner/CoderMdScanner.java`, `src/main/java/br/com/dizeno/reins/source/graph/MarkdownDependencyGraphBuilder.java`, and `src/main/java/br/com/dizeno/reins/source/graph/ProcessingOrderResolver.java`. Reference resolution supports relative paths and test-to-main fallback, while path/domain types preserve source scope.

#### Compilation orchestration and incrementality
`src/main/java/br/com/dizeno/reins/compilation/CompilationService.java` coordinates a project run: construct source work, prefilter unchanged items, process in dependency order, invoke project-level reasoning where configured, and report results. Per-source work passes through the phase chain in `src/main/java/br/com/dizeno/reins/compilation/pipeline/PhaseChain.java`, including source read, tracking load, request construction, reasoning, outcome branching, and result printing. Output is written through `src/main/java/br/com/dizeno/reins/compilation/OutputWriter.java`.

Incremental state is a filesystem-backed manifest/fingerprint subsystem: `src/main/java/br/com/dizeno/reins/compilation/tracking/CompilationTrackingStore.java`, `SourceFingerprintService.java`, and `RecompilationDecider.java`. It determines whether source and mapped outputs can be skipped, and cleanup removes tracked artifacts rather than broadly deleting target paths.

#### Reasoning runtime and scripts
The reasoning service runs a multi-turn, stateful pipeline: initialize context, render reference/context messages, dispatch inference, parse directives, execute permitted tools, and complete or extend turns. The core is `src/main/java/br/com/dizeno/reins/reasoning/DefaultReasoningService.java`, planned/executed through `ReasoningPipelineExecutor.java` and phase implementations under `src/main/java/br/com/dizeno/reins/reasoning/phase/`.

FreeMarker scripts make prompt composition and phase behavior customizable, with classpath defaults in `src/main/resources/reasoning/reasoning-pipeline.ftl`, `system-context.ftl`, and `context-build.ftl`; runtime resolution is centered on `src/main/java/br/com/dizeno/reins/reasoning/scripting/ScriptRegistry.java`.

#### LLM provider boundary
Provider-neutral inference flows through `src/main/java/br/com/dizeno/reins/reasoning/inference/InferenceService.java` and `inference/llm/service/DefaultLlmService.java`. Adapter/registry abstractions isolate external services: Gemini at `inference/llm/adapters/GeminiProviderAdapter.java` and Ollama at `OllamaProviderAdapter.java`, with HTTP clients and retry policies beneath each provider. A stub adapter supports non-provider execution paths.

#### Tooling and security boundary
LLM output cannot directly mutate the project. Directives are parsed and routed through `src/main/java/br/com/dizeno/reins/reasoning/ReasoningToolOperationHandler.java` into `tooling/ToolingService.java` and operation handlers. File reads/writes/patches/deletes and script execution are constrained by base-path mappings and policy in `tooling/file/BasePathResolver.java`, `FilePolicy.java`, and global `src/main/java/br/com/dizeno/reins/security/PathValidator.java`. This is the critical containment boundary between untrusted model responses and the local filesystem.

Main entry points: [`src/main/java/br/com/dizeno/reins/compilation/CompilationService.java`](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/CompilationService.java) (Compilation service), [`src/main/java/br/com/dizeno/reins/reasoning/ReasoningPipelineExecutor.java`](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/ReasoningPipelineExecutor.java) (Reasoning pipeline executor), [`src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java`](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java) (Config loader), [`src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java`](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java) (Reins config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Delivery surfaces"]
  node_maven["Maven mojos<br/>Maven entrypoint<br/>[CompileMojo.java]"]
  node_cli["CLI<br/>[ReinsCli.java]"]
  node_library["Embeddable library<br/>Java API<br/>[ReinsLibrary.java]"]
  node_config_loader["Config loader<br/>configuration"]
  node_config_validator["Config validator<br/>validation"]
  node_config["Reins config<br/>shared model<br/>[ReinsConfig.java]"]
end

subgraph group_source["Source planning"]
  node_scanner["Markdown scanner<br/>source discovery"]
  node_dependency_graph["Reference graph builder<br/>dependency graph"]
  node_processing_order["Processing order<br/>ordering"]
end

subgraph group_compile["Compilation"]
  node_compilation_service{{"Compilation service<br/>project orchestrator"}}
  node_tracking_store[("Tracking store<br/>incremental manifest")]
  node_fingerprints["Source fingerprints<br/>change detection"]
  node_recompile_decider["Recompilation decider<br/>incremental policy"]
  node_phase_chain["Compilation phase chain<br/>per-source pipeline<br/>[PhaseChain.java]"]
  node_output_writer["Output writer<br/>artifact writer<br/>[OutputWriter.java]"]
end

subgraph group_reasoning["Reasoning runtime"]
  node_reasoning_service{{"Reasoning service<br/>stateful runtime"}}
  node_pipeline_executor["Reasoning pipeline executor<br/>phase executor"]
  node_scripts["Script registry<br/>FreeMarker runtime"]
end

subgraph group_safety["Provider and tool boundary"]
  node_inference["Inference service<br/>provider-neutral API"]
  node_llm_service["LLM service<br/>provider dispatcher"]
  node_tool_handler{{"Directive handler<br/>tool gateway"}}
  node_tooling["Tooling service<br/>operation service"]
  node_base_path["Base path resolver<br/>path containment"]
  node_file_policy["File policy<br/>tool policy"]
  node_path_validator{{"Path validator<br/>security boundary<br/>[PathValidator.java]"}}
end

node_maven -->|"loads"| node_config_loader
node_cli -->|"loads"| node_config_loader
node_library -->|"loads"| node_config_loader
node_config_loader -->|"validates"| node_config_validator
node_config_validator -->|"produces"| node_config
node_config -->|"configures"| node_scanner
node_config -->|"configures"| node_compilation_service
node_scanner -->|"Markdown inputs"| node_dependency_graph
node_dependency_graph -->|"references"| node_processing_order
node_processing_order -->|"ordered work"| node_compilation_service
node_compilation_service -->|"prefilters"| node_recompile_decider
node_fingerprints -->|"change evidence"| node_recompile_decider
node_tracking_store -->|"tracked state"| node_recompile_decider
node_compilation_service -->|"processes sources"| node_phase_chain
node_phase_chain -->|"reasoning requests"| node_reasoning_service
node_phase_chain -->|"generated output"| node_output_writer
node_output_writer -->|"records artifacts"| node_tracking_store
node_reasoning_service -->|"executes turns"| node_pipeline_executor
node_scripts -->|"renders phases"| node_pipeline_executor
node_pipeline_executor -->|"dispatches inference"| node_inference
node_inference -->|"provider calls"| node_llm_service
node_pipeline_executor -->|"parsed directives"| node_tool_handler
node_tool_handler -->|"permitted operations"| node_tooling
node_tooling -->|"resolves paths"| node_base_path
node_tooling -->|"checks policy"| node_file_policy
node_base_path -->|"validates containment"| node_path_validator
node_file_policy -->|"enforces paths"| node_path_validator

click node_maven "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/mojo/CompileMojo.java"
click node_cli "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/cli/ReinsCli.java"
click node_library "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/library/ReinsLibrary.java"
click node_config_loader "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java"
click node_config_validator "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ConfigValidator.java"
click node_config "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java"
click node_scanner "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/source/scanner/CoderMdScanner.java"
click node_dependency_graph "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/source/graph/MarkdownDependencyGraphBuilder.java"
click node_processing_order "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/source/graph/ProcessingOrderResolver.java"
click node_compilation_service "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/CompilationService.java"
click node_tracking_store "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/tracking/CompilationTrackingStore.java"
click node_fingerprints "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/tracking/SourceFingerprintService.java"
click node_recompile_decider "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/tracking/RecompilationDecider.java"
click node_phase_chain "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/pipeline/PhaseChain.java"
click node_output_writer "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/OutputWriter.java"
click node_reasoning_service "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/DefaultReasoningService.java"
click node_pipeline_executor "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/ReasoningPipelineExecutor.java"
click node_scripts "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/scripting/ScriptRegistry.java"
click node_inference "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/inference/InferenceService.java"
click node_llm_service "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/inference/llm/service/DefaultLlmService.java"
click node_tool_handler "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/ReasoningToolOperationHandler.java"
click node_path_validator "https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/security/PathValidator.java"

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_maven,node_cli,node_library,node_config_loader,node_config_validator,node_config toneBlue
class node_scanner,node_dependency_graph,node_processing_order toneAmber
class node_compilation_service,node_tracking_store,node_fingerprints,node_recompile_decider,node_phase_chain,node_output_writer toneMint
class node_reasoning_service,node_pipeline_executor,node_scripts toneRose
class node_inference,node_llm_service,node_tool_handler,node_tooling,node_base_path,node_file_policy,node_path_validator toneIndigo
```

## Components

### Delivery surfaces

- [Maven mojos](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/mojo/CompileMojo.java): Maven entrypoint · Compile, clean, and reasoning-note operations. · `src/main/java/br/com/dizeno/reins/run/mojo/CompileMojo.java`
- [CLI](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/cli/ReinsCli.java): CLI entrypoint · `src/main/java/br/com/dizeno/reins/run/cli/ReinsCli.java`
- [Embeddable library](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/library/ReinsLibrary.java): Java API · `src/main/java/br/com/dizeno/reins/run/library/ReinsLibrary.java`
- [Config loader](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java): configuration · Loads shared runtime configuration. · `src/main/java/br/com/dizeno/reins/run/config/ReinsConfigLoader.java`
- [Config validator](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ConfigValidator.java): validation · `src/main/java/br/com/dizeno/reins/run/config/ConfigValidator.java`
- [Reins config](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java): shared model · Provider, source, target, tooling, tracking, and reasoning settings. · `src/main/java/br/com/dizeno/reins/run/config/ReinsConfig.java`

### Source planning

- [Markdown scanner](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/source/scanner/CoderMdScanner.java): source discovery · `src/main/java/br/com/dizeno/reins/source/scanner/CoderMdScanner.java`
- [Reference graph builder](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/source/graph/MarkdownDependencyGraphBuilder.java): dependency graph · Builds Markdown references and contextual attachments. · `src/main/java/br/com/dizeno/reins/source/graph/MarkdownDependencyGraphBuilder.java`
- [Processing order](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/source/graph/ProcessingOrderResolver.java): ordering · `src/main/java/br/com/dizeno/reins/source/graph/ProcessingOrderResolver.java`

### Compilation

- [Compilation service](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/CompilationService.java): project orchestrator · Coordinates filtering, ordered compilation, reasoning, and reporting. · `src/main/java/br/com/dizeno/reins/compilation/CompilationService.java`
- [Tracking store](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/tracking/CompilationTrackingStore.java): incremental manifest · Filesystem-backed compilation state. · `src/main/java/br/com/dizeno/reins/compilation/tracking/CompilationTrackingStore.java`
- [Source fingerprints](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/tracking/SourceFingerprintService.java): change detection · `src/main/java/br/com/dizeno/reins/compilation/tracking/SourceFingerprintService.java`
- [Recompilation decider](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/tracking/RecompilationDecider.java): incremental policy · Skips unchanged sources and mapped outputs. · `src/main/java/br/com/dizeno/reins/compilation/tracking/RecompilationDecider.java`
- [Compilation phase chain](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/pipeline/PhaseChain.java): per-source pipeline · Reads source, loads tracking, builds requests, branches outcomes, and prints results. · `src/main/java/br/com/dizeno/reins/compilation/pipeline/PhaseChain.java`
- [Output writer](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/compilation/OutputWriter.java): artifact writer · `src/main/java/br/com/dizeno/reins/compilation/OutputWriter.java`

### Reasoning runtime

- [Reasoning service](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/DefaultReasoningService.java): stateful runtime · Runs multi-turn context, inference, directives, and completion. · `src/main/java/br/com/dizeno/reins/reasoning/DefaultReasoningService.java`
- [Reasoning pipeline executor](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/ReasoningPipelineExecutor.java): phase executor · `src/main/java/br/com/dizeno/reins/reasoning/ReasoningPipelineExecutor.java`
- [Script registry](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/scripting/ScriptRegistry.java): FreeMarker runtime · Resolves customizable prompt and phase scripts. · `src/main/java/br/com/dizeno/reins/reasoning/scripting/ScriptRegistry.java`

### Provider and tool boundary

- [Inference service](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/inference/InferenceService.java): provider-neutral API · `src/main/java/br/com/dizeno/reins/reasoning/inference/InferenceService.java`
- [LLM service](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/inference/llm/service/DefaultLlmService.java): provider dispatcher · Dispatches Gemini, Ollama, or stub adapters. · `src/main/java/br/com/dizeno/reins/reasoning/inference/llm/service/DefaultLlmService.java`
- [Directive handler](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/reasoning/ReasoningToolOperationHandler.java): tool gateway · Routes model directives into permitted operations. · `src/main/java/br/com/dizeno/reins/reasoning/ReasoningToolOperationHandler.java`
- **Tooling service**: operation service · Executes constrained file and script operations.
- **Base path resolver**: path containment
- **File policy**: tool policy
- [Path validator](https://github.com/reisidalt-f/reins-nlce/blob/master/src/main/java/br/com/dizeno/reins/security/PathValidator.java): security boundary · Global containment validation for local filesystem access. · `src/main/java/br/com/dizeno/reins/security/PathValidator.java`

## Connections

- Maven mojos → Config loader: loads
- CLI → Config loader: loads
- Embeddable library → Config loader: loads
- Config loader → Config validator: validates
- Config validator → Reins config: produces
- Reins config → Markdown scanner: configures
- Reins config → Compilation service: configures
- Markdown scanner → Reference graph builder: Markdown inputs
- Reference graph builder → Processing order: references
- Processing order → Compilation service: ordered work
- Compilation service → Recompilation decider: prefilters
- Source fingerprints → Recompilation decider: change evidence
- Tracking store → Recompilation decider: tracked state
- Compilation service → Compilation phase chain: processes sources
- Compilation phase chain → Reasoning service: reasoning requests
- Compilation phase chain → Output writer: generated output
- Output writer → Tracking store: records artifacts
- Reasoning service → Reasoning pipeline executor: executes turns
- Script registry → Reasoning pipeline executor: renders phases
- Reasoning pipeline executor → Inference service: dispatches inference
- Inference service → LLM service: provider calls
- Reasoning pipeline executor → Directive handler: parsed directives
- Directive handler → Tooling service: permitted operations
- Tooling service → Base path resolver: resolves paths
- Tooling service → File policy: checks policy
- Base path resolver → Path validator: validates containment
- File policy → Path validator: enforces paths