# yelboudouri/emonext architecture

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

- Interactive diagram: https://gitdiagram.com/yelboudouri/emonext
- Repository: https://github.com/yelboudouri/emonext

## Overview

##### Project type and purpose
- This is a deep‐learning research codebase for training a facial emotion recognition model (EmoNeXt) built on top of the ConvNeXt architecture. It’s neither a web service nor a microservices system—it’s a machine‐learning training pipeline.

##### File structure
- Top‐level files and directories:
- README.md               → project description and quick start
- requirements.txt        → Python dependencies (PyTorch, CUDA, etc.)
- models.py               → model definitions (ConvNeXt backbone + STN + SE + self‐attention reg)
- train.py                → main training loop, argument parsing, logging, checkpointing
- scheduler.py            → learning‐rate scheduler or custom training scheduler logic
- scripts/download_dataset.py → data‐download utility for FER2013

##### README for additional insights
- Key components:
- Data: FER2013, downloaded via a helper script
- Model: Adapted ConvNeXt with Spatial Transformer Network and Squeeze‐and‐Excitation blocks
- Training features: mixed‐precision (AMP), configurable batch size, epochs, learning rate, model size
- Dependencies: CUDA, PyTorch 1.13+, any torchvision or auxiliary libs in requirements.txt

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Ingestion
    subgraph "Data Ingestion"
        DL["Dataset Downloader"]:::data
        RD["Raw Data Store"]:::store
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        DT["DataLoader & Transforms"]:::data
    end

    %% Model Definition
    subgraph "Model Definition"
        MD["ConvNeXt + STN + SE + Self-Attention"]:::model
    end

    %% Training Orchestrator
    subgraph "Training Orchestrator"
        TR["train.py: Argument Parser, AMP, Optimizer, Checkpointing, Logging"]:::compute
        SCH["Custom Scheduler"]:::compute
    end

    %% Outputs
    subgraph "Outputs"
        CO["Checkpoints & Logs"]:::store
    end

    %% Platform & Documentation
    subgraph "Platform & Documentation"
        RE["README.md"]:::doc
        REQ["requirements.txt"]:::infra
    end

    %% Compute Environment
    infraEnv["CUDA GPU(s)"]:::infra

    %% Flow connections
    DL -->|downloads FER2013| RD
    RD -->|reads raw images| DT
    DT -->|batches of tensors| MD
    MD -->|forward/backward| TR
    TR -->|calls| SCH
    TR -->|writes| CO
    infraEnv -->|accelerates| TR
    infraEnv -->|accelerates| MD
    REQ -->|provides deps| infraEnv

    %% Click Events
    click DL "https://github.com/yelboudouri/emonext/blob/master/scripts/download_dataset.py"
    click MD "https://github.com/yelboudouri/emonext/blob/master/models.py"
    click TR "https://github.com/yelboudouri/emonext/blob/master/train.py"
    click SCH "https://github.com/yelboudouri/emonext/blob/master/scheduler.py"
    click REQ "https://github.com/yelboudouri/emonext/blob/master/requirements.txt"
    click RE "https://github.com/yelboudouri/emonext/blob/master/README.md"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef compute fill:#90EE90,stroke:#000,stroke-width:1px
    classDef model fill:#FFA500,stroke:#000,stroke-width:1px
    classDef store fill:#EEEEDD,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef doc fill:#FFFFE0,stroke:#000,stroke-width:1px
```
