# humam-kourani/promoai architecture

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

- Interactive diagram: https://gitdiagram.com/humam-kourani/promoai
- Repository: https://github.com/humam-kourani/promoai

## Overview

##### Main Components
- User Interface / Frontend: Represented by the “app.py” file which launches the Streamlit application.
- Core Library (promoai package): This is the heart of the project, containing the main modules:
- general_utils: Handles common utilities, including LLM connections (llm_connection.py), constants, and application utilities.
- model_generation: Manages the process model generation workflow. It contains generators, code extraction, and validation logic.
- pn_to_powl: Contains functionality to convert process notation into an intermediate “powl” (Probably a process workflow language) representation. It includes submodules for conversion logic, cut detection, weak reachability analysis, and preprocessing.
- prompting: Manages prompt engineering, including the modules for prompt creation, self-evaluation, and providing example “shots” (sample inputs).
- External Dependencies: LLM providers integrated via the utility modules, managed configurations (from requirements.txt, packages.txt) and possibly containerized deployment (via .devcontainer).
- Example Input/Output: The “example_online_shop” directory contains example texts, process descriptions, and responses to demonstrate ProMoAI’s capabilities.

##### Relationships and Interactions
- The Streamlit app (app.py) acts as the entry point for local execution and user interaction. It accepts inputs from users in different formats.
- Once an input is received, the app likely calls into the core library (promoai) where the following interactions occur:
- The “general_utils” folder handles connections to LLMs and environment-specific configurations.
- Depending on the input type, the “prompting” module may generate the appropriate prompt for the LLM.
- The “model_generation” module processes the LLM outputs to extract and generate a valid process model.
- The “pn_to_powl” module might convert or refine these models between formats (e.g., from BPMN/Petri nets to code or other intermediate representations).

##### Architectural Patterns and Design Principles
- Modularity: The separation between utilities, model generation, conversion, and prompting makes the architecture modular.
- Layered Structure: There is a clear division between user interface (front-end) and backend processing.
- Extensibility: By splitting LLM connection logic, prompt engineering, and model generation, it becomes easier to extend or swap components as needed.
- Reusability: The design supports use both as a library (installed via pip) and as a standalone app, which is a versatile pattern for open-source projects.

- “General Utilities” (ai_providers.py, llm_connection.py, constants, etc.)
- “Model Generation” (code_extraction.py, generator.py, validation, etc.)
- “PN to POWL Converter” (converter.py and associated utilities)
- “Prompt Engineering” (prompt_engineering.py, self_evaluation.py, shots modules)
- “Example Inputs/Outputs” block (example_online_shop folder) to show how sample data is used for demonstration/testing.
- Mention that the configuration aspects (.devcontainer, requirements.txt, setup.py) support development and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UI["User Interface (Streamlit App)"]:::ui
    CL["Core Library (promoai)"]:::core
    PE["Prompt Engineering"]:::core
    GE["General Utilities"]:::core
    LLM["External LLM Provider"]:::external
    MG["Model Generation"]:::core
    PN["PN to POWL Conversion"]:::core
    OP["Exported Process Models (BPMN/PNML)"]:::output
    EX["Example Input/Output Data"]:::example

    subgraph "External Dependencies & Configurations"
        DEV[".devcontainer"]:::externalDep
        REQ["requirements.txt"]:::externalDep
        PKG["packages.txt"]:::externalDep
        SET["setup.py"]:::externalDep
    end

    UI -->|"calls"| CL
    CL -->|"initiates"| PE
    CL -->|"contains"| GE
    PE -->|"generates_prompt"| GE
    GE -->|"calls_LLM"| LLM
    LLM -->|"returns_data"| MG
    MG -->|"processes_model"| PN
    PN -->|"exports"| OP
    OP -->|"feedback_loop"| UI

    EX -->|"demonstrates"| UI

    DEV ---|"supports"| GE
    REQ ---|"configures"| CL
    PKG ---|"configures"| CL
    SET ---|"configures"| CL

    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef core fill:#FFEFD5,stroke:#000,stroke-width:1px;
    classDef external fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef output fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef example fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef externalDep fill:#D3D3D3,stroke:#000,stroke-width:1px;

    click UI "https://github.com/humam-kourani/promoai/blob/main/app.py"
    click CL "https://github.com/humam-kourani/promoai/tree/main/promoai"
    click GE "https://github.com/humam-kourani/promoai/tree/main/promoai/general_utils"
    click MG "https://github.com/humam-kourani/promoai/tree/main/promoai/model_generation"
    click PN "https://github.com/humam-kourani/promoai/tree/main/promoai/pn_to_powl"
    click PE "https://github.com/humam-kourani/promoai/tree/main/promoai/prompting"
    click EX "https://github.com/humam-kourani/promoai/tree/main/example_online_shop"
    click DEV "https://github.com/humam-kourani/promoai/blob/main/.devcontainer"
    click REQ "https://github.com/humam-kourani/promoai/blob/main/requirements.txt"
    click PKG "https://github.com/humam-kourani/promoai/blob/main/packages.txt"
    click SET "https://github.com/humam-kourani/promoai/blob/main/setup.py"
```
