# glato/emerge architecture

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

- Interactive diagram: https://gitdiagram.com/glato/emerge
- Repository: https://github.com/glato/emerge

## Overview

1. **What this repo is**
   - Emerge is a Python 3 command-line analysis engine that scans a source tree, extracts code structure, computes metrics, and exports graph/data artifacts.
   - The output is both machine-readable files and a bundled interactive HTML visualization.

2. **Primary entrypoints**
   - `emerge.py` is the standalone CLI launcher.
   - `emerge/main.py` and `emerge/core.py` appear to hold the top-level orchestration for parsing CLI flags, loading YAML config, and running analyses.

3. **Configuration boundary**
   - `emerge/config.py` and `emerge/configs/*.yaml` define the analysis contract.
   - Configuration drives source root, language/file filters, ignored dependencies/entities, selected metrics, export targets, and app visualization settings.
   - This is the main boundary between “what to analyze” and the analysis engine itself.

4. **Analysis pipeline**
   - The pipeline is: load config → traverse filesystem → filter files → parse source files → build graph/result objects → compute metrics/stats → export outputs.
   - `emerge/files.py` likely handles recursive file discovery and path-based filtering.
   - `emerge/analysis.py`, `emerge/analyzer.py`, `emerge/core.py`, `emerge/results.py`, and `emerge/stats.py` are the orchestration/result layers around that pipeline.

5. **Language parsing subsystem**
   - `emerge/languages/` contains one parser per supported language, all built on `abstractparser.py`.
   - Supported parsers include C, C++, Go, Groovy, Java, JavaScript, Kotlin, Objective-C, Python, Ruby, Swift, and TypeScript.
   - These parsers are responsible for recognizing files and, where supported, extracting finer-grained entities such as classes or declarative UI constructs.

6. **Graph model and code relationships**
   - `emerge/graph.py` is the central model for dependency-style structures.
   - The repo supports filesystem graphs, file dependency graphs, entity dependency graphs, inheritance graphs, and a “complete” graph that combines dependency and inheritance edges.
   - Graph construction is the bridge from parsed source data to visual analysis and metric computation.

7. **Metrics subsystem**
   - `emerge/metrics/` is split into isolated metric modules behind `abstractmetric.py`.
   - Implemented metrics include SLOC, whitespace complexity, number of methods, fan-in/fan-out, modularity, TF-IDF semantic keywords, and experimental git-based metrics.
   - `metrics/git/` indicates optional mining from a Git repository, separate from the source scan itself.

8. **Analysis outputs and exports**
   - `emerge/export.py` is the output boundary for GraphML, JSON, tabular console/file output, and the D3-oriented data bundle.
   - The export layer takes computed graphs and metrics and materializes them into the chosen formats.
   - `emerge/abstractresult.py` and `emerge/results.py` suggest a structured result object model used across exporters.

9. **Interactive HTML application**
   - `emerge/output/html/` is a prebuilt static web app packaged with the tool.
   - It uses Bootstrap for UI, D3 for force-directed layout, simpleheat for heatmaps, hull for cluster hulls, and dark-mode-switch for theme control.
   - The generated data files feed this app so users can inspect clusters, node relationships, semantic search, and metrics interactively in a browser.

10. **Testing and packaging**
   - `emerge/tests/` contains parser and metric tests plus test data per language, showing that parser output is a key contract.
   - `setup.py`, `requirements.txt`, `MANIFEST.in`, and `Dockerfile` indicate the project is packaged for pip and container use.
   - The repo is structured as a library-plus-CLI tool, with the UI assets bundled rather than served by a separate backend.

