# scaibu/policy-orchestrator architecture

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

- Interactive diagram: https://gitdiagram.com/scaibu/policy-orchestrator
- Repository: https://github.com/scaibu/policy-orchestrator

## Overview

Policy Orchestrator is a FastAPI/CLI product for repository architecture operations: it searches local files and code, scaffolds package/feature layouts, and performs zero-clone remote Git inspection, mutation, verification, and submodule management. The main user flow is an HTTP or CLI request routed to a feature service, which performs domain work and, where needed, uses remote Git providers or persistence. README documentation establishes several capabilities whose internal implementations were not sampled, so those links are shown as unverified rather than inferred call chains.

Main entry points: [`src/api/rest/app.py`](https://github.com/scaibu/policy-orchestrator/blob/main/src/api/rest/app.py) (REST API), [`src/api/cli/main.py`](https://github.com/scaibu/policy-orchestrator/blob/main/src/api/cli/main.py) (CLI), [`src/features/git_submodule_manager/service/git_submodule_manager_service.py`](https://github.com/scaibu/policy-orchestrator/blob/main/src/features/git_submodule_manager/service/git_submodule_manager_service.py) (Submodule Manager), [`src/features/file_search/service/file_search_service.py`](https://github.com/scaibu/policy-orchestrator/blob/main/src/features/file_search/service/file_search_service.py) (File Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_rest["REST API<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
  node_tasks["Task Lifecycle"]
end

subgraph group_repo["Repository Intelligence"]
  node_file_search["File Search"]
  node_code_search["Code Search"]
  node_scaffold["Scaffolding"]
  node_resolver["Module Resolver"]
end

subgraph group_git["Remote Git Operations"]
  node_inspector["Remote Inspector"]
  node_mutator["Remote Mutator"]
  node_submodules["Submodule Manager"]
  node_verifier["Git Verifier"]
  node_branch["Branch Lifecycle"]
end

subgraph group_platform["Shared Platform"]
  node_contracts["API Contracts<br/>[envelope_types.py]"]
  node_remote_providers["Git Providers"]
  node_graph_store[("Graph Lineage<br/>[neo4j_adapter.py]")]
  node_config["Configuration<br/>[config_loader.py]"]
end

node_user(("Engineer"))

node_user -->|"sends request"| node_rest
node_user -->|"runs command"| node_cli
node_rest -.->|"routes search"| node_file_search
node_rest -.->|"routes search"| node_code_search
node_rest -.->|"routes scaffold"| node_scaffold
node_rest -.->|"routes resolution"| node_resolver
node_rest -.->|"routes inspection"| node_inspector
node_rest -.->|"routes mutation"| node_mutator
node_rest -->|"routes operations"| node_submodules
node_rest -.->|"routes verification"| node_verifier
node_rest -.->|"routes lifecycle"| node_branch
node_cli -->|"invokes search"| node_file_search
node_cli -.->|"invokes search"| node_code_search
node_cli -->|"invokes scaffold"| node_scaffold
node_cli -->|"dispatches tasks"| node_tasks
node_cli -->|"invokes inspection"| node_inspector
node_cli -->|"invokes mutation"| node_mutator
node_cli -->|"invokes operations"| node_submodules
node_cli -->|"invokes verification"| node_verifier
node_file_search -->|"returns envelope"| node_contracts
node_submodules -->|"mutates and inspects"| node_remote_providers
node_submodules -->|"syncs lineage"| node_graph_store
node_inspector -.->|"reads remote Git"| node_remote_providers
node_mutator -->|"writes remote Git"| node_remote_providers
node_branch -.->|"tracks branches"| node_graph_store
node_rest -->|"loads settings"| node_config

click node_rest "https://github.com/scaibu/policy-orchestrator/blob/main/src/api/rest/app.py"
click node_cli "https://github.com/scaibu/policy-orchestrator/blob/main/src/api/cli/main.py"
click node_file_search "https://github.com/scaibu/policy-orchestrator/blob/main/src/features/file_search/service/file_search_service.py"
click node_code_search "https://github.com/scaibu/policy-orchestrator/blob/main/src/features/code_search/service/code_search_service.py"
click node_scaffold "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/folder_scaffold"
click node_resolver "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/module_resolver"
click node_inspector "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_remote_inspector"
click node_mutator "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_remote_mutator"
click node_submodules "https://github.com/scaibu/policy-orchestrator/blob/main/src/features/git_submodule_manager/service/git_submodule_manager_service.py"
click node_verifier "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_verifier"
click node_branch "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_branch_lifecycle"
click node_tasks "https://github.com/scaibu/policy-orchestrator/tree/main/src/features/task_lifecycle"
click node_contracts "https://github.com/scaibu/policy-orchestrator/blob/main/src/shared/types/envelope_types.py"
click node_graph_store "https://github.com/scaibu/policy-orchestrator/blob/main/src/infra/adapters/graph/neo4j_adapter.py"
click node_config "https://github.com/scaibu/policy-orchestrator/blob/main/src/infra/config/config_loader.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_rest,node_cli,node_tasks toneBlue
class node_file_search,node_code_search,node_scaffold,node_resolver toneAmber
class node_inspector,node_mutator,node_submodules,node_verifier,node_branch toneMint
class node_contracts,node_remote_providers,node_graph_store,node_config toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [REST API](https://github.com/scaibu/policy-orchestrator/blob/main/src/api/rest/app.py): `src/api/rest/app.py`
- [CLI](https://github.com/scaibu/policy-orchestrator/blob/main/src/api/cli/main.py): `src/api/cli/main.py`
- [Task Lifecycle](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/task_lifecycle): `src/features/task_lifecycle`

### Repository Intelligence

- [File Search](https://github.com/scaibu/policy-orchestrator/blob/main/src/features/file_search/service/file_search_service.py): `src/features/file_search/service/file_search_service.py`
- [Code Search](https://github.com/scaibu/policy-orchestrator/blob/main/src/features/code_search/service/code_search_service.py): `src/features/code_search/service/code_search_service.py`
- [Scaffolding](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/folder_scaffold): `src/features/folder_scaffold`
- [Module Resolver](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/module_resolver): `src/features/module_resolver`

### Remote Git Operations

- [Remote Inspector](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_remote_inspector): `src/features/git_remote_inspector`
- [Remote Mutator](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_remote_mutator): `src/features/git_remote_mutator`
- [Submodule Manager](https://github.com/scaibu/policy-orchestrator/blob/main/src/features/git_submodule_manager/service/git_submodule_manager_service.py): `src/features/git_submodule_manager/service/git_submodule_manager_service.py`
- [Git Verifier](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_verifier): `src/features/git_verifier`
- [Branch Lifecycle](https://github.com/scaibu/policy-orchestrator/tree/main/src/features/git_branch_lifecycle): `src/features/git_branch_lifecycle`

### Shared Platform

- [API Contracts](https://github.com/scaibu/policy-orchestrator/blob/main/src/shared/types/envelope_types.py): `src/shared/types/envelope_types.py`
- **Git Providers**
- [Graph Lineage](https://github.com/scaibu/policy-orchestrator/blob/main/src/infra/adapters/graph/neo4j_adapter.py): `src/infra/adapters/graph/neo4j_adapter.py`
- [Configuration](https://github.com/scaibu/policy-orchestrator/blob/main/src/infra/config/config_loader.py): `src/infra/config/config_loader.py`

### Other components

- **Engineer**

## Connections

- Engineer → REST API: sends request (evidence: `README.md`)
- Engineer → CLI: runs command (evidence: `README.md`)
- REST API → File Search: routes search
- REST API → Code Search: routes search
- REST API → Scaffolding: routes scaffold
- REST API → Module Resolver: routes resolution
- REST API → Remote Inspector: routes inspection
- REST API → Remote Mutator: routes mutation
- REST API → Submodule Manager: routes operations
- REST API → Git Verifier: routes verification
- REST API → Branch Lifecycle: routes lifecycle
- CLI → File Search: invokes search (evidence: `src/api/cli/main.py`)
- CLI → Code Search: invokes search
- CLI → Scaffolding: invokes scaffold (evidence: `README.md`)
- CLI → Task Lifecycle: dispatches tasks (evidence: `src/api/cli/main.py`)
- CLI → Remote Inspector: invokes inspection (evidence: `src/api/cli/main.py`)
- CLI → Remote Mutator: invokes mutation (evidence: `src/api/cli/main.py`)
- CLI → Submodule Manager: invokes operations
- CLI → Git Verifier: invokes verification (evidence: `src/api/cli/main.py`)
- File Search → API Contracts: returns envelope (evidence: `src/api/rest/v1/handlers/file_search_handler.py`)
- Submodule Manager → Git Providers: mutates and inspects (evidence: `src/features/git_submodule_manager/service/git_submodule_manager_service.py`)
- Submodule Manager → Graph Lineage: syncs lineage
- Remote Inspector → Git Providers: reads remote Git (evidence: `README.md`)
- Remote Mutator → Git Providers: writes remote Git (evidence: `README.md`)
- Branch Lifecycle → Graph Lineage: tracks branches (evidence: `README.md`)
- REST API → Configuration: loads settings
