# vgakilan/archweave architecture

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

- Interactive diagram: https://gitdiagram.com/vgakilan/archweave
- Repository: https://github.com/vgakilan/archweave

## Overview

Requirement to Diagram turns a requirement document into an evidence-backed model, selects focused diagram views, and produces Mermaid, SVG, and a written review package. The main path is document parsing → Codex extraction and planning → model validation → package generation and rendering. The repository also supports a Codex skill workflow and standalone parsing or rendering commands. Relationships are based on the README and shown source excerpts; the skill’s internal behavior and unsampled modules are not inferred.

Main entry points: [`src/diagram_generator/workflow.py`](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/workflow.py) (Workflow orchestrator), [`src/diagram_generator/codex_runner.py`](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/codex_runner.py) (Codex runner), [`src/diagram_generator/review_package.py`](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/review_package.py) (Package generator), [`scripts/run_pipeline.py`](https://github.com/vgakilan/archweave/blob/main/scripts/run_pipeline.py) (Pipeline command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and entrypoints"]
  node_source_doc["Requirement document"]
  node_pipeline_cli["Pipeline command<br/>[run_pipeline.py]"]
  node_skill["Codex skill<br/>[SKILL.md]"]
  node_parser_cli["Parse command<br/>[parse_document.py]"]
  node_review_cli["Review command<br/>[generate_review.py]"]
end

subgraph group_analysis["Requirement analysis"]
  node_parsed_md["Parsed Markdown<br/>[document_parser.py]"]
  node_document_parser["Document parser<br/>[document_parser.py]"]
  node_workflow["Workflow orchestrator<br/>[workflow.py]"]
  node_codex_runner["Codex runner<br/>[codex_runner.py]"]
  node_prompt["Review prompt"]
  node_schema["Model schema"]
  node_model["Requirement model"]
  node_model_validator["Model validator"]
end

subgraph group_generation["Review generation"]
  node_review_package["Package generator<br/>[review_package.py]"]
  node_mermaid["Mermaid generator<br/>[mermaid.py]"]
  node_renderer["SVG renderer<br/>[renderer.py]"]
  node_review_artifacts["Review package<br/>[review_package.py]"]
end

subgraph group_integration["External tools"]
  node_codex_cli["Codex CLI"]
  node_mermaid_cli["Mermaid CLI"]
end

node_user(("Engineer"))

node_user -->|"provides"| node_source_doc
node_user -->|"runs"| node_pipeline_cli
node_pipeline_cli -->|"invokes"| node_workflow
node_pipeline_cli -->|"supplies callbacks"| node_codex_runner
node_source_doc -->|"submits"| node_workflow
node_workflow -->|"parses when needed"| node_document_parser
node_document_parser -->|"converts"| node_parsed_md
node_workflow -->|"reads"| node_parsed_md
node_workflow -->|"requests extraction and planning"| node_codex_runner
node_codex_runner -->|"runs"| node_codex_cli
node_codex_runner -->|"loads"| node_prompt
node_codex_runner -->|"loads"| node_schema
node_codex_runner -->|"extracts"| node_model
node_workflow -->|"writes"| node_model
node_workflow -->|"validates via"| node_model_validator
node_model_validator -->|"checks against"| node_schema
node_workflow -->|"generates"| node_review_package
node_user -->|"invokes"| node_skill
node_skill -->|"analyzes"| node_parsed_md
node_user -->|"runs"| node_parser_cli
node_parser_cli -->|"calls"| node_document_parser
node_user -->|"runs"| node_review_cli
node_review_cli -->|"calls"| node_review_package
node_review_package -->|"generates source"| node_mermaid
node_review_package -->|"renders SVG"| node_renderer
node_renderer -->|"runs"| node_mermaid_cli
node_review_package -->|"writes"| node_review_artifacts

click node_pipeline_cli "https://github.com/vgakilan/archweave/blob/main/scripts/run_pipeline.py"
click node_skill "https://github.com/vgakilan/archweave/blob/main/.agents/skills/requirement-review/SKILL.md"
click node_parser_cli "https://github.com/vgakilan/archweave/blob/main/scripts/parse_document.py"
click node_parsed_md "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/document_parser.py"
click node_document_parser "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/document_parser.py"
click node_workflow "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/workflow.py"
click node_codex_runner "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/codex_runner.py"
click node_prompt "https://github.com/vgakilan/archweave/blob/main/prompts/requirement_review.md"
click node_schema "https://github.com/vgakilan/archweave/blob/main/schemas/requirement.schema.json"
click node_model "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/requirement_model.py"
click node_model_validator "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/requirement_model.py"
click node_review_cli "https://github.com/vgakilan/archweave/blob/main/scripts/generate_review.py"
click node_review_package "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/review_package.py"
click node_mermaid "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/mermaid.py"
click node_renderer "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/renderer.py"
click node_review_artifacts "https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/review_package.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_source_doc,node_pipeline_cli,node_skill,node_parser_cli,node_review_cli toneBlue
class node_parsed_md,node_document_parser,node_workflow,node_codex_runner,node_prompt,node_schema,node_model,node_model_validator toneAmber
class node_review_package,node_mermaid,node_renderer,node_review_artifacts toneMint
class node_codex_cli,node_mermaid_cli toneRose
class node_user toneIndigo
```

## Components

### Inputs and entrypoints

- **Requirement document**
- [Pipeline command](https://github.com/vgakilan/archweave/blob/main/scripts/run_pipeline.py): `scripts/run_pipeline.py`
- [Codex skill](https://github.com/vgakilan/archweave/blob/main/.agents/skills/requirement-review/SKILL.md): `.agents/skills/requirement-review/SKILL.md`
- [Parse command](https://github.com/vgakilan/archweave/blob/main/scripts/parse_document.py): `scripts/parse_document.py`
- [Review command](https://github.com/vgakilan/archweave/blob/main/scripts/generate_review.py): `scripts/generate_review.py`

### Requirement analysis

- [Parsed Markdown](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/document_parser.py): `src/diagram_generator/document_parser.py`
- [Document parser](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/document_parser.py): `src/diagram_generator/document_parser.py`
- [Workflow orchestrator](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/workflow.py): `src/diagram_generator/workflow.py`
- [Codex runner](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/codex_runner.py): `src/diagram_generator/codex_runner.py`
- [Review prompt](https://github.com/vgakilan/archweave/blob/main/prompts/requirement_review.md): `prompts/requirement_review.md`
- [Model schema](https://github.com/vgakilan/archweave/blob/main/schemas/requirement.schema.json): `schemas/requirement.schema.json`
- [Requirement model](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/requirement_model.py): `src/diagram_generator/requirement_model.py`
- [Model validator](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/requirement_model.py): `src/diagram_generator/requirement_model.py`

### Review generation

- [Package generator](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/review_package.py): `src/diagram_generator/review_package.py`
- [Mermaid generator](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/mermaid.py): `src/diagram_generator/mermaid.py`
- [SVG renderer](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/renderer.py): `src/diagram_generator/renderer.py`
- [Review package](https://github.com/vgakilan/archweave/blob/main/src/diagram_generator/review_package.py): `src/diagram_generator/review_package.py`

### External tools

- **Codex CLI**
- **Mermaid CLI**

### Other components

- **Engineer**

## Connections

- Engineer → Requirement document: provides (evidence: `README.md`)
- Engineer → Pipeline command: runs (evidence: `README.md`)
- Pipeline command → Workflow orchestrator: invokes (evidence: `scripts/run_pipeline.py`)
- Pipeline command → Codex runner: supplies callbacks (evidence: `scripts/run_pipeline.py`)
- Requirement document → Workflow orchestrator: submits (evidence: `README.md`)
- Workflow orchestrator → Document parser: parses when needed (evidence: `src/diagram_generator/workflow.py`)
- Document parser → Parsed Markdown: converts (evidence: `src/diagram_generator/document_parser.py`)
- Workflow orchestrator → Parsed Markdown: reads (evidence: `src/diagram_generator/workflow.py`)
- Workflow orchestrator → Codex runner: requests extraction and planning (evidence: `scripts/run_pipeline.py`)
- Codex runner → Codex CLI: runs (evidence: `src/diagram_generator/codex_runner.py`)
- Codex runner → Review prompt: loads (evidence: `src/diagram_generator/codex_runner.py`)
- Codex runner → Model schema: loads (evidence: `src/diagram_generator/codex_runner.py`)
- Codex runner → Requirement model: extracts (evidence: `README.md`)
- Workflow orchestrator → Requirement model: writes (evidence: `src/diagram_generator/workflow.py`)
- Workflow orchestrator → Model validator: validates via (evidence: `src/diagram_generator/workflow.py`)
- Model validator → Model schema: checks against (evidence: `src/diagram_generator/requirement_model.py`)
- Workflow orchestrator → Package generator: generates (evidence: `src/diagram_generator/workflow.py`)
- Engineer → Codex skill: invokes (evidence: `README.md`)
- Codex skill → Parsed Markdown: analyzes (evidence: `README.md`)
- Engineer → Parse command: runs (evidence: `README.md`)
- Parse command → Document parser: calls (evidence: `scripts/parse_document.py`)
- Engineer → Review command: runs (evidence: `README.md`)
- Review command → Package generator: calls (evidence: `scripts/generate_review.py`)
- Package generator → Mermaid generator: generates source (evidence: `src/diagram_generator/review_package.py`)
- Package generator → SVG renderer: renders SVG (evidence: `src/diagram_generator/review_package.py`)
- SVG renderer → Mermaid CLI: runs (evidence: `src/diagram_generator/renderer.py`)
- Package generator → Review package: writes (evidence: `README.md`)