Main entry points: [`emerge/metrics/metrics.py`](https://github.com/glato/emerge/blob/dev/emerge/metrics/metrics.py) (Metrics Core), [`emerge/graph.py`](https://github.com/glato/emerge/blob/dev/emerge/graph.py) (Graph Model), [`emerge/analyzer.py`](https://github.com/glato/emerge/blob/dev/emerge/analyzer.py) (Analyzer), [`emerge/languages/abstractparser.py`](https://github.com/glato/emerge/blob/dev/emerge/languages/abstractparser.py) (Parser Base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI & Orchestration"]
  node_node_cli_launcher["Launcher<br/>entrypoint<br/>[emerge.py]"]
  node_node_cli_main["Main CLI<br/>command<br/>[main.py]"]
  node_node_core["Core Flow<br/>orchestrator<br/>[core.py]"]
  node_node_analyzer["Analyzer<br/>analysis engine<br/>[analyzer.py]"]
end

subgraph group_group_config["Config & Scan"]
  node_node_config["Config<br/>settings schema<br/>[config.py]"]
  node_node_defaults["Templates<br/>yaml presets<br/>[default.yaml]"]
  node_node_files["File Scan<br/>filesystem walker<br/>[files.py]"]
end

subgraph group_group_parse["Language Parsing"]
  node_node_abstractparser["Parser Base<br/>parser interface<br/>[abstractparser.py]"]
  node_node_pyparser["Python Parser<br/>language parser<br/>[pyparser.py]"]
  node_node_javaparser["Java Parser<br/>language parser<br/>[javaparser.py]"]
  node_node_cppparser["C/C++ Parser<br/>language parser<br/>[cppparser.py]"]
end

subgraph group_group_model["Graph & Results"]
  node_node_graph["Graph Model<br/>dependency graph<br/>[graph.py]"]
  node_node_results["Results<br/>[results.py]"]
  node_node_abstractresult["Result Base<br/>result interface<br/>[abstractresult.py]"]
  node_node_stats["Stats<br/>summary metrics<br/>[stats.py]"]
end

subgraph group_group_metrics["Metrics"]
  node_node_metrics["Metrics Core<br/>metric registry<br/>[metrics.py]"]
  node_node_sloc["SLOC<br/>metric<br/>[sloc.py]"]
  node_node_faninout["Fan In/Out<br/>metric<br/>[faninout.py]"]
  node_node_tfidf["TF-IDF<br/>metric<br/>[tfidf.py]"]
end

subgraph group_group_output["Export & UI"]
  node_node_export["Export<br/>artifact writer<br/>[export.py]"]
  node_node_html["HTML App<br/>static viewer<br/>[emerge.html]"]
end

node_node_cli_launcher -->|"starts"| node_node_cli_main
node_node_cli_main -->|"loads"| node_node_config
node_node_cli_main -->|"runs"| node_node_core
node_node_core -->|"delegates"| node_node_analyzer
node_node_analyzer -->|"scans"| node_node_files
node_node_config -->|"uses"| node_node_defaults
node_node_files -->|"selects"| node_node_abstractparser
node_node_abstractparser -->|"implements"| node_node_pyparser
node_node_abstractparser -->|"implements"| node_node_javaparser
node_node_abstractparser -->|"implements"| node_node_cppparser
node_node_pyparser -->|"emits"| node_node_graph
node_node_javaparser -->|"emits"| node_node_graph
node_node_cppparser -->|"emits"| node_node_graph
node_node_graph -->|"summarizes"| node_node_stats
node_node_graph -->|"packages"| node_node_results
node_node_results -->|"conforms to"| node_node_abstractresult
node_node_analyzer -->|"computes"| node_node_metrics
node_node_metrics -->|"includes"| node_node_sloc
node_node_metrics -->|"includes"| node_node_faninout
node_node_metrics -->|"includes"| node_node_tfidf
node_node_metrics -->|"feeds"| node_node_stats
node_node_analyzer -->|"exports"| node_node_export
node_node_export -->|"bundles"| node_node_html

click node_node_cli_launcher "https://github.com/glato/emerge/blob/dev/emerge.py"
click node_node_cli_main "https://github.com/glato/emerge/blob/dev/emerge/main.py"
click node_node_core "https://github.com/glato/emerge/blob/dev/emerge/core.py"
click node_node_analyzer "https://github.com/glato/emerge/blob/dev/emerge/analyzer.py"
click node_node_config "https://github.com/glato/emerge/blob/dev/emerge/config.py"
click node_node_defaults "https://github.com/glato/emerge/blob/dev/emerge/configs/default.yaml"
click node_node_files "https://github.com/glato/emerge/blob/dev/emerge/files.py"
click node_node_abstractparser "https://github.com/glato/emerge/blob/dev/emerge/languages/abstractparser.py"
click node_node_pyparser "https://github.com/glato/emerge/blob/dev/emerge/languages/pyparser.py"
click node_node_javaparser "https://github.com/glato/emerge/blob/dev/emerge/languages/javaparser.py"
click node_node_cppparser "https://github.com/glato/emerge/blob/dev/emerge/languages/cppparser.py"
click node_node_graph "https://github.com/glato/emerge/blob/dev/emerge/graph.py"
click node_node_results "https://github.com/glato/emerge/blob/dev/emerge/results.py"
click node_node_abstractresult "https://github.com/glato/emerge/blob/dev/emerge/abstractresult.py"
click node_node_stats "https://github.com/glato/emerge/blob/dev/emerge/stats.py"
click node_node_metrics "https://github.com/glato/emerge/blob/dev/emerge/metrics/metrics.py"
click node_node_sloc "https://github.com/glato/emerge/blob/dev/emerge/metrics/sloc/sloc.py"
click node_node_faninout "https://github.com/glato/emerge/blob/dev/emerge/metrics/faninout/faninout.py"
click node_node_tfidf "https://github.com/glato/emerge/blob/dev/emerge/metrics/tfidf/tfidf.py"
click node_node_export "https://github.com/glato/emerge/blob/dev/emerge/export.py"
click node_node_html "https://github.com/glato/emerge/blob/dev/emerge/output/html/emerge.html"

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_node_cli_launcher,node_node_cli_main,node_node_core,node_node_analyzer toneBlue
class node_node_config,node_node_defaults,node_node_files toneAmber
class node_node_abstractparser,node_node_pyparser,node_node_javaparser,node_node_cppparser toneMint
class node_node_graph,node_node_results,node_node_abstractresult,node_node_stats toneRose
class node_node_metrics,node_node_sloc,node_node_faninout,node_node_tfidf toneIndigo
class node_node_export,node_node_html toneTeal
```

## Components

### CLI & Orchestration

Entry points and top-level control flow.

- [Launcher](https://github.com/glato/emerge/blob/dev/emerge.py): entrypoint · Standalone CLI script that starts the tool. · `emerge.py`
- [Main CLI](https://github.com/glato/emerge/blob/dev/emerge/main.py): command · Parses arguments and hands off to orchestration. · `emerge/main.py`
- [Core Flow](https://github.com/glato/emerge/blob/dev/emerge/core.py): orchestrator · Top-level run coordination and execution wiring. · `emerge/core.py`
- [Analyzer](https://github.com/glato/emerge/blob/dev/emerge/analyzer.py): analysis engine · Coordinates analysis stages across inputs and outputs. · `emerge/analyzer.py`

### Config & Scan

Configuration boundary and filesystem discovery.

- [Config](https://github.com/glato/emerge/blob/dev/emerge/config.py): settings schema · Defines analysis options, filters, and export settings. · `emerge/config.py`
- [Templates](https://github.com/glato/emerge/blob/dev/emerge/configs/default.yaml): yaml presets · Language-specific and default configuration presets. · `emerge/configs/default.yaml`
- [File Scan](https://github.com/glato/emerge/blob/dev/emerge/files.py): filesystem walker · Discovers and filters source files from the configured root. · `emerge/files.py`

### Language Parsing

Per-language source parsers built on a shared parser base.

- [Parser Base](https://github.com/glato/emerge/blob/dev/emerge/languages/abstractparser.py): parser interface · Shared parsing contract for all language implementations. · `emerge/languages/abstractparser.py`
- [Python Parser](https://github.com/glato/emerge/blob/dev/emerge/languages/pyparser.py): language parser · Representative parser for Python source extraction. · `emerge/languages/pyparser.py`
- [Java Parser](https://github.com/glato/emerge/blob/dev/emerge/languages/javaparser.py): language parser · Representative parser for JVM-style class extraction. · `emerge/languages/javaparser.py`
- [C/C++ Parser](https://github.com/glato/emerge/blob/dev/emerge/languages/cppparser.py): language parser · Representative parser for native-language structure extraction. · `emerge/languages/cppparser.py`

### Graph & Results

Core analysis model, results, and statistics.

- [Graph Model](https://github.com/glato/emerge/blob/dev/emerge/graph.py): dependency graph · Central model for filesystem, dependency, inheritance, and combined graphs. · `emerge/graph.py`
- [Results](https://github.com/glato/emerge/blob/dev/emerge/results.py): analysis results · Structured result objects shared across exporters and consumers. · `emerge/results.py`
- [Result Base](https://github.com/glato/emerge/blob/dev/emerge/abstractresult.py): result interface · Common result abstraction used by the output layer. · `emerge/abstractresult.py`
- [Stats](https://github.com/glato/emerge/blob/dev/emerge/stats.py): summary metrics · Aggregates derived counts and summary statistics. · `emerge/stats.py`

### Metrics

Metric plug-ins and their categories.

- [Metrics Core](https://github.com/glato/emerge/blob/dev/emerge/metrics/metrics.py): metric registry · Coordinates metric modules and metric execution. · `emerge/metrics/metrics.py`
- [SLOC](https://github.com/glato/emerge/blob/dev/emerge/metrics/sloc/sloc.py): metric · Source-line counting metric. · `emerge/metrics/sloc/sloc.py`
- [Fan In/Out](https://github.com/glato/emerge/blob/dev/emerge/metrics/faninout/faninout.py): metric · Dependency connectivity metric. · `emerge/metrics/faninout/faninout.py`
- [TF-IDF](https://github.com/glato/emerge/blob/dev/emerge/metrics/tfidf/tfidf.py): metric · Semantic keyword extraction metric. · `emerge/metrics/tfidf/tfidf.py`

### Export & UI

Artifact generation and the bundled HTML viewer.

- [Export](https://github.com/glato/emerge/blob/dev/emerge/export.py): artifact writer · Writes GraphML, JSON, console/tabular output, and UI data bundles. · `emerge/export.py`
- [HTML App](https://github.com/glato/emerge/blob/dev/emerge/output/html/emerge.html): static viewer · Bundled interactive browser UI for graphs, heatmaps, search, and metrics. · `emerge/output/html/emerge.html`

## Connections

- Launcher → Main CLI: starts · The standalone script invokes the main CLI flow.
- Main CLI → Config: loads · CLI parses runtime options and resolves configuration.
- Main CLI → Core Flow: runs · Main hands control to the orchestration layer.
- Core Flow → Analyzer: delegates · Core execution passes into the analysis engine.
- Analyzer → File Scan: scans · Analysis begins by discovering candidate source files.
- Config → Templates: uses · Configuration is seeded by YAML presets and templates.
- File Scan → Parser Base: selects · File types are matched to parser implementations.
- Parser Base → Python Parser: implements · Representative language parser implementation.
- Parser Base → Java Parser: implements · Representative language parser implementation.
- Parser Base → C/C++ Parser: implements · Representative language parser implementation.
- Python Parser → Graph Model: emits · Parsed entities and dependencies are added to graph structures.
- Java Parser → Graph Model: emits · Parsed entities and dependencies are added to graph structures.
- C/C++ Parser → Graph Model: emits · Parsed entities and dependencies are added to graph structures.
- Graph Model → Stats: summarizes · Graph content feeds derived statistics and summaries.
- Graph Model → Results: packages · Graph state is wrapped in result objects.
- Results → Result Base: conforms to · Result objects follow a shared abstraction.
- Analyzer → Metrics Core: computes · The analysis engine runs selected metrics over parsed data.
- Metrics Core → SLOC: includes · Representative size metric module.
- Metrics Core → Fan In/Out: includes · Representative dependency metric module.
- Metrics Core → TF-IDF: includes · Representative semantic metric module.
- Metrics Core → Stats: feeds · Metric outputs contribute to overall statistics.
- Analyzer → Export: exports · Final analysis artifacts are materialized by the exporter.
- Export → HTML App: bundles · Export data feeds the packaged interactive HTML application.
