# besser-pearl/besser architecture

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

- Interactive diagram: https://gitdiagram.com/besser-pearl/besser
- Repository: https://github.com/besser-pearl/besser

## Overview

##### Project Type and Purpose
- BESSER is a low-code, open-source platform focused on “low-modeling”. It allows developers and users to define application models using B-UML and then generate target code structures.
- It spans both domain modeling (metamodel definitions) and code generation, integrating various transformation pipelines to serve multiple frameworks (backend, frontend, mobile, and database schema generation).

##### File Structure
- The top-level directories include “besser” (the core Python package) and “docs”, “tests”, etc. Within “besser”, you see several key subcomponents:
- The BUML subpackage contains “metamodel” and “notations”. The metamodel defines various aspects (deployment, gui, object, ocl, state_machine, structural) that represent the different modeling domains.
- Under “notations”, you see directories for deployment, object (PlantUML), ocl, and structural (both DrawIO and PlantUML). These components are responsible for parsing and converting external model representations.
- The “generators” directory is subdivided by target (backend, django, flutter, java, pydantic, python, rdf, rest_api, sql, sql_alchemy, terraform). They take the internal model representation and produce source codes/templates in various forms.
- “Utilities” includes helper scripts, code builders, and notably the web modeling editor, which likely offers an interactive front end.
- There are many templating files (with a .j2 extension) and ANTLR grammar files (.g4) that support the parsing of modeling languages and generation of target code.

##### Key Components to Highlight
a. Core Modeling Engine (B-UML Metamodel):
b. Notations Layer:
c. Code Generators:
d. Utilities and Extensions:
- Supporting tools such as the BumL code builder, image-to-B-UML conversion utilities, and the Web Modeling Editor. These enhance the modeling experience and provide user interfaces.
e. Infrastructure and Integration Components:
- Deployment artifacts such as the Dockerfile and docker-compose.yml indicate that containerization and deployment are integrated. This can be depicted as infrastructure elements interfacing with the core model processor.

##### Relationships and Interactions
- The core metamodel then feeds into the various code generator modules.
- Utilities (like the Web Modeling Editor) interact with both the internal model and the generators to offer an interactive environment.
- External deployment tools (Docker- and Terraform-based infrastructure) are connected to the generated backend and deployment artifacts.
- Tests in the “tests” directory ensure that each component (metamodel, notations, generators) meets reliability and integration standards.

