# jbilcke-hf/ai-comic-factory architecture

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

- Interactive diagram: https://gitdiagram.com/jbilcke-hf/ai-comic-factory
- Repository: https://github.com/jbilcke-hf/ai-comic-factory

## Overview

- Frontend/UI Layer: Represent the Next.js application that includes:
– The “src/app/interface” folder with screens such as login, about, grid, panel, settings, and other interactive components.
– Layout components (found in src/app/layouts) and global styling files.
- Engine/Business Logic: Highlight the modular “engine” (src/app/engine) which covers:
– Core functionalities: caption generation, censorship, community-based decisions, forbidden content check, presets, and the render function.
- Query Layer: Represent the “src/app/queries” directory:
– This layer encapsulates requests to external APIs and defines functions like getSystemPrompt, getUserPrompt, and various “predict…” queries for LLM interaction.
- Utility/Library Layer:
– Include the “src/lib” directory and the “src/types.ts” file to emphasize helper functions that support image processing (loadImage, cropImage, getImageDimension), JSON parsing, and other utilities.
- External API Services:
– LLM API: Outline external language model providers – the various engines (Inference API, Inference Endpoint, OpenAI, GROQ, Anthropic) as configurable endpoints defined via environment variables.
– Rendering API: Similarly, represent external image-generation services (Replicate, VideoChain, or alternative SDXL APIs) that are used to create comic panels.
- Configuration & Environment:
– The .env file, Next configuration (next.config.js), and Dockerfile (for containerized deployment) are key parts of the architectural configuration.

##### Relationships and data flow
- From the end user’s browser, requests travel to the Next.js–powered frontend.
- The UI components interact with the client-side state (managed in “src/app/store”) and dispatch events that trigger queries.
- The “queries” layer calls the appropriate external LLM or rendering APIs based on the environment configuration and user settings.
- The “engine” layer processes the API responses. For example, it may modify captions, apply censorship, or combine responses to structure a comic story.
- Utility functions (in “lib”) are used throughout to process data (e.g., image transformation, JSON cleaning, cryptographic functions).
- Finally, the results are rendered on the UI via React components.

##### Architectural patterns and design principles
- Modular design & separation of concerns: The system clearly segregates UI, business logic, API-interaction (queries), and helper functions.
- Configurability: The use of environment variables allows swapping between different LLM and rendering providers, meaning external integrations are “plug and play.”
- Reusability: The common UI components and libraries are designed so that consistent behavior can be maintained across different parts of the application.

##### Technology and framework details
- Next.js (and React): Used for the frontend and server-side rendering components.
- Tailwind CSS: Suggested by the tailwind.config.js.
- Docker: Indicated by the Dockerfile for containerization.
- Various API providers (e.g., HuggingFace, OpenAI) are integrated via REST or similar API calls from the query layer.

##### Elements
- Each component should have a clear label (e.g., “Frontend – UI Components,” “Engine – Comic Processing,” “Queries – API Handlers,” “External LLM API,” “External Rendering API”).

