# l2-regulasyon/teknofest2022 architecture

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

- Interactive diagram: https://gitdiagram.com/l2-regulasyon/teknofest2022
- Repository: https://github.com/l2-regulasyon/teknofest2022

## Overview

##### Main Components
- Data & Resources:
- Data Directory: Contains input data (legal texts) and resources (e.g., image for the UI/logo).
- Notebooks: Contains multiple Jupyter notebooks which are used for exploratory data analysis, model pipeline testing, text extraction, and specification documentation.

- Model Artifacts:
- Models Directory: Stores model artifacts (e.g., a binary model file “model.cbm” and a TF-IDF vectorizer “tfidf.pickle”). These are produced by the training process and are consumed during inference.

- Core Application Logic:
- Source Code (src folder): Contains modules for constants, utility functions, machine learning model implementation, and evaluation utilities.
- run.py and run_debug.py: Act as main execution entry points for production runs and debugging/training sessions respectively.
- scorer.py: Enables standalone evaluation of predictions against ground truth.

- Environment / Dependencies:
- environment.yml, req.in, and req.txt: Define and manage the project’s dependencies and environment setup (using conda and pip).

##### Establish Relationships and Interactions
- Data Flow:
- Input data (from the “data” directory) is utilized by the execution scripts (run.py/run_debug.py) which call modules in the “src” directory.
- The utilities in src (like utils.py and eval_utils.py) perform preprocessing, feature extraction (including TF-IDF handling using the tfidf.pickle), and model inference by leveraging the model artifact (model.cbm).

- Interaction between Components:
- Execution Scripts (run.py, run_debug.py) → Call functions from src/model.py and src/utils.py to process input data and load necessary artifacts.
- Model Pipeline: Within these modules, constants in src/constants.py and utility functions orchestrate the transformation pipeline (e.g., from raw data to standardized text processing) feeding to the model.
- Evaluation Component: scorer.py and functions in src/eval_utils.py compute scores and statistics compared to the ground truth, with experiments and results documented in the provided Notebooks.

- Development vs. Production:
- Notebooks provide an experimental and iterative interface whereas run.py and run_debug.py offer command-line driven pipeline execution.
- The scorer.py is used as a separate evaluation module that can be invoked once predictions have been generated.

##### Highlighting Architectural Patterns and Design Principles
- Modular Structure:
- Distinct separation between data handling, model logic (prediction/inference/training), and evaluation.
- The use of separate scripts and notebooks supports the iterative development/test cycle.

- Environment Consistency:
- Environment management via environment.yml ensures reproducibility across development and production.

- Pipeline Design:
- The system is designed as a pipeline where each step (data ingestion, preprocessing, model inference, evaluation) is clearly delineated.
- The shared use of utility modules (e.g., constants.py, utils.py) promotes code reusability.

##### Relevant Technologies, Frameworks, and Libraries
- Python and Jupyter Notebooks for experimentation and interactive development.
- Conda for environment management.
- Possibly machine learning libraries (e.g., scikit-learn for TF-IDF or lightgbm/xgboost if model.cbm is built using these) – could be inferred from the file naming and model pipeline notebooks.
- Pip tools (pip-compile) for dependency management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        A["Data Directory & Resources"] 
    end

    %% Execution Layer
    subgraph "Execution Layer"
        R1["run.py"]
        R2["run_debug.py"]
    end

    %% Core Application Logic
    subgraph "Core Application Logic"
        C2["Utilities (src/utils.py)"]
        C1["Constants (src/constants.py)"]
        C3["Model (src/model.py)"]
    end

    %% Model Artifacts
    subgraph "Model Artifacts"
        MA["Models (model.cbm, tfidf.pickle)"]
    end

    %% Evaluation
    subgraph "Evaluation"
        C4["Evaluation Utils (src/eval_utils.py)"]
        SCR["scorer.py"]
    end

    %% Development & Environment
    subgraph "Development & Environment"
        N["Notebooks"]
        Env["Dependencies (environment.yml, req.in, req.txt)"]
    end

    %% Connections
    A --> R1
    A --> R2

    R1 --> C2
    R2 --> C2

    C2 --> C1
    C2 --> C3

    C3 --> MA
    C3 --> C4
    C3 --> SCR

    %% Feedback links from development
    N --> C2
    N --> C3
    N --> SCR

    %% Environment influences execution
    Env -.-> R1
    Env -.-> R2
    Env -.-> C2
    Env -.-> C3
    Env -.-> C4

    %% Styles
    class A data;
    class R1,R2 execution;
    class C1,C2,C3 core;
    class MA artifacts;
    class C4,SCR evaluation;
    class N,Env dev;

    %% Class Definitions (colors and styles)
    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef execution fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef artifacts fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef evaluation fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef dev fill:#FAD7A0,stroke:#7D6608,stroke-width:2px;

    %% Click Events
    click A "https://github.com/l2-regulasyon/teknofest2022/tree/main/data"
    click R1 "https://github.com/l2-regulasyon/teknofest2022/blob/main/run.py"
    click R2 "https://github.com/l2-regulasyon/teknofest2022/blob/main/run_debug.py"
    click C1 "https://github.com/l2-regulasyon/teknofest2022/blob/main/src/constants.py"
    click C2 "https://github.com/l2-regulasyon/teknofest2022/blob/main/src/utils.py"
    click C3 "https://github.com/l2-regulasyon/teknofest2022/blob/main/src/model.py"
    click MA "https://github.com/l2-regulasyon/teknofest2022/tree/main/models"
    click C4 "https://github.com/l2-regulasyon/teknofest2022/blob/main/src/eval_utils.py"
    click SCR "https://github.com/l2-regulasyon/teknofest2022/blob/main/scorer.py"
    click N "https://github.com/l2-regulasyon/teknofest2022/tree/main/notebook"
    click Env "https://github.com/l2-regulasyon/teknofest2022/blob/main/environment.yml"
```
