# evanzhoudev/open-genmoji architecture

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

- Interactive diagram: https://gitdiagram.com/evanzhoudev/open-genmoji
- Repository: https://github.com/evanzhoudev/open-genmoji

## Overview

##### Project Type and Purpose
- Open Genmoji is an image generation tool that reproduces Apple’s Genmoji functionality using open technology. It does so by applying fine-tuned LoRA models onto a base image generation model.
- It supports prompt enrichment through “Prompt Assist” (using predefined metaprompts) and integrates with external services like HuggingFace for model weight downloads and LM Studio/mflux for image generation.
- Additionally, it provides tools for finetuning and postprocessing (like image resizing), so think of it as a modular application that “glues” together various scripts, models, and workflows for custom emoji creation.

##### File Structure & Architectural Clues
- Top-level files:
- README.md: Contains usage instructions, setup, and integration details.
- download.py, generateImage.py, genmoji.py, promptAssistant.py, resize.py: Core scripts serving different purposes (download, generation, prompt handling, postprocessing).
- Directories:
- assets: Holds sample images and banners (mostly for presentation and documentation).
- lora: Contains LoRA models, a template (LORA_TEMPLATE.md), readme, and info.json which maps metaprompts to specific models.
- metaprompt: Houses metaprompt files (e.g., open-genmoji.md) which are used by the Prompt Assist feature.
- finetuning: Contains scripts and configurations (various JSON files and related scripts) for training or fine-tuning the models.
- Configuration Files:
- Files like mise.toml and JSON configs in finetuning/config provide operational parameters that may influence model behavior and training processes.

##### Main Components and Their Relationships
A. External Services & Dependencies:
- HuggingFace Hub: Used to download LoRA weight files (via download.py).
- LM Studio and mflux: These tools handle integration with the underlying image generation model (Flux.1 Dev) and provide an interface for both manual prompt generation and the Prompt Assist workflow.
- Python Environment with relevant libraries (huggingface_hub, pillow, requests, mflux) enabling script execution.

B. Core Functional Modules:
1. LoRA Management:
– The lora directory (with its README.md, info.json, and templates) manages available LoRA models.
– download.py is used to fetch these models from HuggingFace.
– Finetuning scripts under the finetuning directory support model training and emoji list management.

2. Prompt Engineering / Prompt Assist:
– The metaprompt directory holds files that define metaprompts.
– promptAssistant.py (and genmoji.py which makes use of LM Studio for prompt refinement) orchestrates the process where a raw user prompt is enhanced before being dispatched to the image generation module.

3. Image Generation & Postprocessing:
– Scripts like generateImage.py and genmoji.py interface directly with mflux (and LM Studio if integrated) to generate emoji images based on refined prompts.
– Once generated, resize.py (using Pillow) performs important postprocessing (upscaling with anti-aliasing) so that the final image is in the right format and resolution for use as a sticker/emoji.

C. Interaction Flow:
- User Input → (Optional) Prompt Assist:
- Raw user prompt goes into the Prompt Assist module that uses metaprompts to produce an enhanced prompt.
- Enhanced Prompt → Image Generation Module:
- The refined prompt is passed to mflux (or directly to the image generation model) along with LoRA information, calling scripts like genmoji.py or generateImage.py.
- Image Output → Postprocessing:
- The generated image is further processed (resized using resize.py) before being exported for user consumption.
- LoRA Management & Finetuning:
- The download.py script interacts with HuggingFace to download LoRA files. Finetuning scripts prepare and adjust models as needed.

##### Architectural Patterns and Design Choices
- Modularity: Each major function (download, prompt-assist, image generation, postprocessing) is separated into its own script or directory. This separation helps isolate concerns.
- Extensibility: The project is built with clear extension points (e.g., new LoRA support via the lora directory, adding new metaprompts, or additional finetuning configurations).
- Service Integration: Integration with external services (HuggingFace, LM Studio, mflux) is explicit and divided in the workflow, signifying that multiple external APIs and tools collaborate to produce the final images.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry and Exit
    UserInput["User Input"]:::internal
    Final["Final Emoji Output"]:::internal

    %% External Services
    HF["HuggingFace Hub"]:::external
    LMS["LM Studio/mflux"]:::external
    PY["Python Environment"]:::external

    %% Subgraph: Prompt Assist Module
    subgraph "Prompt Assist Module"
        PA1["promptAssistant.py"]:::internal
        PA2["metaprompt Directory"]:::resource
    end

    %% Subgraph: Image Generation Module
    subgraph "Image Generation Module"
        Gen1["genmoji.py"]:::internal
        Gen2["generateImage.py"]:::internal
    end

    %% Subgraph: LoRA Management
    subgraph "LoRA Management"
        LM1["download.py"]:::internal
        LM2["lora Directory"]:::resource
    end

    %% Subgraph: Postprocessing
    subgraph "Postprocessing"
        R1["resize.py"]:::internal
    end

    %% Finetuning Tools (as a separate component)
    FT["Finetuning Tools"]:::resource

    %% Connections
    UserInput -->|"input_prompt"| PA1
    PA1 -->|"enhances_prompt"| Gen1
    PA2 --- PA1

    %% LoRA integration into Image Generation
    LM1 -->|"provides_LoRA"| Gen1
    LM2 -->|"contains_models"| Gen1
    FT -->|"tunes_models"| LM2

    %% External service integrations
    LM1 -->|"downloads_from"| HF
    Gen1 -->|"integrates_with"| LMS

    %% Image Generation to Postprocessing Workflow
    Gen1 -->|"produces_image"| R1
    R1 -->|"finalizes_image"| Final

    %% Python Environment supporting internal modules
    PY -->|"supports"| PA1
    PY -->|"supports"| Gen1
    PY -->|"supports"| LM1
    PY -->|"supports"| R1

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#CA6F1E,stroke-width:2px;
    classDef resource fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;

    %% Click Events
    click LM1 "https://github.com/evanzhoudev/open-genmoji/blob/main/download.py"
    click LM2 "https://github.com/evanzhoudev/open-genmoji/tree/main/lora/"
    click PA1 "https://github.com/evanzhoudev/open-genmoji/blob/main/promptAssistant.py"
    click PA2 "https://github.com/evanzhoudev/open-genmoji/tree/main/metaprompt/"
    click Gen1 "https://github.com/evanzhoudev/open-genmoji/blob/main/genmoji.py"
    click Gen2 "https://github.com/evanzhoudev/open-genmoji/blob/main/generateImage.py"
    click R1 "https://github.com/evanzhoudev/open-genmoji/blob/main/resize.py"
    click FT "https://github.com/evanzhoudev/open-genmoji/tree/main/finetuning/"
```
