# mohammedashiqued/artifex_ai_2023-26 architecture

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

- Interactive diagram: https://gitdiagram.com/mohammedashiqued/artifex_ai_2023-26
- Repository: https://github.com/mohammedashiqued/artifex_ai_2023-26

## Overview

##### Project type + purpose (from file tree + README)
**ARTIFEX** is a **small Flask web application** (single service) that serves an HTML UI and calls an **external text-to-image provider (Leonardo AI API)** to generate images. It includes **safety filtering**, **prompt enhancement**, **API key authentication**, and **style/model selection**.

Key evidence:
- `app.py` ⇒ single Flask server, routes + orchestration.
- `templates/index.html` + `static/style.css` ⇒ server-rendered UI + static assets.
- `.env` described ⇒ secrets/config are environment driven.
- `tests/` (`functional`, `models`, `performance`) ⇒ test layers exist even if “models” are likely internal domain objects (not a DB ORM).

This is **not microservices**, not a distributed system internally; the *distributed aspect* is mainly the **external Leonardo API** dependency.

This project benefits a lot from the **component + sequence** views because most complexity is in request processing steps (validation, filtering, enhancement, API call).

##### Architectural patterns/design principles visible in this repo
- **Orchestrator pattern**: `/generate` route orchestrates multiple internal steps.
- **Policy enforcement**: safety filter is a policy gate before external call.
- **Adapter/Client wrapper**: Leonardo API should be treated as an external dependency behind a “LeonardoClient” boundary.
- **Config via environment**: `.env` for secrets (treat as a separate config node / secret store).
- **Separation of concerns (lightweight)**: Templates/static vs backend logic; tests separated by intent (functional/models/performance).

##### Extra: how to reflect the tests folder accurately
- `pytest`/test runner (or whatever is used) →
- Functional tests hit Flask endpoints (may spin server or use Flask test client)
- Model/unit tests call prompt/safety/style functions
- Performance tests measure latency; should mock Leonardo or use a stub to avoid external variability

This is important because it shows **how correctness is enforced** and where external dependencies should be mocked.

