# southbridgeai/diagen architecture

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

- Interactive diagram: https://gitdiagram.com/southbridgeai/diagen
- Repository: https://github.com/southbridgeai/diagen

## Overview

##### Analyzing the File Structure
- The top-level contains configuration files (package.json, tsconfig.json, tsup.config.ts) indicative of a Node/TypeScript application.
- The primary source of the logic is within the src directory, with the main entry points in src/index.ts and src/run.ts.
- The “src/diagen” directory houses core modules:
- prompts.ts: Manages the interactive CLI prompts that guide the user in providing input and selecting options.
- visualReflect.ts: Possibly implements additional logic for a “visual reflection” or critique loop.
- Additionally, the “src/utils” folder provides utilities (ai-adapters, constants, helpers, resize) which abstract interactions with external AI services and provide general helper functions.

##### Insights from the README
- It highlights the use of multiple AI models during different stages (generation, fixing, critique), thereby confirming the need to represent iterative loops and external API interactions.
- It outlines two modes of operation: running as a tool (CLI) and using the module programmatically.

a. Main Components to Represent:
- User Interface / CLI: Represents the command-line interface where user input is captured (e.g., src/run.ts and interactive prompts from src/diagen/prompts.ts).
- Core Processing Engine:
– Improvement Module (src/diagen/improve.ts) and Visual Reflection (src/diagen/visualReflect.ts): Provides iterative feedback and refinement through critique loops.
- Utility Components: (src/utils folder) Abstract external AI interactions, file handling, and additional helpers.
- External Services:
– AI APIs (OpenAI, Anthropic, Google/Gemini) which are called during generation, fixing, and critique stages.

b. Relationships and Interactions:
- The CLI (entry point via src/run.ts / index.ts) receives user commands and passes inputs to the core engine.
- The core engine sequentially interacts with its internal modules: generation initiates the process, then the fix module addresses errors, and the improvement module iterates based on visual reflection feedback.
- Each processing module potentially communicates with external AI services (via utility functions in src/utils/ai-adapters.ts) for model-specific operations.

c. Architectural Patterns/Design Principles:
- Layered Architecture: Clearly separate the CLI interface, business logic (core engine with generation, fixing, improvement, rendering), and external utilities/adapters.
- Iterative Feedback Loop: Highlight the cyclic process where the output is improved upon iteratively based on AI feedback.

d. Relevant Technologies & Frameworks:
- TypeScript with Node.js for the application runtime.
- AI models provided by OpenAI, Anthropic, and Google.
- Utility libraries and custom functions (in src/utils) for API communication and auxiliary tasks.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interface Layer
    subgraph "User Interface Layer"
        EP["Entry Point (src/index.ts)"]:::cli
        CLI["CLI Interface (src/run.ts)"]:::cli
        PM["Prompt Manager (src/diagen/prompts.ts)"]:::cli
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        GEN["Generation Module"]:::core
        FIX["Fix Module"]:::core
        IMP["Improvement Module"]:::core
        VR["Visual Reflection Module"]:::core
        REN["Render Module"]:::core
    end

    %% Utility Components
    subgraph "Utility Components"
        UA["AI Adapters"]:::utils
        CONST["Constants"]:::utils
        HELP["Helpers"]:::utils
        RSZ["Resize"]:::utils
    end

    %% External Integration Layer
    subgraph "External Integration Layer"
        OAI["OpenAI"]:::external
        ANTH["Anthropic"]:::external
        GG["Google"]:::external
        D2["d2 Rendering Service"]:::external
    end

    %% Relationships within User Interface Layer
    EP --> CLI
    PM --> CLI

    %% Flow from User Interface to Core Processing
    CLI --> GEN

    %% Core Processing Flow
    GEN --> FIX
    FIX --> IMP
    IMP --> REN
    %% Iterative Loop from Improvement Module back to Fix Module
    IMP -- "iterate" --> FIX

    %% Core Processing interactions with External AI APIs (dashed arrows)
    GEN --- OAI
    GEN --- ANTH
    GEN --- GG
    FIX --- OAI
    FIX --- ANTH
    FIX --- GG
    IMP --- OAI
    IMP --- ANTH
    IMP --- GG

    %% Core Processing interaction with Utility Components (dashed arrow from Generation as example)
    GEN --- UA
    FIX --- UA
    IMP --- UA

    %% Render Module interaction with d2 Rendering Service
    REN --> D2

    %% Styling Classes
    classDef cli fill:#ffeead,stroke:#333,stroke-width:1px;
    classDef core fill:#b3e5fc,stroke:#333,stroke-width:1px;
    classDef utils fill:#d7ccc8,stroke:#333,stroke-width:1px;
    classDef external fill:#c8e6c9,stroke:#333,stroke-width:1px;

    %% Click Events for User Interface / CLI
    click CLI "https://github.com/southbridgeai/diagen/blob/master/src/run.ts"
    click EP "https://github.com/southbridgeai/diagen/blob/master/src/index.ts"
    click PM "https://github.com/southbridgeai/diagen/blob/master/src/diagen/prompts.ts"

    %% Click Events for Core Processing Modules
    click GEN "https://github.com/southbridgeai/diagen/blob/master/src/diagen/generate.ts"
    click FIX "https://github.com/southbridgeai/diagen/blob/master/src/diagen/fix.ts"
    click IMP "https://github.com/southbridgeai/diagen/blob/master/src/diagen/improve.ts"
    click VR "https://github.com/southbridgeai/diagen/blob/master/src/diagen/visualReflect.ts"
    click REN "https://github.com/southbridgeai/diagen/blob/master/src/diagen/render.ts"

    %% Click Events for Utility Components
    click UA "https://github.com/southbridgeai/diagen/blob/master/src/utils/ai-adapters.ts"
    click CONST "https://github.com/southbridgeai/diagen/blob/master/src/utils/constants.ts"
    click HELP "https://github.com/southbridgeai/diagen/blob/master/src/utils/helpers.ts"
    click RSZ "https://github.com/southbridgeai/diagen/blob/master/src/utils/resize.ts"
```