- Top (Client Side):
– Browser / User → Next.js Frontend → UI Components (with distinct elements for login, panels, settings, etc.)
- Middle (Application Logic):
– “Engine” modules that process comic-related logic.
– “Queries” acting as service brokers calling external APIs.
– Shared utilities and state managing layers.
- Bottom (External Services):
– LLM API providers (Hugging Face’s Inference API, OpenAI, etc.)
– Rendering API endpoints (Replicate, VideoChain, or other SDXL-based services)
- Supporting infrastructure:
– Environment configuration (.env), Docker container, and overall deployment configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level
    Browser("User/Browser"):::external
    NextJS("Next.js Frontend"):::frontend

    Browser -->|"requests"| NextJS

    %% Frontend/UI Layer Subgraph
    subgraph "Frontend/UI Layer"
        Interface["Interface Screens"]:::frontend
        Layouts["Layouts"]:::frontend
        GlobalStyles["Global Styles"]:::frontend
        UIComponents["UI Components"]:::frontend
        Icons["Icons"]:::frontend
        ClientState["Client State"]:::frontend
    end

    NextJS -->|"renders"| Interface
    NextJS --> Layouts
    NextJS --> GlobalStyles
    NextJS --> UIComponents
    NextJS --> Icons
    UIComponents --> ClientState

    %% Query Layer Subgraph
    subgraph "Query Layer"
        Q1["getSystemPrompt"]:::queries
        Q2["getUserPrompt"]:::queries
        Q3["predict"]:::queries
        Q4["predictNextPanels"]:::queries
        Q5["predictWithAnthropic"]:::queries
        Q6["predictWithGroq"]:::queries
        Q7["predictWithHuggingFace"]:::queries
        Q8["predictWithOpenAI"]:::queries
    end

    %% Engine/Business Logic Subgraph
    subgraph "Engine/Business Logic"
        E1["Caption Generation"]:::engine
        E2["Censorship"]:::engine
        E3["Community Decision"]:::engine
        E4["Forbidden Check"]:::engine
        E5["Presets"]:::engine
        E6["Render Function"]:::engine
    end

    %% Utility/Library Layer Subgraph
    subgraph "Utility/Library Layer"
        U1["Utilities"]:::utility
        U2["Types"]:::utility
    end

    %% Configuration & Environment Subgraph
    subgraph "Configuration & Environment"
        C1[".env"]:::config
        C2["Next Config"]:::config
        C3["Dockerfile"]:::config
        C4["Tailwind Config"]:::config
    end

    %% External API Services Subgraph
    subgraph "External API Services"
        ExLLM["External LLM API Providers"]:::external
        ExRender["External Rendering API Providers"]:::external
    end

    %% Data Flow Connections
    UIComponents -->|"triggers"| Q1
    ClientState --> Q1

    %% Simulate query operations vertical flow
    Q1 --> Q2
    Q2 --> Q3
    Q3 --> Q4
    Q4 --> Q5
    Q5 --> Q6
    Q6 --> Q7
    Q7 --> Q8

    %% Queries call External APIs
    Q3 ---|"calls"| ExLLM
    ExLLM ---|"response"| Q3
    Q4 ---|"calls"| ExRender
    ExRender ---|"response"| Q4

    %% Query results feed into Engine processing
    Q8 -->|"passes data"| E1

    %% Engine processing chain
    E1 --> E2
    E2 --> E3
    E3 --> E4
    E4 --> E5
    E5 --> E6

    %% Engine uses Utility functions
    E6 --- U1
    E6 --- U2

    %% Engine & Query layers use Configuration
    C1 --- Q1
    C2 --- Q1
    C3 --- Q1
    C4 --- Q1

    C1 --- E1
    C2 --- E1
    C3 --- E1
    C4 --- E1

    %% Flow back to Frontend UI for display
    E6 -->|"renders comic"| UIComponents

    %% Click Events for Frontend/UI Layer
    click Interface "https://github.com/jbilcke-hf/ai-comic-factory/tree/main/src/app/interface"
    click Layouts "https://github.com/jbilcke-hf/ai-comic-factory/tree/main/src/app/layouts"
    click GlobalStyles "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/globals.css"
    click UIComponents "https://github.com/jbilcke-hf/ai-comic-factory/tree/main/src/components/ui"
    click Icons "https://github.com/jbilcke-hf/ai-comic-factory/tree/main/src/components/icons"

    %% Click Events for Engine/Business Logic
    click E1 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/engine/caption.ts"
    click E2 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/engine/censorship.ts"
    click E3 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/engine/community.ts"
    click E4 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/engine/forbidden.ts"
    click E5 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/engine/presets.ts"
    click E6 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/engine/render.ts"

    %% Click Events for Query Layer
    click Q1 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/getSystemPrompt.ts"
    click Q2 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/getUserPrompt.ts"
    click Q3 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/predict.ts"
    click Q4 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/predictNextPanels.ts"
    click Q5 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/predictWithAnthropic.ts"
    click Q6 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/predictWithGroq.ts"
    click Q7 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/predictWithHuggingFace.ts"
    click Q8 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/app/queries/predictWithOpenAI.ts"

    %% Click Events for Utility/Library Layer
    click U1 "https://github.com/jbilcke-hf/ai-comic-factory/tree/main/src/lib"
    click U2 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/src/types.ts"

    %% Click Events for Configuration & Environment
    click C1 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/.env"
    click C2 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/next.config.js"
    click C3 "https://github.com/jbilcke-hf/ai-comic-factory/tree/main/Dockerfile"
    click C4 "https://github.com/jbilcke-hf/ai-comic-factory/blob/main/tailwind.config.js"

    %% Styles
    classDef frontend fill:#CDEBFF,stroke:#036,stroke-width:2px;
    classDef engine fill:#D1FFD1,stroke:#0A3,stroke-width:2px;
    classDef queries fill:#FFE7BA,stroke:#E66,stroke-width:2px;
    classDef utility fill:#FFF5BA,stroke:#BA3,stroke-width:2px;
    classDef config fill:#FFD1D1,stroke:#C33,stroke-width:2px;
    classDef external fill:#E0E0E0,stroke:#999,stroke-width:2px;
```
