OpenHeart README

The project's README from github.com/AhmadHassan-BTed/OpenHeart. As one markdown file: README.md.

OpenHeart

Succinct Compositional Program Graph (SCPG) Engine & Universal UML 2.5 Studio

Language: Rust License: MIT Live Studio CI Pipeline Security Policy Maintainer: Ahmad Hassan (B-Ted)


OpenHeart SCPG Architecture

A high-performance static program analysis compiler and bidirectional UML 2.5 projection platform built on succinct bitstring trees, memory-mapped binary layouts, and formal graph semantics.

System Overview & Human Intent

Software codebases are living artifacts of human intellect designed to express domain logic, structural design, and operational intent. Traditional static analysis frameworks—such as pointer-heavy Code Property Graphs or lowered compiler IRs—strip away this high-level context, introducing massive memory inflation and pointer-chasing latency that isolate static analysis from real-time developer workflows.

Designed, created, and maintained solely by Ahmad Hassan (B-Ted), OpenHeart introduces the Succinct Compositional Program Graph (SCPG)—a formal 7-tuple graph representation:

$$\mathcal{G} = (V, E, \nu, \varepsilon, \tau, \rho, \Sigma_\Phi)$$

By combining Succinct Balanced Parentheses (BP) trees, Compressed Sparse Row (CSR) control flow graphs, Static Single-Assignment (SSA) data flow representations, and Reduced Ordered Binary Decision Diagram (ROBDD) path summaries, OpenHeart achieves up to 128× memory compression while maintaining $O(1)$ bidirectional source-to-diagram traceability.

Key Technical Features

📊 Complete 19-Diagram Suite Specification

OpenHeart deterministically derives 19 specialized graph projections organized into 3 distinct categories:

1. UML 2.5 Structural Projections (7 Diagrams)

  1. 01 · Class Diagram (package_tree engine): Complete class taxonomy, inheritance hierarchies, interfaces, fields, methods, and member visibility.
  2. 02 · Package Diagram (hierarchical engine): Multi-tier domain namespaces, package containment hierarchy, and inter-package dependencies.
  3. 03 · Component Diagram (hierarchical engine): Modular subsystems, provided/required interfaces, and runtime service wiring.
  4. 04 · Composite Structure Diagram (hierarchical engine): Internal parts, ports, and assembly connectors within composite classifiers.
  5. 05 · Object Diagram (hierarchical engine): Runtime heap instances, object identities, and reference linkages.
  6. 06 · Deployment Diagram (hierarchical engine): Execution environment nodes, devices, and artifact distribution topologies.
  7. 07 · Profile Diagram (hierarchical engine): Metamodels, stereotypes, tagged values, and <<extend>> arrows.

2. UML 2.5 Behavioral Projections (7 Diagrams)

  1. 08 · Sequence Diagram (sequence engine): Lifeline message traces, synchronous/asynchronous dispatches, and activation bars.
  2. 09 · State Machine Diagram (hierarchical engine): Finite states, initial/final pseudostates, transition triggers, and entry/do/exit activities.
  3. 10 · Activity Diagram (hierarchical engine): Business logic workflows, control nodes, decision branches, and swimlanes.
  4. 11 · Use Case Diagram (usecase engine): Actor boundaries, goal-driven use cases, <<include>>, and <<extend>> dependencies.
  5. 12 · Communication Diagram (hierarchical engine): Object collaboration topology with sequenced message ordering numbers.
  6. 13 · Interaction Overview Diagram (hierarchical engine): High-level control flow between nested sequence reference frames (ref sd).
  7. 14 · Timing Diagram (timing engine): Multi-track temporal waveforms, clock events, and state change transitions over time.

3. Compiler Pipeline IRs (5 Diagrams)

  1. 15 · Control Flow Graph (CFG) (hierarchical engine): Basic block partitioning, branching conditions, and loop back-edges.
  2. 16 · Data Flow Graph (DFG) (hierarchical engine): SSA def-use value lineage chains and operand dependencies.
  3. 17 · Control Dependence Graph (CDG) (hierarchical engine): Reversed post-dominator control conditions governing basic block execution.
  4. 18 · Call Graph (CG) (hierarchical engine): Interprocedural call sites, CHA virtual method dispatch resolution, and recursion SCCs.
  5. 19 · ROBDD Saturation (hierarchical engine): Canonical Reduced Ordered Binary Decision Diagram path summaries and exact #SAT path counting.

