# giselles-ai/giselle architecture

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

- Interactive diagram: https://gitdiagram.com/giselles-ai/giselle
- Repository: https://github.com/giselles-ai/giselle

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted AI agent builder called “Giselle.” It consists of two Next.js applications (“playground” for experimenting and “studio.giselles.ai” for the production UI), a collection of shared TypeScript packages implementing core engine logic, data models, workflow orchestration, integrations, and utility libraries, plus database migrations and infrastructure-as-code for deployment.
- The README highlights that Giselle enables “agentic workflows” (chaining LLM calls, file operations, and integrations) in a cloud or self-hosted environment.

##### File structure
- Top-level “apps” directory:
- apps/playground – a Next.js 13 app for interactive sandboxing of agents.
- apps/studio.giselles.ai – the main Next.js 13 application with pages, API routes (auth, files upload, webhooks, workspace-run), and middleware.
- “packages” directory: dozens of internal packages providing:
- giselle-engine (core HTTP handlers, Next.js adapters, React contexts)
- data modeling (data-type, data-mod, flow)
- UI components (text-editor, workflow-designer-ui)
- SDK (giselle-sdk)
- Integrations (github-tool, supabase-driver, stripe via services/external, language-model providers)
- Telemetry, usage-limits, utilities, test-utils.
- Configuration and infra: Drizzle ORM config, SQL migrations, Supabase storage driver, Vercel/turbo/pnpm config, GitHub Actions workflows, Opentelemetry setup, CLI tools under “tools.”

