# muzzammil242/pgrecon architecture

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

- Interactive diagram: https://gitdiagram.com/muzzammil242/pgrecon
- Repository: https://github.com/muzzammil242/pgrecon

## Overview

pgrecon assesses Oracle migrations and converts supported schema objects without connecting to Oracle: a DBA runs the generated read-only extraction script, then local commands load its files, report deterministic findings, estimate effort, or emit PostgreSQL DDL plus named residue. The graph separates extraction, inventory/parsing, assessment, conversion, and CLI orchestration. Some converter and extraction implementations were not excerpted; their documented roles are shown, but uncertain internal calls are omitted.

Main entry points: [`src/pgrecon/convert/schema.py`](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/schema.py) (Schema conversion), [`src/pgrecon/cli.py`](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/cli.py) (CLI commands), [`src/pgrecon/convert/tables.py`](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/tables.py) (Table and partition DDL), [`src/pgrecon/rules/engine.py`](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/rules/engine.py) (Rule engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["CLI workflows"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_runbook["Migration runbook<br/>[runbook.py]"]
end

subgraph group_capture["Oracle extraction"]
  node_extract["SQL*Plus script<br/>[__init__.py]"]
  node_dump["Dump files"]
end

subgraph group_inventory["Inventory and parsing"]
  node_loader["Dump loader<br/>[loader.py]"]
  node_sqlite[("SQLite inventory")]
  node_plsql["PL/SQL parsing<br/>[__init__.py]"]
  node_plsql_walk["Parse tree walker<br/>[walk.py]"]
  node_antlr_lexer["Generated lexer<br/>[PlSqlLexer.py]"]
  node_antlr_parser["Generated parser<br/>[PlSqlParser.py]"]
  node_antlr_listener["Parse listener"]
end

subgraph group_assessment["Assessment"]
  node_rules_catalog["Rule catalog<br/>[__init__.py]"]
  node_rule_engine["Rule engine<br/>[engine.py]"]
  node_rule_sets["Rule categories"]
  node_findings["Findings"]
  node_effort["Effort estimator<br/>[effort.py]"]
end

subgraph group_conversion["Schema conversion"]
  node_converter["Schema conversion<br/>[schema.py]"]
  node_table_emit["Table and partition DDL<br/>[tables.py]"]
  node_partition_emit["Partition emission<br/>[partitions.py]"]
  node_identifier["Identifier translation<br/>[identifiers.py]"]
  node_namespace["Name registry<br/>[namespace.py]"]
  node_typemap["Type mapping<br/>[typemap.py]"]
  node_plsql_rewrite["PL/SQL rewriting<br/>[plsql_rewrite.py]"]
  node_other_emitters["Other DDL emitters"]
  node_residue["Conversion residue<br/>[residue.py]"]
  node_ddl["PostgreSQL DDL"]
end

node_dba(("DBA"))

node_dba -->|"runs script"| node_extract
node_extract -->|"spools files"| node_dump
node_dba -->|"runs commands"| node_cli
node_cli -->|"generates script"| node_extract
node_cli -->|"loads dump"| node_loader
node_dump -->|"provides input"| node_loader
node_loader -->|"writes inventory"| node_sqlite
node_loader -->|"parses stored units"| node_plsql_walk
node_plsql_walk -->|"uses parser"| node_plsql
node_plsql -->|"tokenizes with"| node_antlr_lexer
node_plsql -->|"parses with"| node_antlr_parser
node_plsql_walk -->|"walks parse events"| node_antlr_listener
node_cli -->|"runs report"| node_rule_engine
node_rule_engine -->|"queries inventory"| node_sqlite
node_rule_engine -->|"loads rules"| node_rules_catalog
node_rules_catalog -->|"assembles categories"| node_rule_sets
node_rule_engine -->|"produces"| node_findings
node_cli -->|"estimates effort"| node_effort
node_effort -->|"uses findings"| node_findings
node_cli -->|"converts schema"| node_converter
node_converter -.->|"reads inventory"| node_sqlite
node_converter -.->|"emits tables"| node_table_emit
node_converter -.->|"emits partitions"| node_partition_emit
node_table_emit -->|"translates names"| node_identifier
node_table_emit -->|"maps types"| node_typemap
node_table_emit -->|"uses partition logic"| node_partition_emit
node_converter -.->|"emits other objects"| node_other_emitters
node_other_emitters -.->|"rewrites stored code"| node_plsql_rewrite
node_plsql_rewrite -->|"uses translation helpers"| node_identifier
node_plsql_rewrite -->|"uses type mapping"| node_typemap
node_converter -.->|"tracks names"| node_namespace
node_table_emit -->|"claims names"| node_namespace
node_converter -.->|"records refusals"| node_residue
node_converter -.->|"emits PostgreSQL DDL"| node_ddl
node_converter -.->|"offers guidance"| node_runbook

click node_cli "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/cli.py"
click node_runbook "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/runbook.py"
click node_extract "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/extract/__init__.py"
click node_loader "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/inventory/loader.py"
click node_plsql "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/__init__.py"
click node_plsql_walk "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/walk.py"
click node_antlr_lexer "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/_generated/PlSqlLexer.py"
click node_antlr_parser "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/_generated/PlSqlParser.py"
click node_antlr_listener "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/_generated/PlSqlParserListener.py"
click node_rules_catalog "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/rules/__init__.py"
click node_rule_engine "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/rules/engine.py"
click node_rule_sets "https://github.com/muzzammil242/pgrecon/tree/main/src/pgrecon/rules"
click node_effort "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/effort.py"
click node_converter "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/schema.py"
click node_table_emit "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/tables.py"
click node_partition_emit "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/partitions.py"
click node_identifier "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/identifiers.py"
click node_namespace "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/namespace.py"
click node_typemap "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/typemap.py"
click node_plsql_rewrite "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/plsql_rewrite.py"
click node_other_emitters "https://github.com/muzzammil242/pgrecon/tree/main/src/pgrecon/convert"
click node_residue "https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/residue.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_cli,node_runbook toneBlue
class node_extract,node_dump toneAmber
class node_loader,node_sqlite,node_plsql,node_plsql_walk,node_antlr_lexer,node_antlr_parser,node_antlr_listener toneMint
class node_rules_catalog,node_rule_engine,node_rule_sets,node_findings,node_effort toneRose
class node_converter,node_table_emit,node_partition_emit,node_identifier,node_namespace,node_typemap,node_plsql_rewrite,node_other_emitters,node_residue,node_ddl,node_dba toneIndigo
```

## Components

### CLI workflows

- [CLI commands](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/cli.py): `src/pgrecon/cli.py`
- [Migration runbook](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/runbook.py): `src/pgrecon/runbook.py`

### Oracle extraction

- [SQL*Plus script](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/extract/__init__.py): `src/pgrecon/extract/__init__.py`
- **Dump files**

### Inventory and parsing

- [Dump loader](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/inventory/loader.py): `src/pgrecon/inventory/loader.py`
- **SQLite inventory**
- [PL/SQL parsing](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/__init__.py): `src/pgrecon/plsql/__init__.py`
- [Parse tree walker](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/walk.py): `src/pgrecon/plsql/walk.py`
- [Generated lexer](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/_generated/PlSqlLexer.py): `src/pgrecon/plsql/_generated/PlSqlLexer.py`
- [Generated parser](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/_generated/PlSqlParser.py): `src/pgrecon/plsql/_generated/PlSqlParser.py`
- [Parse listener](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/plsql/_generated/PlSqlParserListener.py): `src/pgrecon/plsql/_generated/PlSqlParserListener.py`

### Assessment

- [Rule catalog](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/rules/__init__.py): `src/pgrecon/rules/__init__.py`
- [Rule engine](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/rules/engine.py): `src/pgrecon/rules/engine.py`
- [Rule categories](https://github.com/muzzammil242/pgrecon/tree/main/src/pgrecon/rules): `src/pgrecon/rules`
- **Findings**
- [Effort estimator](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/effort.py): `src/pgrecon/effort.py`

### Schema conversion

- [Schema conversion](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/schema.py): `src/pgrecon/convert/schema.py`
- [Table and partition DDL](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/tables.py): `src/pgrecon/convert/tables.py`
- [Partition emission](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/partitions.py): `src/pgrecon/convert/partitions.py`
- [Identifier translation](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/identifiers.py): `src/pgrecon/convert/identifiers.py`
- [Name registry](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/namespace.py): `src/pgrecon/convert/namespace.py`
- [Type mapping](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/typemap.py): `src/pgrecon/convert/typemap.py`
- [PL/SQL rewriting](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/plsql_rewrite.py): `src/pgrecon/convert/plsql_rewrite.py`
- [Other DDL emitters](https://github.com/muzzammil242/pgrecon/tree/main/src/pgrecon/convert): `src/pgrecon/convert`
- [Conversion residue](https://github.com/muzzammil242/pgrecon/blob/main/src/pgrecon/convert/residue.py): `src/pgrecon/convert/residue.py`
- **PostgreSQL DDL**

### Other components

- **DBA**

## Connections

- DBA → SQL*Plus script: runs script (evidence: `README.md`)
- SQL*Plus script → Dump files: spools files (evidence: `README.md`)
- DBA → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → SQL*Plus script: generates script (evidence: `src/pgrecon/cli.py`)
- CLI commands → Dump loader: loads dump (evidence: `src/pgrecon/cli.py`)
- Dump files → Dump loader: provides input (evidence: `src/pgrecon/inventory/loader.py`)
- Dump loader → SQLite inventory: writes inventory (evidence: `src/pgrecon/inventory/loader.py`)
- Dump loader → Parse tree walker: parses stored units (evidence: `src/pgrecon/inventory/loader.py`)
- Parse tree walker → PL/SQL parsing: uses parser (evidence: `src/pgrecon/plsql/walk.py`)
- PL/SQL parsing → Generated lexer: tokenizes with (evidence: `src/pgrecon/plsql/__init__.py`)
- PL/SQL parsing → Generated parser: parses with (evidence: `src/pgrecon/plsql/__init__.py`)
- Parse tree walker → Parse listener: walks parse events (evidence: `src/pgrecon/plsql/walk.py`)
- CLI commands → Rule engine: runs report (evidence: `src/pgrecon/cli.py`)
- Rule engine → SQLite inventory: queries inventory (evidence: `src/pgrecon/rules/engine.py`)
- Rule engine → Rule catalog: loads rules (evidence: `src/pgrecon/rules/engine.py`)
- Rule catalog → Rule categories: assembles categories (evidence: `src/pgrecon/rules/__init__.py`)
- Rule engine → Findings: produces (evidence: `src/pgrecon/rules/engine.py`)
- CLI commands → Effort estimator: estimates effort (evidence: `src/pgrecon/cli.py`)
- Effort estimator → Findings: uses findings (evidence: `src/pgrecon/effort.py`)
- CLI commands → Schema conversion: converts schema (evidence: `src/pgrecon/cli.py`)
- Schema conversion → SQLite inventory: reads inventory (evidence: `README.md`)
- Schema conversion → Table and partition DDL: emits tables (evidence: `README.md`)
- Schema conversion → Partition emission: emits partitions (evidence: `README.md`)
- Table and partition DDL → Identifier translation: translates names (evidence: `src/pgrecon/convert/tables.py`)
- Table and partition DDL → Type mapping: maps types (evidence: `src/pgrecon/convert/tables.py`)
- Table and partition DDL → Partition emission: uses partition logic (evidence: `src/pgrecon/convert/tables.py`)
- Schema conversion → Other DDL emitters: emits other objects (evidence: `README.md`)
- Other DDL emitters → PL/SQL rewriting: rewrites stored code (evidence: `src/pgrecon/convert/code.py`)
- PL/SQL rewriting → Identifier translation: uses translation helpers (evidence: `src/pgrecon/convert/plsql_rewrite.py`)
- PL/SQL rewriting → Type mapping: uses type mapping (evidence: `src/pgrecon/convert/plsql_rewrite.py`)
- Schema conversion → Name registry: tracks names (evidence: `src/pgrecon/convert/namespace.py`)
- Table and partition DDL → Name registry: claims names (evidence: `src/pgrecon/convert/tables.py`)
- Schema conversion → Conversion residue: records refusals (evidence: `README.md`)
- Schema conversion → PostgreSQL DDL: emits PostgreSQL DDL (evidence: `README.md`)
- Schema conversion → Migration runbook: offers guidance
