# fpom/ecco architecture

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

- Interactive diagram: https://gitdiagram.com/fpom/ecco
- Repository: https://github.com/fpom/ecco

## Overview

##### Project type and purpose
- `ecco` is an open-source Python/Cython library (with C++ back-end) for formal modelling and analysis of ecosystems.

##### File structure
- Top-level:
- bin/ → entry points (`ecco.py`, desktop launcher)
- ecco/ → Python packages & Cython modules (`dr`, `lrr`, `mrr`, `model`, `graphs`, `cygraphs`, `bqcm`, `ui`)
- / → C++ libraries (DDD in include/ddd, ITS in include/its) wrapped by Cython (`*.pxd`, `.pyx`)
- doc/ → Jupyter notebooks (documentation & examples)
- setup files (Dockerfile, setup.py, Makefile)
- The architecture is a modular monolith with clear separation between:
- **Frontend / UI** (CLI, GUI, Jupyter notebooks)
- **Core Python/Cython engine** (rule parser, state‐space builder, analyzers)
- **Native libraries** (DDD & ITS C++ code)
- **Visualization & persistence** (NetworkX, Graphviz, pandas)

##### Pull insights from the README
- Core modelling language: reaction‐rules (.rr) → Boolean entities + transition rules
- Static analyses independent of state‐space build
- Interactive exploration via Jupyter + BQPlot + ipywidgets

1. **CLI/Launcher**
- bin/ecco.py → wraps Docker + starts JupyterHub/Notebook
- ecco/__main__.py → `python -m ecco` entry point
2. **Jupyter Server / GUI**
- JupyterHub / Jupyter Notebook process
3. **Python API / Engine**
- ecco/_ui.pyx, ecco/ui.py → interactive widgets & commands
- ecco/dr → `drparse.parse_rules()`, `dr_peg.build_graph()`
- ecco/lrr → `lts.compute_lts()`, `match.perform_matching()`
- ecco/mrr → `lts.compute_mrr_lts()`, `tables.build_transition_tables()`
- ecco/model → `model.match.match_model()`, `record.StateRecord()`
- ecco/cygraphs → `build_cygraph()`, `analyze_graph()`
- ecco/bqcm → `compute_bqm()`
- ecco/rr (top‐level state-space): `compute_state_space()`, `static_analysis()`
4. **Native Libraries**
- **ITS** (include/its): explicit state‐space & model‐checker, wrapped by Cython (`its.pxd`, `itswrap.h`)
5. **External Services & Tools**
- GraphViz (`pydot`) → graph rendering
- NetworkX → graph algorithms
- pandas, NumPy → data handling
- TatSu → grammar parsing for .rr files
- **CLI/Launcher** → starts → **Jupyter Server / GUI**
- **User notebooks or CLI commands** → invoke → **Python API / Engine**
- **Parser modules** (drparse, rrparse) → produce → intermediate rule AST
- **State-space builder** (compute_state_space) → calls →
- DDD library (symbolic)
- ITS library (explicit)
- **Graph modules** (cygraphs, tikz, bqcm) → consume → state-space → produce → visualizations
- **Persistence** (pandas) → stores → analysis results
c. Architectural patterns & design principles:
- **Modular layering**: clear separation of concerns (UI vs engine vs native libs)
- **Cython bridge**: Python <→ C++ for performance-critical parts
- **Plugin‐style grammar**: TatSu for .rr language extensibility
- **Notebook-first**: entire API exposed via notebooks for exploratory analysis
d. Key technologies/frameworks:
- Python 3, Cython
- C++ (DDD, ITS), wrapped via `.pxd`/`.pyx`
- JupyterHub / Jupyter Notebook
- GraphViz, NetworkX, pandas, NumPy, TatSu, BQPlot, ipywidgets