##### Final advice for this specific project
- safety policy placement unambiguous,
- external API dependency isolated,
- future refactors (moving to `services/`, `clients/`, `policies/`) straightforward.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% SYSTEM CONTEXT (Top)
  %% =========================
  subgraph "System Context"
    direction TB
    U["User"]:::external
    B["Web Browser"]:::client
    ART["ARTIFEX Web App"]:::backend
    LEO["Leonardo AI API (Text-to-Image)"]:::externalSvc
    ENV["Environment Variables (.env at runtime)"]:::config
    DEV["Developer / CI"]:::external
  end

  U -->|"uses"| B
  B -->|"HTTP GET /"| ART
  B -->|"HTTP POST /generate {prompt,style,params}"| ART
  ART -->|"HTTPS (auth header) text-to-image request"| LEO
  LEO -->|"image_url/data or error"| ART
  ENV -->|"provides secrets/config"| ART
  DEV -->|"runs tests"| ART

  %% =========================
  %% CONTAINERS (Middle)
  %% =========================
  subgraph "Container View"
    direction TB

    subgraph "Client Container"
      direction TB
      C_BROWSER["Browser Runtime"]:::client
      C_UI["Server-rendered Web UI (HTML)"]:::client
      C_CSS["Static CSS Asset"]:::client
    end

    subgraph "Server Container"
      direction TB
      C_FLASK["Flask Server (single service)"]:::backend
    end

    subgraph "External Container"
      direction TB
      C_LEO["Leonardo AI API"]:::externalSvc
    end

    subgraph "Quality / Testing"
      direction TB
      T_RUNNER["Test Runner (pytest)"]:::test
      T_FUNC["Functional / E2E Tests"]:::test
      T_UNIT["Domain / Logic Unit Tests"]:::test
      T_PERF["Performance Tests"]:::test
    end
  end

  C_BROWSER -->|"GET / -> HTML"| C_FLASK
  C_FLASK -->|"renders"| C_UI
  C_BROWSER -->|"GET /static/style.css"| C_FLASK
  C_FLASK -->|"serves"| C_CSS
  C_BROWSER -->|"POST /generate"| C_FLASK
  C_FLASK -->|"HTTPS request"| C_LEO
  C_LEO -->|"HTTPS response"| C_FLASK
  C_FLASK -->|"JSON or HTML response {image_url}"| C_BROWSER

  T_RUNNER -->|"executes"| T_FUNC
  T_RUNNER -->|"executes"| T_UNIT
  T_RUNNER -->|"executes"| T_PERF
  T_FUNC -->|"HTTP-level calls"| C_FLASK
  T_UNIT -->|"calls internal logic"| C_FLASK
  T_PERF -->|"measures latency/throughput"| C_FLASK
  T_FUNC -.->|"should mock external dependency"| C_LEO
  T_PERF -.->|"should stub/mocks to reduce variance"| C_LEO

  %% =========================
  %% COMPONENTS (Inside Flask)
  %% =========================
  subgraph "Component View (Inside Flask Server)"
    direction TB

    subgraph "Routes"
      direction TB
      R_INDEX["Route: GET / (render UI)"]:::backend
      R_GEN["Route: POST /generate (orchestrator)"]:::backend
    end

    VLD["Input Validation + Sanitization"]:::backend
    SAFE["Safety Filter (blocklist / policy gate)"]:::backend
    ENH["Prompt Enhancement (quality + negative prompts)"]:::backend
    STYLE["Style/Model Resolver (maps UI style -> params)"]:::backend
    AUTH["Authentication / API Key Handling (env/.env)"]:::backend
    LCLIENT["Leonardo API Client (HTTP adapter)"]:::backend
    RESP["Response Formatter (image_url/data)"]:::backend
  end

  %% Primary request flow
  C_FLASK -->|"handles"| R_INDEX
  R_INDEX -->|"renders template"| C_UI
  C_FLASK -->|"handles"| R_GEN
  R_GEN -->|"validate {prompt,style,params}"| VLD
  VLD -->|"policy check"| SAFE
  SAFE -->|"enhance prompt"| ENH
  ENH -->|"resolve model params"| STYLE
  STYLE -->|"load API key"| AUTH
  AUTH -->|"call external provider"| LCLIENT
  LCLIENT -->|"HTTPS text-to-image"| C_LEO
  C_LEO -->|"image_url/data"| LCLIENT
  LCLIENT -->|"map result"| RESP
  RESP -->|"return to browser"| C_BROWSER

  %% Failure / edge flows
  VLD -.->|"invalid input -> 400"| RESP
  SAFE -.->|"blocked prompt -> 400/policy error"| RESP
  AUTH -.->|"missing API key -> 401/500"| RESP
  LCLIENT -.->|"timeout/error -> 502/504"| RESP

  %% =========================
  %% GENERATE SEQUENCE (Refined as vertical steps)
  %% =========================
  subgraph "Generate Image: Refined Sequence (Step View)"
    direction TB
    S1["1) Browser submits POST /generate {prompt, style, params}"]:::sequence
    S2["2) Validate & sanitize input"]:::sequence
    S3["3) Safety policy gate (blocklist / negative prompt injection)"]:::sequence
    S4["4) Enhance prompt (quality keywords + negatives)"]:::sequence
    S5["5) Resolve style/model -> Leonardo parameters"]:::sequence
    S6["6) Load API key from environment"]:::sequence
    S7["7) Call Leonardo API (HTTPS)"]:::sequence
    S8["8) Parse response -> image_url/data"]:::sequence
    S9["9) Return response to browser; UI displays image"]:::sequence
  end

  C_BROWSER -->|"triggers"| S1
  S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 --> S9

  S3 -.->|"blocked -> error response"| S9
  S7 -.->|"provider failure -> error response"| S9
  S6 -.->|"no key -> error response"| S9

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click C_FLASK "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click ART "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click R_INDEX "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click R_GEN "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click VLD "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click SAFE "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click ENH "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click STYLE "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click AUTH "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click LCLIENT "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click RESP "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/app.py"
  click C_UI "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/templates/index.html"
  click C_CSS "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/static/style.css"
  click T_FUNC "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/tests/test_functional.py"
  click T_UNIT "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/tests/test_models.py"
  click T_PERF "https://github.com/mohammedashiqued/artifex_ai_2023-26/blob/main/tests/test_performance.py"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#D6ECFF,stroke:#1E5AA8,stroke-width:1.2px,color:#0B2A4A
  classDef backend fill:#DFF7E3,stroke:#1C7A3A,stroke-width:1.2px,color:#0F2E19
  classDef external fill:#FFFFFF,stroke:#6B7280,stroke-width:1.2px,color:#111827
  classDef externalSvc fill:#FFE4C7,stroke:#B45309,stroke-width:1.2px,color:#4A2A06
  classDef config fill:#E5E7EB,stroke:#374151,stroke-width:1.2px,color:#111827
  classDef test fill:#F3E8FF,stroke:#6D28D9,stroke-width:1.2px,color:#2E1065
  classDef sequence fill:#FFF7ED,stroke:#9A3412,stroke-width:1.2px,color:#431407
```
