# ai4sociaty/apex architecture

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

- Interactive diagram: https://gitdiagram.com/ai4sociaty/apex
- Repository: https://github.com/ai4sociaty/apex

## Overview

##### Project type and purpose
- Project Type: Full-stack AI web application for agentic, iterative portrait generation.
- Purpose: Collect user style preferences, generate an initial portrait using a diffusion model (Flux), evaluate with a vision-language model, refine prompts via an LLM, loop until quality thresholds are met, and deliver a polished portrait.

##### File structure
- Top-level directories:
- apex/ – Python package (config, core logic, models, utils; **skip** ui/gradio_interface per instructions)
- backend/ – Two microservice folders: flux_server and vllm_server
- web-app/ – React + TypeScript frontend (Vite build)
- data/ – Persistent JSON profiles (+ uploads folder)
- tests/ – Unit tests for backend core logic
- Key files:
- app.py – Python entry point (“API Gateway”)
- user_form*.py – Legacy CLI forms (deprecated)
- setup.py, requirements.txt – Backend packaging & dependencies
- web-app/src – Components, utils, constants, types

##### README insights
- The high-level workflow:
[User Form Input] → [LLM Style Planner] → [Flux Generation] → [VLM Judge + Scoring] → [LLM Prompt Refiner] → (loop) → [Post-Processing]
- Technologies: React (web-app), Python (apex package), Transformers, Diffusers, PyTorch, CLIP, aesthetic-score
- Microservices: Separate servers for Flux diffusion (flux_server) and vLLM inference (vllm_server)

##### Main components
a. Frontend (blue)
- React web-app (web-app/src)
- Components: PortraitForm, UI elements (Button, Input, etc.)
- Builds via Vite; served on :3000
b. API Gateway / Backend Orchestrator (green)
- app.py exposing HTTP endpoints (e.g., /generate)
- ProfileManager & PromptGenerator (apex/core)
- Config (apex/config/settings.py) and Validators (apex/utils/validators.py)
c. Microservices (orange)
- Flux Diffusion Server (backend/flux_server)
- vLLM Server (backend/vllm_server)
- Communicate over HTTP or RPC; each has its own requirements.txt and startup script
d. Data Storage (gray)
- JSON profiles (data/profiles)
- Uploaded reference images (data/uploads)
e. External ML Libraries & Services (purple)
- Transformers & Diffusers (flux prompt generation & image synthesis)
- CLIP (“clip-by-openai”) for scoring
- aesthetic-score for quality assessment

##### Relationships and interactions
1. User fills form in React → submits via REST call to Python backend
2. Backend (app.py) invokes ProfileManager to validate and save profile JSON
3. PromptGenerator produces initial Flux prompt
4. Backend sends prompt to Flux Server → receives generated image
5. Backend sends image + prompt to vLLM Server for scoring/feedback
6. Based on scores, PromptGenerator refines prompt → repeat steps 4–5
7. Once threshold met, backend applies optional post-processing (e.g., upscaling)
8. Final image returned to frontend for display/download

