# logisx/deepessay architecture

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

- Interactive diagram: https://gitdiagram.com/logisx/deepessay
- Repository: https://github.com/logisx/deepessay

## Overview

##### Main components

- Frontend Client – This represents the user interface where essays are submitted. In our project, this is served by HTML, CSS, and JavaScript files from the /app/templates and /app/static directories.

- Web Server (Flask Application) – The core of the application is the Flask server (as seen in app/main.py). This component handles incoming HTTP requests, serves the frontend pages, and routes submissions to the essay grading functionality.

- Text Validation Module – Located at app/text_validation.py, this module handles preliminary checks on the submitted text (e.g., ensuring minimum essay length, warning features).

- Machine Learning Pipeline – Under app/ML (specifically pipeline.py and the model directories as detailed in the README), this component encapsulates the functionality of applying the BERT model to grade essays. Although the file tree provided is slightly truncated (missing the explicit model directories), the README tells us that there are distinct model training paths such as “training_bert_text,” “training_bert_num,” and “training_bert_num_bin.”

- ML Model Artifacts – While these are created and stored during the model training phase (using the provided notebook “IELTS_Grading_with_BERT.ipynb”), they represent essential infrastructure for the prediction service when deployed.

- Deployment and Containerization – The Dockerfile and accompanying assets indicate that the application is containerized. Additionally, with Microsoft Azure being part of the tech stack, the infrastructure might include cloud-deployed services.

##### Relationships and interactions between components

- The Browser (Frontend Client) sends essay submissions to the Flask Web Server.
- The Flask Web Server (via app/main.py and its associated routes) first invokes text validation (from app/text_validation.py) to check the essay.
- Once validated, the server calls the Machine Learning Pipeline (via app/ML/pipeline.py) to perform the BERT-based grading. This part may interact further with model artifacts stored in specific subdirectories.
- The ML Pipeline returns the predicted score, which the Web Server then sends back to the client (displayed in the frontend web pages).
- The Docker container wraps the entire application for consistent deployment, and Microsoft Azure is likely used to host/scale the service.

##### Architectural patterns or design principles

- Separation of concerns: Different modules handle distinct responsibilities—UI rendering, request routing, text validation, and ML inference.
- Modular design: The ML work is separated into its own package (app/ML), making it easy to maintain or extend (for example, by adding more model variants).
- Containerization and cloud deployment: The use of a Dockerfile (and mention of Microsoft Azure) suggests that deployment is designed for scalability and portability.

##### Relevant technologies, frameworks, or libraries

- Flask for the web framework
- TensorFlow, BERT, and Hugging Face Transformers for NLP and Machine Learning
- Docker for containerization and Microsoft Azure for cloud infrastructure
- Frontend technologies such as HTML, CSS, and JavaScript
- Python 3.11 as the programming language platform

##### Elements

- Clearly labeled blocks/components (e.g., “Client Interface,” “Flask Server,” “Text Validation,” “ML Pipeline,” “Model Artifacts,” “Container / Docker,” “Azure Cloud”)
- Annotations or notes that mention key technologies (e.g., “Flask, TensorFlow, BERT”) and architectural decisions (e.g., “separation of validation and prediction”).

##### Detail level

- If space permits, break down the ML pipeline to show how the model is chosen (if multiple variants are retained) and how the pipeline interacts with static assets where model weights might be loaded.

## Diagram (Mermaid)

```mermaid
flowchart TD
    AC["Azure Cloud"]:::cloud
    DC["Docker Container"]:::deployment
    AC -->|"deploys"| DC

    subgraph "Web Application"
        FC["Frontend Client"]:::frontend
        FS["Flask Server"]:::backend
        TV["Text Validation"]:::module
        ML["ML Pipeline"]:::module
        MA["ML Model Artifacts"]:::module

        FC -->|"HTTP_Request"| FS
        FS -->|"validate"| TV
        TV -->|"returns"| FS
        FS -->|"grading_request"| ML
        ML -->|"grading_result"| FS
        FS -->|"HTTP_Response"| FC
        ML -->|"uses"| MA
    end

    DC -->|"hosts"| FC
    DC -->|"hosts"| FS

    click FC "https://github.com/logisx/deepessay/tree/main/app/templates"
    click FC "https://github.com/logisx/deepessay/tree/main/app/static"
    click FS "https://github.com/logisx/deepessay/blob/main/app/main.py"
    click TV "https://github.com/logisx/deepessay/blob/main/app/text_validation.py"
    click ML "https://github.com/logisx/deepessay/blob/main/app/ML/pipeline.py"
    click MA "https://github.com/logisx/deepessay/blob/main/IELTS_Grading_with_BERT.ipynb"
    click DC "https://github.com/logisx/deepessay/tree/main/Dockerfile"

    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef module fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef cloud fill:#F0E68C,stroke:#000,stroke-width:2px;
```