Master 10-Phase SCPG Compilation Pipeline

Phase 1 (COMPLETED) ──► Phase 2 (COMPLETED) ──► Phase 3 (COMPLETED) ──► Phase 4 (COMPLETED) ──► Phase 5 (COMPLETED)
Lexical Ingestion       BP AST & Succinct      Symbol Table &         CFG CSR & Dominator    SSA Conversion, CDG
& Token Corpus (.tca)   Reduction (.bpa)       Hierarchy (.sta)       Tree (.cfa)            & IFDS Solver (.ssa)

        │
        ▼
Phase 6 (COMPLETED) ──► Phase 7 (COMPLETED) ──► Phase 8 (COMPLETED) ──► Phase 9 (COMPLETED) ──► Phase 10 (COMPLETED)
Inter-procedural        Traceability Index     ROBDD Path             UML Semantic           SCPG Binary (.scpg)
Call Graph (.cga)       Forward/Backward       Summaries (.psa)       Metadata (.uma)        & Query Engine

Binary Artifact Specifications

Phase Artifact Extension Magic Header Core Storage Strategy & Data Structures
Phase 1 .tca TCA\0 SourceFileRecord[], 16-byte TokenRecord[], FNV-1a StringInterner
Phase 2 .bpa BPA\0 Balanced Parentheses bitstrings (u64[]), JumpTable, RankSelectIndex, SparseTableRMQ
Phase 3 .sta STA\0 SymbolRecord[], ScopeNode[], TypeHierarchyEdge[], StdLibManager
Phase 4 .cfa CFA\0 SuccessorCSR, PredecessorCSR, idom[], DominanceFrontierCSR
Phase 5 .ssa SSA\0 SSARecord[], PhiRecord[], DefUseCSR, CDGCSR, IFDS Solvers
Phase 6 .cga CGA\0 CallSiteRecord[], CallEdgeCSR, Andersen Points-To Allocation Sets
Phase 7 .tra TRA\0 Forward Map, Backward Map, Bijective UMLLinkRecord[]
Phase 8 .psa PSA\0 FunctionPSAHeader[], 12-byte Compact ROBDDNodeTable
Phase 9 .uma UMA\0 ClassRecord[], ObjectRecord[], SequenceDiagramRecord[], GoF Pattern Matches
Phase 10 .scpg SCPG Unified Memory-Mapped SCPG Header, Layer Maps, Cross-Layer Indexes

Repository Structure

OpenHeart/
├── src/                          # Native Rust Engine Implementation (10 Compilation Phases)
│   ├── adapters/                 # HTTP REST API Server & Git Clone Ingestion Adapter
│   ├── ast/                      # Phase 2: Balanced Parentheses (BP) AST & Rank/Select LCA Engine
│   ├── cfg/                      # Phase 4: Control Flow Graph (CSR) & Cooper Dominators
│   ├── cg/                       # Phase 6: Call Graph & Andersen Points-To Analysis
│   ├── core/                     # Core Types, Binary Serialization Primitives & Logger
│   ├── ingestion/                # Phase 1: Tree-sitter Lexical Ingestion & Token Corpus (.tca)
│   ├── psa/                      # Phase 8: ROBDD Path Summaries & #SAT Path Counting (.psa)
│   ├── scpg/                     # Phase 10: SCPG Binary Serializer, Query Engine, & Diagram Exporters
│   │   ├── diagram/              # Multi-Format Abstract Factory (JSON, PlantUML, Mermaid, XMI)
│   ├── ssa/                      # Phase 5: SSA Form, CDG, & IFDS Data Flow Solvers (.ssa)
│   ├── symbol/                   # Phase 3: Symbol Table & Scope Graph Engine (.sta)
│   ├── tra/                      # Phase 7: Universal Traceability Index (.tra) & UMLLinks
│   ├── uma/                      # Phase 9: UML Semantic Metadata Artifact (.uma) & Pattern Detectors
│   ├── lib.rs                    # Library Crate Root
│   └── main.rs                   # Engine CLI Entrypoint
│
├── web/                          # OpenHeart Web Studio Portal (100% Free Zero-Backend on GitHub Pages)
│   ├── diagrams/                 # Declarative manifest.json + 19 JSON & PUML Projections
│   ├── js/                       # Modular ES6 Web Engine (Layout, Renderer, Canvas, Editor, File Tree)
│   │   ├── themes/               # Theme Manager & Dynamic Cytoscape Stylesheet Compiler
│   │   ├── uml-card-renderer.js  # Vector SVG Card Generators
│   │   ├── uml-layout.js         # Deterministic Spatial Layout Engines
│   │   ├── puml-parser.js        # Generic PlantUML / Mermaid Parser
│   │   ├── graph-canvas.js       # Interactive Cytoscape Canvas Controller
│   │   ├── editor.js             # Monaco Precision Code Synchronizer
│   │   ├── file-tree.js          # Deterministic File Tree Explorer
│   │   └── github-engine.js      # Zero-Backend In-Browser GitHub Repo Analyzer
│   ├── index.html                # Single-Page Web Studio Application
│   └── style.css                 # Premium Swiss Design System & Dark/Light Themes
│
├── examples/                     # Standard Example & Benchmark Codebases (GoF Patterns, Enterprise Sample)
├── tests/                        # Unit & Integration Test Suite (47 Unit + 22 Integration Tests)
├── scripts/                      # Autonomous Diagram Generators, CI Checkers & Benchmark Harnesses
├── docs/                         # Formal Specifications, Research Papers, & Developer Guides
├── Cargo.toml / Cargo.lock       # Rust Package Dependencies & Build Configuration
└── Makefile                      # Convenient Targets for Build, Test, & Server Launch

