# leyber91/ai_canvas architecture

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

- Interactive diagram: https://gitdiagram.com/leyber91/ai_canvas
- Repository: https://github.com/leyber91/ai_canvas

## Overview

##### Core Components
- Frontend: Represent the client-side aspects, including the HTML, CSS, and JavaScript folders (note the many JavaScript subdirectories for handling API communication, conversation panels, dialogs, graph managers, UI components, workflows, and theme management). Highlight that Cytoscape.js is used for graph visualization.
- API Controllers (e.g., chat_controller, execute_controller, graph_controller, etc.) which expose endpoints for node operations.
- Domain Services (e.g., chat_service, edge_service, graph_service, model_service, node_service) handling business logic.
- Infrastructure layer: This includes database interactions (via SQLAlchemy), AI provider integrations (Ollama and Groq through ai_providers), and possibly some external API coupling.
- Core and Utility components: Configurations, exception handling, streaming utilities, and similar constructs.
- External Services: Represent the external dependencies such as:
- Ollama (running locally) and its real-time response streaming.
- Groq API, which is an external service integrated via environment configurations.

##### Relationships and Interactions
- From the Frontend (UI) to the Backend APIs (which are defined within the “app/api/controllers”).
- How the backend calls domain services, which in turn utilize the infrastructure (database repositories and AI provider interfaces).
- Workflow execution: Demonstrate how nodes are connected in a directed acyclic graph. Include an element for the graph analysis using NetworkX (for topological sorting and cycle detection) as well as the sequential workflow execution logic.
- That the real-time streaming is handled over a WebSocket or similar channels (Flask-SocketIO).

##### Architectural Patterns & Design Principles
- MVC/MVT Influences: The API (controllers), domain models, and templating (in backend/templates and static assets) can be mapped to a similar pattern.
- Modular Design: Indicate that both the client-side (organized in modules, core components, and UI managers) and server-side (dividing responsibilities among controllers, services, and infrastructure) follow modular design.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend Layer
    subgraph "Frontend (UI & Presentation)"
        F1["UI HTML/CSS (index.html)"]
        F2["JavaScript Modules (API, UI, Graph & Tools)"]
        F3["Cytoscape.js (Graph Visualization)"]
    end

    %% Backend Layer
    subgraph "Backend (Flask Server)"
        B1["Flask Server"]
        %% API Controllers
        subgraph "API Controllers"
            A1["chat_controller.py"]
            A2["edge_controller.py"]
            A3["execute_controller.py"]
            A4["graph_controller.py"]
            A5["main_controller.py"]
            A6["models_controller.py"]
            A7["node_controller.py"]
        end
        %% Domain Services
        subgraph "Domain Services"
            D1["chat_service.py"]
            D2["edge_service.py"]
            D3["graph_service.py"]
            D4["model_service.py"]
            D5["node_service.py"]
        end
        %% Infrastructure
        subgraph "Infrastructure"
            subgraph "AI Provider Integrations"
                I1["base.py"]
                I2["groq_provider.py"]
            end
            subgraph "Database Interactions"
                I3["models.py"]
                I4["repositories.py"]
            end
        end
        %% Core & Utilities
        subgraph "Core & Utilities"
            C1["configurations & init"]
            C2["exceptions.py"]
            C3["streaming.py"]
        end
        %% Additional Services
        subgraph "Additional Services"
            S1["graph_service.py"]
            S2["groq_service.py"]
            S3["ollama_service.py"]
            S4["topology_service.py"]
            S5["workflow_service.py"]
        end
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        DDP1["Data Models (conversation.py, edge.py, graph.py, message.py, node.py)"]
        DDP2["Database (ai_canvas.sqlite)"]
    end

    %% External Services
    subgraph "External Services"
        X1["Ollama (Real-time Streaming)"]
        X2["Groq API"]
    end

    %% Connections from Frontend to Backend
    F2 -->|"requests"| A1
    F2 -->|"requests"| A2
    F2 -->|"requests"| A3
    F2 -->|"requests"| A4
    F2 -->|"requests"| A5
    F2 -->|"requests"| A6
    F2 -->|"requests"| A7

    %% Backend API Controllers call Domain Services
    A1 -->|"calls"| D1
    A2 -->|"calls"| D2
    A3 -->|"calls"| D3
    A4 -->|"calls"| D3
    A5 -->|"calls"| D1
    A6 -->|"calls"| D4
    A7 -->|"calls"| D5

    %% Domain Services use Infrastructure for DB and AI integrations
    D1 -->|"uses"| I3
    D2 -->|"uses"| I3
    D3 -->|"uses"| I4
    D4 -->|"uses"| I3
    D5 -->|"uses"| I3

    %% Domain Services call Additional Services for AI processing and workflow
    D1 -->|"calls"| S3
    D3 -->|"calls"| S2

    %% Additional Services integrate with Infrastructure AI Providers
    S2 -->|"integrates"| I2
    S3 -->|"integrates"| I1

    %% Infrastructure Database Interactions persist data to Data Persistence
    I3 -->|"persists"| DDP2
    I4 -->|"persists"| DDP2

    %% Flask Server configuration and streaming
    B1 -->|"init"| C1
    B1 -->|"initiates"| C3
    C3 -->|"streams to"| F3

    %% Flask Server executes additional services
    B1 -->|"executes"| S1
    B1 -->|"analyzes"| S4
    B1 -->|"manages"| S5

    %% External Services triggered by Additional Services
    S3 -->|"calls"| X1
    S2 -->|"calls"| X2

    %% External Services stream responses to Frontend
    X1 -->|"streams"| F3

    %% Class definitions for styling
    class F1,F2,F3 frontend
    class B1,A1,A2,A3,A4,A5,A6,A7,D1,D2,D3,D4,D5,I1,I2,I3,I4,C1,C2,C3,S1,S2,S3,S4,S5 backend
    class DDP1,DDP2 database
    class X1,X2 external

    %% Click Events
    click F1 "https://github.com/leyber91/ai_canvas/blob/main/backend/templates/index.html"
    click F2 "https://github.com/leyber91/ai_canvas/tree/main/static/js/api"
    click F3 "https://github.com/leyber91/ai_canvas/tree/main/static/js/graph"
    click B1 "https://github.com/leyber91/ai_canvas/blob/main/backend/run.py"
    click C1 "https://github.com/leyber91/ai_canvas/blob/main/backend/app/core/config.py"
    click A1 "https://github.com/leyber91/ai_canvas/tree/main/backend/app/api/controllers"
    click D1 "https://github.com/leyber91/ai_canvas/tree/main/backend/app/domain/services"
    click I1 "https://github.com/leyber91/ai_canvas/tree/main/backend/app/infrastructure/ai_providers"
    click I3 "https://github.com/leyber91/ai_canvas/tree/main/backend/app/infrastructure/database"
    click DDP1 "https://github.com/leyber91/ai_canvas/tree/main/backend/app/models"
    click DDP2 "https://github.com/leyber91/ai_canvas/blob/main/backend/ai_canvas.sqlite"
    click C2 "https://github.com/leyber91/ai_canvas/blob/main/backend/app/core/exceptions.py"
    click C3 "https://github.com/leyber91/ai_canvas/blob/main/backend/app/utils/streaming.py"
    click S1 "https://github.com/leyber91/ai_canvas/tree/main/backend/app/services"

    %% Styles
    classDef frontend fill:#a9d8ff,stroke:#333,stroke-width:2px;
    classDef backend fill:#b0ffb0,stroke:#333,stroke-width:2px;
    classDef database fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef external fill:#ffdead,stroke:#333,stroke-width:2px;
```
