# commontoolsinc/labs architecture

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

- Interactive diagram: https://gitdiagram.com/commontoolsinc/labs
- Repository: https://github.com/commontoolsinc/labs

## Overview

##### Project type and purpose
- This is a monorepo containing a full-stack application called “Common Labs.”
- Frontend: “Jumble” – a React/TypeScript SPA built with Vite.
- Backend: “Toolshed” – a Deno-based HTTP API.
- Alongside are dozens of shared libraries (memory, llm, runner, builder, charm, identity, iframe-sandbox, etc.), CLI tools, and background services.

##### File structure
- Top-level folders handle global config, CI/CD (.github/workflows), scripts, tasks, and monorepo tooling (deno.json, dockerignore).
- packages/ contains discrete workspaces:
– toolshed: Deno server implementing routes for AI, storage, auth, health, integrations.
– jumble: React SPA with components, contexts, hooks, styles.
– memory, llm, runner, builder, charm, identity, iframe-sandbox: core libraries encapsulating data storage, LLM prompt logic, recipe execution, code generation, authentication, sandboxed iframes.
– cli, seeder, background-charm-service: developer-facing CLIs and background worker processes.
– ui, html, deno-vite-plugin, deno-web-test, utils: ancillary libraries for rendering, bundling, testing, and utility functions.

##### README for additional insights
- README emphasizes a two-tier architecture: frontend at http://localhost:5173, backend at http://localhost:8000.
- Toolshed README details API startup; jumble README covers SPA development and environment override for cloud backend.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        Jumble["Jumble SPA"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (API)"
        Toolshed["Toolshed API"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        SQL["SQL Database"]:::datastore
        Redis["Redis (Blob/Cache)"]:::datastore
    end

    %% Workers / Background Services
    subgraph "Workers / Background Services"
        BGCharm["Background Charm Service"]:::worker
    end

    %% Shared Libraries
    subgraph "Libraries (Shared Modules)"
        Memory["memory"]:::library
        LLM["llm"]:::library
        RunnerLib["runner"]:::library
        Builder["builder"]:::library
        CharmLib["charm"]:::library
        Identity["identity"]:::library
        IFrameSandbox["iframe-sandbox"]:::library
        UI["ui"]:::library
        HTML["html"]:::library
        VitePlugin["deno-vite-plugin"]:::library
        WebTest["deno-web-test"]:::library
        Utils["utils"]:::library
    end

    %% External Services
    subgraph "External Services"
        LLMProvider["LLM Provider"]:::external
        GoogleOAuth["Google OAuth"]:::external
        Discord["Discord API"]:::external
    end

    %% User
    User["User"]:::external

    %% Relationships
    User -->|"HTTP/WebSocket"| Jumble
    Jumble -->|"REST API Calls"| Toolshed

    Toolshed -->|"SQL Reads/Writes"| SQL
    Toolshed -->|"Blob/Cache"| Redis
    Toolshed -->|"uses prompts"| LLM
    Toolshed -->|"DB migrations"| Memory
    Toolshed -->|"exec recipes"| RunnerLib
    Toolshed -->|"auth/session"| Identity
    Toolshed -->|"offload tasks"| BGCharm

    BGCharm <-->|"IPC"| RunnerLib

    Jumble -->|"UI Components"| UI
    Jumble -->|"build via Vite"| VitePlugin
    Jumble -->|"utils"| Utils

    Toolshed -->|"codegen spells"| Builder
    Toolshed -->|"workflow logic"| CharmLib
    Toolshed -->|"iframe sandbox"| IFrameSandbox

    Toolshed -->|"LLM API"| LLMProvider
    Toolshed -->|"OAuth flows"| GoogleOAuth
    Toolshed -->|"Discord integration"| Discord

    %% Click Events
    click Jumble "https://github.com/commontoolsinc/labs/tree/main/packages/jumble/"
    click Toolshed "https://github.com/commontoolsinc/labs/tree/main/packages/toolshed/"
    click Memory "https://github.com/commontoolsinc/labs/tree/main/packages/memory/"
    click LLM "https://github.com/commontoolsinc/labs/tree/main/packages/llm/"
    click RunnerLib "https://github.com/commontoolsinc/labs/tree/main/packages/runner/"
    click Builder "https://github.com/commontoolsinc/labs/tree/main/packages/builder/"
    click CharmLib "https://github.com/commontoolsinc/labs/tree/main/packages/charm/"
    click Identity "https://github.com/commontoolsinc/labs/tree/main/packages/identity/"
    click IFrameSandbox "https://github.com/commontoolsinc/labs/tree/main/packages/iframe-sandbox/"
    click BGCharm "https://github.com/commontoolsinc/labs/tree/main/packages/background-charm-service/"
    click UI "https://github.com/commontoolsinc/labs/tree/main/packages/ui/"
    click HTML "https://github.com/commontoolsinc/labs/tree/main/packages/html/"
    click VitePlugin "https://github.com/commontoolsinc/labs/tree/main/packages/deno-vite-plugin/"
    click WebTest "https://github.com/commontoolsinc/labs/tree/main/packages/deno-web-test/"
    click Utils "https://github.com/commontoolsinc/labs/tree/main/packages/utils/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#05A,stroke-width:2px
    classDef backend fill:#DFF5D0,stroke:#3A7,stroke-width:2px
    classDef datastore fill:#F0F0F0,stroke:#888,stroke-width:2px
    classDef worker fill:#FFE5CC,stroke:#E90,stroke-width:2px
    classDef library fill:#F5D0FF,stroke:#A05,stroke-width:2px
    classDef external fill:#FFD0D0,stroke:#A00,stroke-width:2px
```