##### README for additional insights
- Confirms a cloud-hosted service with auth, usage plans, free tier, and a self-hosting guide.
- Emphasizes AI-driven workflows that connect to Langchain-style LLM providers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend UIs"
        direction TB
        PlaygroundApp["Playground App (Next.js)"]:::frontend
        StudioApp["Studio App (Next.js)"]:::frontend
        ReactContexts["React Contexts & Hooks"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js Routes)"
        direction TB
        subgraph "Studio API Routes"
            AuthRoute["Auth Route"]:::backend
            FileUploadRoute["File Upload Route"]:::backend
            GiselleProxyStudio["Giselle Proxy Route"]:::backend
        end
        subgraph "Playground API Routes"
            GiselleProxyPlayground["Giselle Proxy Route"]:::backend
        end
    end

    %% Engine Layer
    subgraph "Giselle Engine"
        direction TB
        GiselleRouter["HTTP Router"]:::backend
        GiselleHandler["HTTP Handler"]:::backend
        CoreEngine["Core Engine Logic"]:::backend
        EngineReact["Engine React Contexts"]:::frontend
    end

    %% Shared Libraries
    subgraph "Shared Packages"
        direction TB
        DataModels["Data Models & Workflow Definitions"]:::backend
        WorkspaceLib["Workspace Management Library"]:::backend
        UtilsLib["Utility Libraries"]:::backend
        LLMIntegrations["LLM Provider Integrations"]:::external
        GitHubTool["GitHub Integration Package"]:::external
        IntegrationFramework["Integration Framework"]:::backend
        SupabaseDriver["Supabase Driver"]:::backend
        TelemetryLib["Telemetry Framework"]:::backend
        UsageLimits["Usage Limits Framework"]:::backend
        TextEditor["Text Editor UI Component"]:::frontend
        WorkflowDesigner["Workflow Designer UI"]:::frontend
    end

    %% Data Layer
    subgraph "Data & Storage"
        direction TB
        DrizzleConfig["Drizzle Config & Schema"]:::data
        Migrations["SQL Migrations"]:::data
        PostgresDB["PostgreSQL Database"]:::data
        StorageBuckets["Supabase Storage"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI & LLMs"]:::external
        Anthropic["Anthropic & Other LLMs"]:::external
        GitHubAPI["GitHub API"]:::external
        StripeSvc["Stripe Billing"]:::external
        EmailSvc["Email Service"]:::external
        Firecrawl["Firecrawl Scraper"]:::external
        Posthog["Posthog Analytics"]:::external
        OpenTelemetrySvc["OpenTelemetry"]:::external
    end

    %% Relationships
    PlaygroundApp -->|uses| ReactContexts
    StudioApp -->|uses| ReactContexts

    ReactContexts -->|calls| AuthRoute
    ReactContexts -->|calls| FileUploadRoute
    ReactContexts -->|calls| GiselleProxyStudio
    PlaygroundApp -->|calls| GiselleProxyPlayground

    AuthRoute -->|delegates| GiselleRouter
    FileUploadRoute -->|delegates| GiselleRouter
    GiselleProxyStudio -->|delegates| GiselleRouter
    GiselleProxyPlayground -->|delegates| GiselleRouter

    GiselleRouter --> GiselleHandler
    GiselleHandler --> CoreEngine
    CoreEngine -->|uses| DataModels
    CoreEngine -->|uses| WorkspaceLib
    CoreEngine -->|uses| SupabaseDriver
    CoreEngine -->|uses| IntegrationFramework
    CoreEngine -->|uses| UtilsLib
    CoreEngine -->|calls| LLMIntegrations
    CoreEngine -->|calls| GitHubTool

    CoreEngine -->|reads/writes| PostgresDB
    CoreEngine -->|stores files| StorageBuckets
    DrizzleConfig --> PostgresDB
    Migrations --> PostgresDB

    CoreEngine -->|emits| TelemetryLib
    ReactContexts -->|emits| TelemetryLib
    TelemetryLib -->|sends to| Posthog
    TelemetryLib -->|sends to| OpenTelemetrySvc

    CoreEngine -->|calls| StripeSvc
    StripeSvc -->|webhook to| AuthRoute
    CoreEngine -->|sends emails via| EmailSvc

    GitHubAPI -->|webhook to| AuthRoute
    CoreEngine -->|calls| Firecrawl

    %% Click Events
    click PlaygroundApp "https://github.com/giselles-ai/giselle/tree/main/apps/playground/"
    click StudioApp "https://github.com/giselles-ai/giselle/tree/main/apps/studio.giselles.ai/"
    click AuthRoute "https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/app/api/auth/[...nextauth]/route.ts"
    click FileUploadRoute "https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/app/api/files/upload/route.ts"
    click GiselleProxyStudio "https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/app/api/giselle/[...next-giselle]/route.ts"
    click GiselleProxyPlayground "https://github.com/giselles-ai/giselle/blob/main/apps/playground/app/api/giselle/[...next-giselle]/route.ts"
    click GiselleRouter "https://github.com/giselles-ai/giselle/blob/main/packages/giselle-engine/src/http/router.ts"
    click GiselleHandler "https://github.com/giselles-ai/giselle/blob/main/packages/giselle-engine/src/http/create-handler.ts"
    click CoreEngine "https://github.com/giselles-ai/giselle/tree/main/packages/giselle-engine/src/core/"
    click EngineReact "https://github.com/giselles-ai/giselle/tree/main/packages/giselle-engine/src/react/"
    click DataModels "https://github.com/giselles-ai/giselle/tree/main/packages/data-type/"
    click DataModels "https://github.com/giselles-ai/giselle/tree/main/packages/flow/"
    click WorkspaceLib "https://github.com/giselles-ai/giselle/tree/main/packages/workspace/"
    click UtilsLib "https://github.com/giselles-ai/giselle/tree/main/packages/utils/"
    click UtilsLib "https://github.com/giselles-ai/giselle/tree/main/packages/test-utils/"
    click LLMIntegrations "https://github.com/giselles-ai/giselle/tree/main/packages/language-model/"
    click GitHubTool "https://github.com/giselles-ai/giselle/tree/main/packages/github-tool/"
    click IntegrationFramework "https://github.com/giselles-ai/giselle/tree/main/packages/integration/"
    click SupabaseDriver "https://github.com/giselles-ai/giselle/tree/main/packages/supabase-driver/"
    click DrizzleConfig "https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/drizzle.config.ts"
    click DrizzleConfig "https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/drizzle/schema.ts"
    click Migrations "https://github.com/giselles-ai/giselle/tree/main/apps/studio.giselles.ai/migrations/"
    click TelemetryLib "https://github.com/giselles-ai/giselle/tree/main/packages/telemetry/"
    click TelemetryLib "https://github.com/giselles-ai/giselle/tree/main/apps/studio.giselles.ai/lib/opentelemetry/"
    click UsageLimits "https://github.com/giselles-ai/giselle/tree/main/packages/usage-limits/"
    click TextEditor "https://github.com/giselles-ai/giselle/tree/main/packages/text-editor/"
    click WorkflowDesigner "https://github.com/giselles-ai/giselle/tree/main/internal-packages/workflow-designer-ui/"
    click StorageBuckets "https://github.com/giselles-ai/giselle/blob/main/apps/studio.giselles.ai/supabase-storage-driver.ts"
    click StorageBuckets "https://github.com/giselles-ai/giselle/blob/main/apps/playground/supabase-storage-driver.ts"
    click WorkspaceLib "https://github.com/giselles-ai/giselle/tree/main/packages/workspace/"
    click IntegrationFramework "https://github.com/giselles-ai/giselle/tree/main/packages/integration/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef data fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef external fill:#FFD6D6,stroke:#333,stroke-width:1px
```
