# sandeco/reversa architecture

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

- Interactive diagram: https://gitdiagram.com/sandeco/reversa
- Repository: https://github.com/sandeco/reversa

## Overview

Reversa is an AI-agent framework and installer that turns knowledge in legacy software into traceable, operational specifications. The main workflow starts when a user invokes the installed Reversa skill in an AI coding environment: its orchestrator coordinates reconnaissance, code excavation, interpretation, specification generation, and review. The resulting specifications support separate migration, forward-development, and HTML-documentation workflows; the framework also provides a greenfield path. The graph combines README-documented capabilities with sampled CLI and installer behavior; agent internals were not sampled, so orchestration links reflect documented workflow rather than inspected calls.

Main entry points: [`agents/reversa`](https://github.com/sandeco/reversa/tree/main/agents/reversa) (Discovery orchestrator), [`lib/commands/install.js`](https://github.com/sandeco/reversa/blob/main/lib/commands/install.js) (Install command), [`bin/reversa.js`](https://github.com/sandeco/reversa/blob/main/bin/reversa.js) (Reversa CLI), [`lib/installer/writer.js`](https://github.com/sandeco/reversa/blob/main/lib/installer/writer.js) (Installer writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Installation"]
  node_cli["Reversa CLI<br/>[reversa.js]"]
  node_install["Install command<br/>[install.js]"]
  node_detect["Engine detection<br/>[detector.js]"]
  node_prompts["Setup prompts<br/>[prompts.js]"]
  node_writer["Installer writer<br/>[writer.js]"]
  node_engines["AI engine setup"]
end

subgraph group_discovery["Legacy Discovery"]
  node_orchestrator["Discovery orchestrator"]
  node_scout["Reconnaissance"]
  node_archaeologist["Code excavation"]
  node_detective["Rule interpretation"]
  node_architect["Architecture analysis"]
  node_writeragent["Spec generation"]
  node_reviewer["Spec review"]
end

subgraph group_delivery["Specification Use"]
  node_specs["Executable specifications"]
  node_forward["Forward development"]
  node_migration["Legacy migration"]
  node_docs["HTML mini-site"]
end

subgraph group_other["Additional Workflows"]
  node_newproject["Greenfield specs"]
  node_debugger["Defect traceability"]
  node_pricing["Effort and pricing"]
end

node_user(("Project user"))
node_legacy["Legacy project"]
node_ai(("AI coding agent"))

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches install"| node_install
node_install -->|"detects engines"| node_detect
node_install -->|"collects setup"| node_prompts
node_install -->|"installs files"| node_writer
node_writer -->|"writes skills"| node_engines
node_engines -->|"enables invocation"| node_ai
node_user -->|"invokes skill"| node_ai
node_ai -->|"runs"| node_orchestrator
node_orchestrator -->|"coordinates"| node_scout
node_orchestrator -->|"coordinates"| node_archaeologist
node_orchestrator -->|"coordinates"| node_detective
node_orchestrator -->|"coordinates"| node_architect
node_orchestrator -->|"coordinates"| node_writeragent
node_orchestrator -->|"coordinates"| node_reviewer
node_scout -->|"inspects"| node_legacy
node_archaeologist -->|"analyzes"| node_legacy
node_writeragent -->|"generates"| node_specs
node_reviewer -->|"reviews"| node_specs
node_specs -->|"guides evolution"| node_forward
node_specs -->|"guides rebuild"| node_migration
node_specs -->|"renders"| node_docs
node_user -->|"starts idea"| node_newproject
node_newproject -->|"generates"| node_specs
node_user -->|"invokes"| node_debugger
node_specs -->|"supports estimate"| node_pricing

click node_cli "https://github.com/sandeco/reversa/blob/main/bin/reversa.js"
click node_install "https://github.com/sandeco/reversa/blob/main/lib/commands/install.js"
click node_detect "https://github.com/sandeco/reversa/blob/main/lib/installer/detector.js"
click node_prompts "https://github.com/sandeco/reversa/blob/main/lib/installer/prompts.js"
click node_writer "https://github.com/sandeco/reversa/blob/main/lib/installer/writer.js"
click node_orchestrator "https://github.com/sandeco/reversa/tree/main/agents/reversa"
click node_scout "https://github.com/sandeco/reversa/tree/main/agents/reversa-scout"
click node_archaeologist "https://github.com/sandeco/reversa/tree/main/agents/reversa-archaeologist"
click node_detective "https://github.com/sandeco/reversa/tree/main/agents/reversa-detective"
click node_architect "https://github.com/sandeco/reversa/tree/main/agents/reversa-architect"
click node_writeragent "https://github.com/sandeco/reversa/tree/main/agents/reversa-writer"
click node_reviewer "https://github.com/sandeco/reversa/tree/main/agents/reversa-reviewer"
click node_forward "https://github.com/sandeco/reversa/tree/main/agents/reversa-forward"
click node_migration "https://github.com/sandeco/reversa/tree/main/agents/reversa-migrate"
click node_docs "https://github.com/sandeco/reversa/tree/main/agents/reversa-docs"
click node_newproject "https://github.com/sandeco/reversa/tree/main/agents/reversa-new"
click node_debugger "https://github.com/sandeco/reversa/tree/main/agents/reversa-debugger"
click node_pricing "https://github.com/sandeco/reversa/tree/main/agents/reversa-pricing-estimate"

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_cli,node_install,node_detect,node_prompts,node_writer,node_engines,node_user toneBlue
class node_orchestrator,node_scout,node_archaeologist,node_detective,node_architect,node_writeragent,node_reviewer toneAmber
class node_specs,node_forward,node_migration,node_docs toneMint
class node_newproject,node_debugger,node_pricing toneRose
class node_legacy,node_ai toneIndigo
```

## Components

### Installation

- [Reversa CLI](https://github.com/sandeco/reversa/blob/main/bin/reversa.js): `bin/reversa.js`
- [Install command](https://github.com/sandeco/reversa/blob/main/lib/commands/install.js): `lib/commands/install.js`
- [Engine detection](https://github.com/sandeco/reversa/blob/main/lib/installer/detector.js): `lib/installer/detector.js`
- [Setup prompts](https://github.com/sandeco/reversa/blob/main/lib/installer/prompts.js): `lib/installer/prompts.js`
- [Installer writer](https://github.com/sandeco/reversa/blob/main/lib/installer/writer.js): `lib/installer/writer.js`
- **AI engine setup**

### Legacy Discovery

- [Discovery orchestrator](https://github.com/sandeco/reversa/tree/main/agents/reversa): `agents/reversa`
- [Reconnaissance](https://github.com/sandeco/reversa/tree/main/agents/reversa-scout): `agents/reversa-scout`
- [Code excavation](https://github.com/sandeco/reversa/tree/main/agents/reversa-archaeologist): `agents/reversa-archaeologist`
- [Rule interpretation](https://github.com/sandeco/reversa/tree/main/agents/reversa-detective): `agents/reversa-detective`
- [Architecture analysis](https://github.com/sandeco/reversa/tree/main/agents/reversa-architect): `agents/reversa-architect`
- [Spec generation](https://github.com/sandeco/reversa/tree/main/agents/reversa-writer): `agents/reversa-writer`
- [Spec review](https://github.com/sandeco/reversa/tree/main/agents/reversa-reviewer): `agents/reversa-reviewer`

### Specification Use

- **Executable specifications**
- [Forward development](https://github.com/sandeco/reversa/tree/main/agents/reversa-forward): `agents/reversa-forward`
- [Legacy migration](https://github.com/sandeco/reversa/tree/main/agents/reversa-migrate): `agents/reversa-migrate`
- [HTML mini-site](https://github.com/sandeco/reversa/tree/main/agents/reversa-docs): `agents/reversa-docs`

### Additional Workflows

- [Greenfield specs](https://github.com/sandeco/reversa/tree/main/agents/reversa-new): `agents/reversa-new`
- [Defect traceability](https://github.com/sandeco/reversa/tree/main/agents/reversa-debugger): `agents/reversa-debugger`
- [Effort and pricing](https://github.com/sandeco/reversa/tree/main/agents/reversa-pricing-estimate): `agents/reversa-pricing-estimate`

### Other components

- **Project user**
- **Legacy project**
- **AI coding agent**

## Connections

- Project user → Reversa CLI: runs command
- Reversa CLI → Install command: dispatches install
- Install command → Engine detection: detects engines
- Install command → Setup prompts: collects setup
- Install command → Installer writer: installs files
- Installer writer → AI engine setup: writes skills
- AI engine setup → AI coding agent: enables invocation
- Project user → AI coding agent: invokes skill
- AI coding agent → Discovery orchestrator: runs
- Discovery orchestrator → Reconnaissance: coordinates
- Discovery orchestrator → Code excavation: coordinates
- Discovery orchestrator → Rule interpretation: coordinates
- Discovery orchestrator → Architecture analysis: coordinates
- Discovery orchestrator → Spec generation: coordinates
- Discovery orchestrator → Spec review: coordinates
- Reconnaissance → Legacy project: inspects
- Code excavation → Legacy project: analyzes
- Spec generation → Executable specifications: generates
- Spec review → Executable specifications: reviews
- Executable specifications → Forward development: guides evolution
- Executable specifications → Legacy migration: guides rebuild
- Executable specifications → HTML mini-site: renders
- Project user → Greenfield specs: starts idea
- Greenfield specs → Executable specifications: generates
- Project user → Defect traceability: invokes
- Executable specifications → Effort and pricing: supports estimate