# uber/piranha architecture

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

- Interactive diagram: https://gitdiagram.com/uber/piranha
- Repository: https://github.com/uber/piranha

## Overview

##### Project Type and Purpose
- PolyglotPiranha is a polyglot, rule-driven code transformation toolset, implemented primarily in Rust with language-agnostic support via Tree-Sitter grammars and exposed as both a CLI and a Python library.
- Its core use case is large-scale automated refactoring (e.g., stale feature-flag cleanup) by loading user-defined rules and executing tree-based analyses + transformations.

##### High-Level Architecture Components
a. Presentation Layers
- CLI Binary (“piranha”) – built from the Rust `crates/core` crate (entry point `main.rs`).
- Python API – a Python package (`polyglot_piranha`), using bindings to the Rust core (via `pyproject.toml` and `polyglot_piranha.pyi`).
- Tree-Sitter Playground – a static web app under `playground/tree-sitter` for grammar and query prototyping.
b. Core Engine
- crates/core – orchestrates rule graph execution, dataflow analyses, cleanup rules, model definitions, Tree-Sitter adapter, and output generation.
- crates/concrete-syntax – defines parsing logic (Pest grammar and Tree-Sitter adapter) and syntax-model layer for matching and rewriting.
- Cleanup Rules – language-specific TOML configs under `crates/core/src/cleanup_rules/<lang>/*` and rule graph edges.
c. Plugin System
- `plugins/` – Python-based transformation plugins (e.g., spark_upgrade) that load custom rule sets and invoke the core engine.
d. Config & Test Artifacts
- Rule Definitions & Edges – `.toml` under `crates/core/src/cleanup_rules` and demo folders.
- Unit & Integration Tests – Rust tests in `crates/*/unit_tests` and Python tests under `tests/test_piranha.py`.
e. CI/CD
- GitHub Actions workflows in `.github/workflows` for building, testing, and releasing both Rust binary and Python package.

##### Component Interactions & Data Flow
1. User invokes CLI or Python API →
2. Core engine loads:
– Concrete syntax module to parse input code into AST.
– Rule Graph (seed rules + outgoing edges) from TOML or programmatic API.
3. Core performs matching, transformation passes, post-processing cleanup.
4. Transformed code is serialized and returned on stdout (CLI) or as Python objects.
5. Plugins can be registered to supply additional rules or drive end-to-end workflows.

##### Key Architectural Patterns
- Modular “crate” layering (separation of parsing vs analysis vs I/O).
- Plugin architecture (Python modules discoverable by core or invoked as separate runners).
- Configuration-driven transformations (TOML-backed rule definitions and edges).
- Dual-interface design (Rust for performance, Python for ease of use).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Binary (piranha)"]:::rust
        PythonAPI["Python API (polyglot_piranha)"]:::python
        Playground["Tree-Sitter Playground"]:::web
    end

    %% Engine Layer
    subgraph "Engine Layer"
        Core["Core Engine"]:::rust
        Syntax["Concrete-Syntax Module"]:::rust
        Rules["Cleanup Rules Store"]:::config
    end

    %% Plugins and Config
    Plugins["Plugin System"]:::python
    Demo["Demo Configurations & Samples"]:::config

    %% Testing
    subgraph "Testing"
        RustUnit1["Rust Unit Tests (concrete-syntax)"]:::test
        RustUnit2["Rust Unit Tests (core models)"]:::test
        RustUnit3["Rust Unit Tests (core df)"]:::test
        Integration["Integration Tests"]:::test
        PyTests["Python Tests"]:::test
    end

    %% CI/CD and Utilities
    CI["CI/CD Workflows"]:::ci
    subgraph "Utilities"
        Viz["Rule Graph Visualization"]:::script
        BuildPlayground["Playground Build Script"]:::script
    end

    %% Data Flow
    CLI -->|"invoke"| Core
    PythonAPI -->|"invoke"| Core
    Core -->|"parse code"| Syntax
    Core -->|"load rules"| Rules
    Core -->|"serialize output"| CLI
    Core -->|"return AST"| PythonAPI
    Playground -->|"fetch grammar + queries"| Syntax
    Plugins -->|"register/invoke"| Core
    Demo -->|"sample configs"| Core

    %% Testing Flows
    RustUnit1 --> Core
    RustUnit2 --> Core
    RustUnit3 --> Core
    Integration --> Core
    PyTests --> PythonAPI

    %% CI/CD Flows
    CI -.-> CLI
    CI -.-> PythonAPI
    CI -.-> Core

    %% Utilities Usage
    Viz --> Rules
    BuildPlayground --> Playground

    %% Click Events
    click CLI "https://github.com/uber/piranha/blob/master/crates/core/src/main.rs"
    click PythonAPI "https://github.com/uber/piranha/blob/master/pyproject.toml"
    click PythonAPI "https://github.com/uber/piranha/blob/master/polyglot_piranha.pyi"
    click Playground "https://github.com/uber/piranha/tree/master/playground/tree-sitter/"
    click Core "https://github.com/uber/piranha/tree/master/crates/core/"
    click Syntax "https://github.com/uber/piranha/tree/master/crates/concrete-syntax/"
    click Rules "https://github.com/uber/piranha/tree/master/crates/core/src/cleanup_rules/"
    click Plugins "https://github.com/uber/piranha/tree/master/plugins/"
    click Demo "https://github.com/uber/piranha/tree/master/demo/"
    click RustUnit1 "https://github.com/uber/piranha/tree/master/crates/concrete-syntax/src/models/concrete_syntax/unit_tests/"
    click RustUnit2 "https://github.com/uber/piranha/tree/master/crates/core/src/models/unit_tests/"
    click RustUnit3 "https://github.com/uber/piranha/tree/master/crates/core/src/df/unit_tests/"
    click Integration "https://github.com/uber/piranha/tree/master/crates/core/src/tests/"
    click PyTests "https://github.com/uber/piranha/blob/master/tests/test_piranha.py"
    click CI "https://github.com/uber/piranha/tree/master/.github/workflows/"
    click Viz "https://github.com/uber/piranha/blob/master/visualize_rules_graph.py"
    click BuildPlayground "https://github.com/uber/piranha/blob/master/playground/tree-sitter/build.py"

    %% Styles
    classDef rust fill:#e0f7e9,stroke:#2e7d32,color:#1b5e20;
    classDef python fill:#e3f2fd,stroke:#1565c0,color:#0d47a1;
    classDef web fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
    classDef config fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef ci fill:#eceff1,stroke:#607d8b,color:#37474f;
    classDef test fill:#ffebee,stroke:#c62828,color:#b71c1c;
    classDef script fill:#fffde7,stroke:#f9a825,color:#f57f17;
```