##### Architectural patterns & design principles
- Separation of concerns: UI vs. orchestration vs. ML inference
- Modular Python package (apex) for core logic, config, models, utils
- Microservices for scalability and independent scaling of heavy ML tasks
- Agentic loop pattern: iterative prompt→generate→evaluate→refine
- Persistence: JSON profiles on disk, enabling reproducibility & local storage

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactApp["React Web App"]:::frontend
        PortraitForm["PortraitForm Component"]:::frontend
        UIElements["UI Elements (Button, Input, Select, Textarea)"]:::frontend
    end

    %% API/Orchestration Layer
    subgraph "API Gateway & Orchestration"
        direction TB
        APIGateway["API Gateway (app.py)"]:::backend
        subgraph "APEX Package"
            direction TB
            ProfileManager["ProfileManager"]:::backend
            PromptGenerator["PromptGenerator"]:::backend
            Config["Config (settings.py)"]:::backend
            Validators["Input Validators"]:::backend
            FileUtils["File Utilities"]:::backend
            ProfileModel["Profile Data Model"]:::backend
        end
    end

    %% Microservices Layer
    subgraph "Microservices"
        direction TB
        FluxServer["Flux Diffusion Server"]:::microservice
        VLLMServer["vLLM Inference Server"]:::microservice
    end

    %% Data Layer
    subgraph "Data Storage"
        direction TB
        Profiles["JSON Profiles"]:::data
        Uploads["Uploaded Images"]:::data
    end

    %% External Libraries
    subgraph "External ML Libraries"
        direction TB
        Transformers["Transformers & Diffusers"]:::external
        CLIP["CLIP Model"]:::external
        Aesthetic["aesthetic-score"]:::external
    end

    %% Connections
    ReactApp -->|"POST /generate"| APIGateway
    PortraitForm --> ReactApp
    UIElements --> ReactApp

    APIGateway -->|validate/save| ProfileManager
    ProfileManager -->|uses| Validators
    ProfileManager -->|uses| FileUtils
    ProfileManager -->|saves to| Profiles

    APIGateway -->|generate prompt| PromptGenerator
    PromptGenerator -->|reads config| Config
    PromptGenerator -->|reads model| ProfileModel

    PromptGenerator -->|HTTP request: Flux prompt| FluxServer
    FluxServer -->|image response| APIGateway

    APIGateway -->|HTTP request: score image| VLLMServer
    VLLMServer -->|score response| APIGateway

    APIGateway -->|refined prompt| PromptGenerator
    APIGateway -->|POST final image| ReactApp

    ProfileManager -->|loads from| Profiles
    APIGateway -->|loads uploads| Uploads

    FluxServer -->|depends on| Transformers
    FluxServer -->|depends on| CLIP
    VLLMServer -->|depends on| CLIP
    APIGateway -->|depends on| Aesthetic

    %% Click Events
    click ReactApp "https://github.com/ai4sociaty/apex/tree/main/web-app/src"
    click PortraitForm "https://github.com/ai4sociaty/apex/blob/main/web-app/src/components/form/PortraitForm.tsx"
    click UIElements "https://github.com/ai4sociaty/apex/blob/main/web-app/src/components/ui/Button.tsx"
    click UIElements "https://github.com/ai4sociaty/apex/blob/main/web-app/src/components/ui/Input.tsx"
    click UIElements "https://github.com/ai4sociaty/apex/blob/main/web-app/src/components/ui/Select.tsx"
    click UIElements "https://github.com/ai4sociaty/apex/blob/main/web-app/src/components/ui/Textarea.tsx"
    click APIGateway "https://github.com/ai4sociaty/apex/blob/main/app.py"
    click ProfileManager "https://github.com/ai4sociaty/apex/blob/main/apex/core/profile_manager.py"
    click PromptGenerator "https://github.com/ai4sociaty/apex/blob/main/apex/core/prompt_generator.py"
    click Config "https://github.com/ai4sociaty/apex/blob/main/apex/config/settings.py"
    click Validators "https://github.com/ai4sociaty/apex/blob/main/apex/utils/validators.py"
    click FileUtils "https://github.com/ai4sociaty/apex/blob/main/apex/utils/file_utils.py"
    click ProfileModel "https://github.com/ai4sociaty/apex/blob/main/apex/models/profile.py"
    click FluxServer "https://github.com/ai4sociaty/apex/blob/main/backend/flux_server/main.py"
    click FluxServer "https://github.com/ai4sociaty/apex/blob/main/backend/flux_server/run_FluxServe.sh"
    click VLLMServer "https://github.com/ai4sociaty/apex/blob/main/backend/vllm_server/servevlm.sh"
    click Profiles "https://github.com/ai4sociaty/apex/tree/main/data/profiles"
    click Uploads "https://github.com/ai4sociaty/apex/tree/main/data/uploads"
    click TestSuite "https://github.com/ai4sociaty/apex/blob/main/tests/test_basic.py"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#2196F3,stroke-width:2px
    classDef backend fill:#E8F5E9,stroke:#4CAF50,stroke-width:2px
    classDef microservice fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef data fill:#ECEFF1,stroke:#607D8B,stroke-width:2px
    classDef external fill:#F3E5F5,stroke:#9C27B0,stroke-width:2px
```