##### Capturing computation functions
- ecco/dr: `parse_rules()`, `dr_peg()`, `drparse.parse()`
- ecco/lrr: `compute_lts()`, `ltsprop()`, `match()`
- ecco/mrr: `compute_mrr_lts()`, `tables.build()`, `pattparse()`
- ecco/rr: `compute_state_space()`, `static_analysis()`
- ecco/cygraphs: `build_graph()`, `to_networkx()`
- ecco/bqcm: `compute_bqm()`
- Cython wrappers: `call_ddd()`, `call_its()`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / Launcher
    subgraph "CLI / Launcher"
        CLI1["bin/ecco.py"]:::python
        CLI2["ecco/__main__.py"]:::python
    end

    %% GUI / Jupyter Integration
    subgraph "GUI / Jupyter Integration"
        GUI1["bin/ecco.desktop"]:::python
        GUI2["ecco/ui.py<br/>(widgets & commands)"]:::python
        GUI3["ecco/_ui.pyx<br/>(Cython UI bridge)"]:::python
    end

    %% Python API / Engine
    subgraph "Python API / Engine"
        %% Reaction‐Rule Parser (dr)
        subgraph "ecco/dr<br/>parse_rules(), dr_peg(), drparse.parse()"
            dr1["ecco/dr/drparse.py"]:::python
            dr2["ecco/dr/dr_peg.py"]:::python
            dr3["ecco/dr/rr.py"]:::python
            dr4["ecco/dr/st.py"]:::python
        end

        %% Local Reaction Semantics (lrr)
        subgraph "ecco/lrr<br/>compute_lts(), ltsprop(), match()"
            lrr1["ecco/lrr/lts.pyx"]:::python
            lrr2["ecco/lrr/ltsprop.py"]:::python
            lrr3["ecco/lrr/match.py"]:::python
            lrr4["ecco/lrr/rrparse.py"]:::python
            lrr5["ecco/lrr/statexpr.py"]:::python
            lrr6["ecco/lrr/st.py"]:::python
            lrr7["ecco/lrr/rr.ebnf"]:::python
        end

        %% Multi‐Reaction Semantics (mrr)
        subgraph "ecco/mrr<br/>compute_mrr_lts(), tables.build(), pattparse()"
            mrr1["ecco/mrr/lts.pyx"]:::python
            mrr2["ecco/mrr/ltsprop.py"]:::python
            mrr3["ecco/mrr/cg.py"]:::python
            mrr4["ecco/mrr/parser.py"]:::python
            mrr5["ecco/mrr/mrrparse.py"]:::python
            mrr6["ecco/mrr/pattparse.py"]:::python
            mrr7["ecco/mrr/tables.py"]:::python
            mrr8["ecco/mrr/mrr.lark"]:::python
        end

        %% Model‐level Matching & Records
        subgraph "ecco/model<br/>match_model(), StateRecord()"
            mod1["ecco/model/match.py"]:::python
            mod2["ecco/model/record.py"]:::python
        end

        %% State‐Space & Static Analysis (rr)
        subgraph "ecco/rr<br/>compute_state_space(), static_analysis()"
            rr1["ecco/rr/__init__.py"]:::python
            rr2["ecco/scm.py"]:::python
            rr3["ecco/tables.py"]:::python
            rr4["ecco/tikz.py"]:::python
        end

        %% Graph Construction & Analysis
        subgraph "Graph Modules<br/>build_graph(), to_networkx()"
            g1["ecco/cygraphs.py"]:::python
            g2["ecco/graphs.py"]:::python
        end

        %% BQM Computation
        bqcm["ecco/bqcm.py<br/>compute_bqm()"]:::python
    end

    %% Native Libraries
    subgraph "Native Libraries"
        DDD["DDD (include/ddd)"]:::native
        ITS["ITS (include/its)"]:::native
    end

    %% External Tools & Services
    subgraph "External Tools"
        GV["GraphViz (pydot)"]:::external
        NX["NetworkX"]:::external
        PD["pandas, NumPy"]:::external
        TS["TatSu"]:::external
    end

    %% Connections
    CLI1 -->|"starts"| GUI1
    CLI2 -->|"-m ecco"| GUI2
    GUI1 -->|"launches"| GUI2
    GUI2 -->|"invokes"| dr1
    GUI3 -->|"invokes"| dr1

    dr1 -->|"parse_rules()"| dr2
    dr2 --> dr3
    dr3 --> dr4
    dr4 -->|"AST"| lrr4

    lrr1 -->|"compute_lts()"| DDD
    lrr1 -->|"compute_lts()"| ITS
    lrr2 --> lrr3
    lrr3 --> lrr5
    lrr5 --> rr1

    mrr1 -->|"compute_mrr_lts()"| DDD
    mrr1 -->|"compute_mrr_lts()"| ITS

    rr1 -->|"compute_state_space()"| DDD
    rr1 -->|"compute_state_space()"| ITS
    rr2 --> rr3
    rr3 --> rr4

    g1 -->|"build_graph()"| rr1
    g1 --> g2
    g2 --> GV
    g2 --> NX

    bqcm --> PD
    bqcm --> NX

    %% Persistence & Parsing
    rr2 --> PD
    dr1 --> TS

    %% Click Events
    click CLI1 "https://github.com/fpom/ecco/blob/main/bin/ecco.py"
    click CLI2 "https://github.com/fpom/ecco/blob/main/ecco/__main__.py"
    click GUI1 "https://github.com/fpom/ecco/blob/main/bin/ecco.desktop"
    click GUI2 "https://github.com/fpom/ecco/blob/main/ecco/ui.py"
    click GUI3 "https://github.com/fpom/ecco/blob/main/ecco/_ui.pyx"
    click dr1 "https://github.com/fpom/ecco/blob/main/ecco/dr/drparse.py"
    click dr2 "https://github.com/fpom/ecco/blob/main/ecco/dr/dr_peg.py"
    click dr3 "https://github.com/fpom/ecco/blob/main/ecco/dr/rr.py"
    click dr4 "https://github.com/fpom/ecco/blob/main/ecco/dr/st.py"
    click lrr1 "https://github.com/fpom/ecco/blob/main/ecco/lrr/lts.pyx"
    click lrr2 "https://github.com/fpom/ecco/blob/main/ecco/lrr/ltsprop.py"
    click lrr3 "https://github.com/fpom/ecco/blob/main/ecco/lrr/match.py"
    click lrr4 "https://github.com/fpom/ecco/blob/main/ecco/lrr/rrparse.py"
    click lrr5 "https://github.com/fpom/ecco/blob/main/ecco/lrr/statexpr.py"
    click lrr6 "https://github.com/fpom/ecco/blob/main/ecco/lrr/st.py"
    click lrr7 "https://github.com/fpom/ecco/blob/main/ecco/lrr/rr.ebnf"
    click mrr1 "https://github.com/fpom/ecco/blob/main/ecco/mrr/lts.pyx"
    click mrr2 "https://github.com/fpom/ecco/blob/main/ecco/mrr/ltsprop.py"
    click mrr3 "https://github.com/fpom/ecco/blob/main/ecco/mrr/cg.py"
    click mrr4 "https://github.com/fpom/ecco/blob/main/ecco/mrr/parser.py"
    click mrr5 "https://github.com/fpom/ecco/blob/main/ecco/mrr/mrrparse.py"
    click mrr6 "https://github.com/fpom/ecco/blob/main/ecco/mrr/pattparse.py"
    click mrr7 "https://github.com/fpom/ecco/blob/main/ecco/mrr/tables.py"
    click mrr8 "https://github.com/fpom/ecco/blob/main/ecco/mrr/mrr.lark"
    click mod1 "https://github.com/fpom/ecco/blob/main/ecco/model/match.py"
    click mod2 "https://github.com/fpom/ecco/blob/main/ecco/model/record.py"
    click rr1 "https://github.com/fpom/ecco/blob/main/ecco/rr/__init__.py"
    click rr2 "https://github.com/fpom/ecco/blob/main/ecco/scm.py"
    click rr3 "https://github.com/fpom/ecco/blob/main/ecco/tables.py"
    click rr4 "https://github.com/fpom/ecco/blob/main/ecco/tikz.py"
    click g1 "https://github.com/fpom/ecco/blob/main/ecco/cygraphs.py"
    click g2 "https://github.com/fpom/ecco/blob/main/ecco/graphs.py"
    click bqcm "https://github.com/fpom/ecco/blob/main/ecco/bqcm.py"
    click DDD "https://github.com/fpom/ecco/tree/main/include/ddd/"
    click ITS "https://github.com/fpom/ecco/tree/main/include/its/"

    %% Styles
    classDef python fill:#cfe2f3,stroke:#084c8d,color:#084c8d
    classDef native fill:#d9ead3,stroke:#38761d,color:#38761d
    classDef external fill:#ffe599,stroke:#bf9000,color:#bf9000
```