##### Architectural Patterns and Design Principles
- The overall structure follows a layered architecture where separate layers perform parsing (input), modeling (business logic), and code generation (output).
- Use of standardized templates (Jinja2) and clearly defined interfaces between components (for instance, the generator interface in “besser/generators/generator_interface.py”) illustrates modularity and separation of concerns.
- ANTLR-based parsers in the notations layer demonstrate the use of formal grammars to interpret domain-specific languages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Notations Layer
    subgraph "Notations Layer"
        N_DEP["Notations – Deployment"]:::notations
        N_OBJ["Notations – Object (PlantUML)"]:::notations
        N_OCL["Notations – OCL"]:::notations
        N_STRUCT_DRAW["Notations – Structural (DrawIO)"]:::notations
        N_STRUCT_PLANT["Notations – Structural (PlantUML)"]:::notations
    end

    %% B-UML Metamodel Layer
    subgraph "B-UML Metamodel"
        MET_CORE["B-UML Metamodel\n(Core Modeling Engine)"]:::metamodel
        MET_DEP["Metamodel – Deployment Module"]:::metamodel
        MET_GUI["Metamodel – GUI Module"]:::metamodel
        MET_OBJ["Metamodel – Object Module"]:::metamodel
        MET_OCL["Metamodel – OCL Module"]:::metamodel
        MET_STATE["Metamodel – State Machine Module"]:::metamodel
        MET_STRUCT["Metamodel – Structural Module"]:::metamodel
    end

    %% Code Generators Layer
    subgraph "Code Generators"
        GEN_BACK["Code Generator – Backend"]:::generator
        GEN_DJANGO["Code Generator – Django"]:::generator
        GEN_FLUTTER["Code Generator – Flutter"]:::generator
        GEN_JAVA["Code Generator – Java Classes"]:::generator
        GEN_PY["Code Generator – Python Classes"]:::generator
        GEN_PYDANTIC["Code Generator – Pydantic Classes"]:::generator
        GEN_RDF["Code Generator – RDF"]:::generator
        GEN_REST["Code Generator – REST API"]:::generator
        GEN_SQL["Code Generator – SQL"]:::generator
        GEN_SQLAL["Code Generator – SQLAlchemy"]:::generator
        GEN_TERRAFORM["Code Generator – Terraform"]:::generator
    end

    %% Utilities Layer
    subgraph "Utilities & Extensions"
        UTIL_BUML["Utility – BUML Code Builder"]:::utility
        UTIL_IMG["Utility – Image to B-UML Converter"]:::utility
        UTIL_WEB["Utility – Web Modeling Editor"]:::utility
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure"
        INF_DOCKER["Infrastructure – Dockerfile"]:::infra
        INF_DCOMP["Infrastructure – Docker Compose"]:::infra
    end

    %% Connections: Notations to Metamodel
    N_DEP -->|"parses to"| MET_CORE
    N_OBJ -->|"parses to"| MET_CORE
    N_OCL -->|"parses to"| MET_CORE
    N_STRUCT_DRAW -->|"parses to"| MET_CORE
    N_STRUCT_PLANT -->|"parses to"| MET_CORE

    %% Connections: Metamodel core and its modules (internal connection)
    MET_CORE --> MET_DEP
    MET_CORE --> MET_GUI
    MET_CORE --> MET_OBJ
    MET_CORE --> MET_OCL
    MET_CORE --> MET_STATE
    MET_CORE --> MET_STRUCT

    %% Connections: Metamodel to Code Generators
    MET_CORE -->|"feeds"| GEN_BACK
    MET_CORE -->|"feeds"| GEN_DJANGO
    MET_CORE -->|"feeds"| GEN_FLUTTER
    MET_CORE -->|"feeds"| GEN_JAVA
    MET_CORE -->|"feeds"| GEN_PY
    MET_CORE -->|"feeds"| GEN_PYDANTIC
    MET_CORE -->|"feeds"| GEN_RDF
    MET_CORE -->|"feeds"| GEN_REST
    MET_CORE -->|"feeds"| GEN_SQL
    MET_CORE -->|"feeds"| GEN_SQLAL
    MET_CORE -->|"feeds"| GEN_TERRAFORM

    %% Connections: Utilities interact with core and generators
    UTIL_WEB -->|"integrates with"| MET_CORE
    UTIL_WEB -->|"triggers"| GEN_BACK
    UTIL_BUML -->|"assists"| MET_CORE
    UTIL_IMG -->|"converts assets for"| MET_Core

    %% Connections: Infrastructure connects with Code Generators (deployment artifacts)
    GEN_BACK -->|"deployed via"| INF_DOCKER
    GEN_BACK -->|"configured by"| INF_DCOMP
    GEN_TERRAFORM -->|"provisions"| INF_DCOMP

    %% Click Events for Metamodel Layer
    click MET_CORE "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/"
    click MET_DEP "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/deployment/"
    click MET_GUI "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/gui/"
    click MET_OBJ "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/object/"
    click MET_OCL "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/ocl/"
    click MET_STATE "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/state_machine/"
    click MET_STRUCT "https://github.com/besser-pearl/besser/tree/master/besser/BUML/metamodel/structural/"

    %% Click Events for Notations Layer
    click N_DEP "https://github.com/besser-pearl/besser/tree/master/besser/BUML/notations/deployment/"
    click N_OBJ "https://github.com/besser-pearl/besser/tree/master/besser/BUML/notations/objectPlantUML/"
    click N_OCL "https://github.com/besser-pearl/besser/tree/master/besser/BUML/notations/ocl/"
    click N_STRUCT_DRAW "https://github.com/besser-pearl/besser/tree/master/besser/BUML/notations/structuralDrawIO/"
    click N_STRUCT_PLANT "https://github.com/besser-pearl/besser/tree/master/besser/BUML/notations/structuralPlantUML/"

    %% Click Events for Code Generators
    click GEN_BACK "https://github.com/besser-pearl/besser/tree/master/besser/generators/backend/"
    click GEN_DJANGO "https://github.com/besser-pearl/besser/tree/master/besser/generators/django/"
    click GEN_FLUTTER "https://github.com/besser-pearl/besser/tree/master/besser/generators/flutter/"
    click GEN_JAVA "https://github.com/besser-pearl/besser/tree/master/besser/generators/java_classes/"
    click GEN_PY "https://github.com/besser-pearl/besser/tree/master/besser/generators/python_classes/"
    click GEN_PYDANTIC "https://github.com/besser-pearl/besser/tree/master/besser/generators/pydantic_classes/"
    click GEN_RDF "https://github.com/besser-pearl/besser/tree/master/besser/generators/rdf/"
    click GEN_REST "https://github.com/besser-pearl/besser/tree/master/besser/generators/rest_api/"
    click GEN_SQL "https://github.com/besser-pearl/besser/tree/master/besser/generators/sql/"
    click GEN_SQLAL "https://github.com/besser-pearl/besser/tree/master/besser/generators/sql_alchemy/"
    click GEN_TERRAFORM "https://github.com/besser-pearl/besser/tree/master/besser/generators/terraform/"

    %% Click Events for Utilities
    click UTIL_BUML "https://github.com/besser-pearl/besser/blob/master/besser/utilities/buml_code_builder.py"
    click UTIL_IMG "https://github.com/besser-pearl/besser/blob/master/besser/utilities/image_to_buml.py"
    click UTIL_WEB "https://github.com/besser-pearl/besser/tree/master/besser/utilities/web_modeling_editor/"

    %% Click Events for Infrastructure
    click INF_DOCKER "https://github.com/besser-pearl/besser/tree/master/Dockerfile"
    click INF_DCOMP "https://github.com/besser-pearl/besser/blob/master/docker-compose.yml"

    %% Styles
    classDef notations fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef metamodel fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef generator fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef infra fill:#C0C0C0,stroke:#333,stroke-width:2px;
```