🛠️ Quickstart & Local Execution

1. Launch Live Web Studio (No Installation Required)

Access the live studio directly in your browser: OpenHeart Web Studio on GitHub Pages

2. Build Engine

cargo build --release

3. Run Single Codebase Analysis

target/release/openheart analyze ./my_project ./output_dir

4. Launch Web Server & Interactive Web Studio

target/release/openheart server 8080

Then visit http://localhost:8080 in your web browser.

5. Run Integration Test Suite

cargo test --all-targets

Documentation Index

License & Author

Authored, created, and maintained solely by Ahmad Hassan (B-Ted) under the MIT License.

OpenHeart (AhmadHassan-BTed/OpenHeart)

terminal
Searching Database…

1.1K ·GitHub
OpenHeart
What is this?OpenHeart is a static analysis compiler written in Rust that parses source code into a formal graph representation called SCPG (Succinct Compositional Program Graph) and projects it into 19 different diagrams: 14 standard UML 2.5 views plus 5 compiler pipeline IRs.
Is this a browser app or a command-line tool?Both: there is a zero-backend Web Studio that clones and analyzes GitHub repos entirely client-side with no server, and a Rust engine you can build and run locally from the command line for single-codebase analysis or integration tests.
How do I get it running?Open the live OpenHeart Web Studio on GitHub Pages for instant, install-free analysis, or clone the repository and go through the build-engine, run-analysis and launch-web-server steps to use it locally.
What do I need to build and run it locally?Since it's a Rust project, you need the Rust toolchain (cargo) to build the engine; the hosted Web Studio needs nothing beyond a browser since parsing happens client-side.
Which languages can it actually analyze?It has been validated with perfect F1=1.0000 precision across Java, Kotlin, Python, Rust, TypeScript, and C++ codebases, so support is centered on those languages.
What exactly is the SCPG graph model?SCPG is a formal 7-tuple graph representation that combines succinct Balanced Parentheses trees, CSR-based control flow graphs, SSA data flow representations, and ROBDD path summaries instead of a traditional pointer-heavy AST or IR.
How does it get 128x memory compression?It replaces pointer-chasing AST/IR nodes with succinct bitstring encodings (Balanced Parentheses) plus O(1) Jacobson Rank/Select indexes, and serializes everything into CRC-64 verified binary artifacts that are memory-mapped rather than deserialized.
What can the 19 generated diagrams show me?Seven UML structural diagrams (class, package, component, composite structure, object, deployment, profile), seven behavioral diagrams (sequence, state machine, activity, use case, communication, interaction overview, timing), and five compiler IRs (CFG, DFG, CDG, call graph, ROBDD saturation).
What are similar projects?graphify, difftastic, rataflow, graphicle, spinel, CoDiver, ast-grep, GitNexus
Which topics is it in?ast, diagram, tree-sitter, github-pages, code-analysis, software-engineering, graph, data-structures, static-analysis, visualization, computer-science, compiler
Creator
AhmadHassan-BTed
Size
2.6 MB
Stars
1.1K
Updated
CommitOct 10
Age
2mo
Commits · 90 Days