Skip to content

01 — System Overview

The big picture: how the entire Blinkin platform fits together across all four repositories.

System Architecture Diagram

The following diagram shows how all four repositories connect — from the user-facing frontend apps, through the backend API, into the AI platform, and out to infrastructure.

graph TB
    %% ───────────────────────────────────────────────
    %% USERS
    %% ───────────────────────────────────────────────
    Creator["👤 Creator / Admin<br/>(builds flows)"]
    EndUser["👤 End User<br/>(interacts with flows)"]
    ExternalSite["🌐 External Website<br/>(embeds blinks)"]

    %% ───────────────────────────────────────────────
    %% PICASSO-FE (Frontend Monorepo)
    %% ───────────────────────────────────────────────
    subgraph picasso_fe ["picasso-fe — React/TypeScript Monorepo"]
        direction TB

        subgraph editor_app ["Picasso Editor App"]
            Editor["Visual Flow Editor<br/>(ReactFlow)"]
            EditorDash["Creator Dashboard<br/>picasso-app.blinkin.io"]
        end

        subgraph houston_app ["Houston App"]
            Houston["Public Flow Viewer<br/>houston-app.blinkin.io"]
        end

        subgraph widget_app ["Widget"]
            Widget["Embeddable Script<br/>(iframe)"]
        end
    end

    %% ───────────────────────────────────────────────
    %% STUDIO-API (Backend)
    %% ───────────────────────────────────────────────
    subgraph studio_api ["studio-api — NestJS Backend"]
        direction TB

        subgraph studio_module ["Studio Module (Protected)"]
            StudioEndpoints["/picasso/* endpoints<br/>Flow creation & management<br/>Auth0-protected"]
        end

        subgraph houston_module ["Houston Module (Public)"]
            HoustonEndpoints["/houston/* endpoints<br/>Flow execution & interaction<br/>Public access"]
        end

        subgraph studio_services ["Core Services"]
            BullQueues["Bull Job Queues<br/>(Redis-backed)"]
            FileService["File Service<br/>(Azure Blob Storage)"]
            AuthService["Auth Service<br/>(Auth0)"]
            IntegrationService["Integration Service<br/>(Mailgun, Mux, Google Sheets, etc.)"]
        end
    end

    %% ───────────────────────────────────────────────
    %% ZWEISTEIN (AI Platform)
    %% ───────────────────────────────────────────────
    subgraph zweistein ["zweistein — AI Platform"]
        direction TB

        subgraph zw_admin ["Admin Panel (React)"]
            AdminUI["AI Management Dashboard<br/>Bots, Concepts, Agents"]
        end

        subgraph zw_server ["Server (NestJS)"]
            ZwAPI["/api/* endpoints<br/>API Gateway"]
            ZwFileManager["File Management"]
            ZwOrchestrator["Data Processing<br/>Orchestration"]
        end

        subgraph zw_ingestion ["Ingestion Worker (Python)"]
            FileProcessor["File Processor<br/>(text, audio, video)"]
            EmbeddingGen["Embedding Generator"]
            RedisListener["Redis Streams<br/>Listener"]
        end

        subgraph zw_query ["Query Engine (Python / FastAPI)"]
            LLMRouter["LLM Router<br/>(OpenAI, Gemini, Claude,<br/>Groq, Perplexity)"]
            ChatEngine["Chat / Agent Engine"]
            QueryProcessor["Query Processor"]
        end
    end

    %% ───────────────────────────────────────────────
    %% INFRASTRUCTURE
    %% ───────────────────────────────────────────────
    subgraph gitops ["blinkin-gitops — Kubernetes / Helm"]
        direction LR
        DevCluster["Dev Cluster"]
        UATCluster["UAT Cluster"]
        ProdCluster["Prod Cluster"]
    end

    %% ───────────────────────────────────────────────
    %% DATA STORES
    %% ───────────────────────────────────────────────
    subgraph datastores ["Data Stores"]
        direction LR
        PostgreSQL[("PostgreSQL<br/>Main Database")]
        Redis[("Redis<br/>Queues & Streams")]
        Qdrant[("Qdrant<br/>Vector Database")]
        AzureBlob[("Azure Blob<br/>File Storage")]
        GCS[("Google Cloud Storage<br/>AI File Storage")]
    end

    %% ───────────────────────────────────────────────
    %% EXTERNAL SERVICES
    %% ───────────────────────────────────────────────
    subgraph external ["External Services"]
        direction LR
        Auth0["Auth0<br/>Authentication"]
        Mailgun["Mailgun<br/>Email"]
        Mux["Mux<br/>Video"]
        GoogleSheets["Google Sheets<br/>Data"]
        LLMProviders["LLM Providers<br/>(OpenAI, Gemini, Claude,<br/>Groq, Perplexity)"]
    end

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Users to Frontend
    %% ───────────────────────────────────────────────
    Creator -->|"builds flows"| EditorDash
    EndUser -->|"interacts with flows"| Houston
    ExternalSite -->|"embeds via iframe"| Widget

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Frontend to Backend
    %% ───────────────────────────────────────────────
    Editor -->|"/picasso/* endpoints"| StudioEndpoints
    Editor -->|"/api/* endpoints"| ZwAPI
    EditorDash -->|"/picasso/* endpoints"| StudioEndpoints
    Houston -->|"/houston/* endpoints"| HoustonEndpoints
    Widget -->|"/houston/* endpoints"| HoustonEndpoints

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Studio API internals
    %% ───────────────────────────────────────────────
    StudioEndpoints --> BullQueues
    HoustonEndpoints --> BullQueues
    StudioEndpoints --> FileService
    StudioEndpoints --> AuthService
    StudioEndpoints --> IntegrationService

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Studio API to Data Stores
    %% ───────────────────────────────────────────────
    studio_api -->|"read/write"| PostgreSQL
    BullQueues -->|"job queue"| Redis
    FileService -->|"file upload/download"| AzureBlob

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Studio API to Zweistein
    %% ───────────────────────────────────────────────
    BullQueues -->|"sends data via queue"| RedisListener

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Zweistein internals
    %% ───────────────────────────────────────────────
    ZwAPI --> ZwOrchestrator
    ZwOrchestrator --> RedisListener
    RedisListener --> FileProcessor
    FileProcessor --> EmbeddingGen
    EmbeddingGen -->|"store embeddings"| Qdrant
    QueryProcessor --> LLMRouter
    ChatEngine --> QueryProcessor
    ZwAPI --> ChatEngine

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — Zweistein to Data Stores
    %% ───────────────────────────────────────────────
    zw_server -->|"read/write"| PostgreSQL
    zw_server -->|"publish streams"| Redis
    zw_ingestion -->|"listen streams"| Redis
    ZwFileManager -->|"file storage"| GCS

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — External Services
    %% ───────────────────────────────────────────────
    AuthService --> Auth0
    IntegrationService --> Mailgun
    IntegrationService --> Mux
    IntegrationService --> GoogleSheets
    LLMRouter --> LLMProviders

    %% ───────────────────────────────────────────────
    %% CONNECTIONS — GitOps deploys everything
    %% ───────────────────────────────────────────────
    gitops -.->|"deploys"| studio_api
    gitops -.->|"deploys"| picasso_fe
    gitops -.->|"deploys"| zweistein

    %% ───────────────────────────────────────────────
    %% STYLES
    %% ───────────────────────────────────────────────
    classDef userNode fill:#f9f,stroke:#333,stroke-width:2px
    classDef feNode fill:#61dafb,stroke:#333,stroke-width:1px,color:#000
    classDef beNode fill:#e0234e,stroke:#333,stroke-width:1px,color:#fff
    classDef aiNode fill:#a855f7,stroke:#333,stroke-width:1px,color:#fff
    classDef dataNode fill:#fbbf24,stroke:#333,stroke-width:1px,color:#000
    classDef extNode fill:#94a3b8,stroke:#333,stroke-width:1px,color:#000
    classDef infraNode fill:#22c55e,stroke:#333,stroke-width:1px,color:#000

    class Creator,EndUser,ExternalSite userNode
    class Editor,EditorDash,Houston,Widget feNode
    class StudioEndpoints,HoustonEndpoints,BullQueues,FileService,AuthService,IntegrationService beNode
    class AdminUI,ZwAPI,ZwFileManager,ZwOrchestrator,FileProcessor,EmbeddingGen,RedisListener,LLMRouter,ChatEngine,QueryProcessor aiNode
    class PostgreSQL,Redis,Qdrant,AzureBlob,GCS dataNode
    class Auth0,Mailgun,Mux,GoogleSheets,LLMProviders extNode
    class DevCluster,UATCluster,ProdCluster infraNode

Simplified Data Flow

This diagram shows the high-level flow of data through the system — from content creation to AI-powered interaction.

flowchart LR
    A["Creator builds<br/>flow in Editor"] -->|"saves via /picasso/*"| B["Studio API<br/>stores in PostgreSQL"]
    B -->|"publishes flow"| C["Houston serves<br/>flow to end users"]
    B -->|"sends to queue"| D["Zweistein ingests<br/>& generates embeddings"]
    D -->|"stores in Qdrant"| E["Vector DB ready<br/>for AI queries"]
    C -->|"user asks question"| F["Query Engine<br/>uses LLM + vectors"]
    F -->|"returns answer"| C

Tech Stack Summary

Category Technologies
Languages TypeScript, Python, JavaScript
Frontend Frameworks React 18, Vite, ReactFlow, TailwindCSS, Ant Design
Backend Frameworks NestJS (Node.js), FastAPI (Python)
Databases PostgreSQL (relational data), Redis (queues & streams), Qdrant (vector embeddings)
ORM / Data Access TypeORM (NestJS), SQLAlchemy (Python)
AI / ML OpenAI API, Google Gemini, Anthropic Claude, Groq, Perplexity
Embedding Models OpenAI Embeddings, Sentence Transformers
File Processing FFmpeg (audio/video), PyPDF, Unstructured (document parsing)
File Storage Azure Blob Storage (Studio API), Google Cloud Storage (Zweistein)
Authentication Auth0 (OAuth 2.0 / OIDC)
Job Queues Bull (Redis-backed, Studio API), Redis Streams (Zweistein)
Email Mailgun
Video Mux
Infrastructure Google Cloud Platform (GCP), Kubernetes (GKE), Helm
CI/CD GitHub Actions, Helm deployments
Monorepo Tooling Nx (picasso-fe)
Package Managers npm/yarn (TypeScript), pip/poetry (Python)

Environment Overview

Blinkin runs across three environments. Each environment is a separate Kubernetes namespace deployed via Helm charts from blinkin-gitops.

Environment Picasso Editor URL Houston URL Deploy Method
Dev picasso-app-dev.blinkin.io houston-app-dev.blinkin.io Auto-deploy on push to dev branch
UAT picasso-app.blinkin.io houston-app.blinkin.io Manual deploy (promotion from dev)
Prod Not yet available Not yet available Not yet configured 
graph LR
    subgraph dev ["Dev Environment"]
        DevPicasso["picasso-app-dev.blinkin.io"]
        DevHouston["houston-app-dev.blinkin.io"]
    end

    subgraph uat ["UAT Environment"]
        UATPicasso["picasso-app.blinkin.io"]
        UATHouston["houston-app.blinkin.io"]
    end

    subgraph prod ["Prod Environment"]
        ProdPicasso["Not yet available"]
        ProdHouston["Not yet available"]
    end

    dev -->|"manual promotion"| uat
    uat -->|"future"| prod

    Push["Push to dev branch"] -->|"auto-deploy"| dev

    style dev fill:#7b3eab,stroke:#6a3494,color:#fff
    style uat fill:#0057b7,stroke:#004a9e,color:#fff
    style prod fill:#5d5959,stroke:#444444,color:#aeafb4

Repository Summary

Repository Purpose Primary Tech Role in System
picasso-fe Frontend monorepo — 3 apps (Editor, Houston, Widget) React, TypeScript, Vite, ReactFlow, Nx User-facing interfaces for building and viewing interactive flows
studio-api Main backend API — flow CRUD, file management, integrations NestJS, TypeORM, PostgreSQL, Bull, Redis Central API server handling all business logic, data persistence, and external integrations
zweistein AI platform — admin panel, API server, ingestion, query engine React, NestJS, Python, FastAPI, Qdrant AI/ML pipeline: ingests content, generates embeddings, powers LLM-based chat and query
blinkin-gitops Infrastructure — Kubernetes & Helm deployment configs Kubernetes, Helm, GCP Manages deployment of all services across dev, UAT, and prod environments

How the Repos Connect

Here is a summary of the key integration points between repositories:

From To How What
picasso-fe (Editor) studio-api HTTP REST (/picasso/*) Flow creation, updates, file uploads, user management
picasso-fe (Editor) zweistein HTTP REST (/api/*) AI bot configuration, concept management
picasso-fe (Houston) studio-api HTTP REST (/houston/*) Flow execution, user interaction data, analytics
studio-api zweistein Redis Queue Sends ingestion jobs (files, content) for AI processing
zweistein (Server) zweistein (Ingestion) Redis Streams Publishes processing tasks for the Python ingestion worker
zweistein (Query Engine) LLM Providers HTTP APIs Sends prompts to OpenAI, Gemini, Claude, Groq, Perplexity
blinkin-gitops All repos Helm / K8s Deploys and configures all services in GCP

How to Navigate This Documentation

If you want to... Read this document
Understand the big picture and how everything connects You are here — 01 System Overview
Understand end-to-end data flows 02 — Data Flows
Work on the frontend (Editor, Houston, or Widget) 03 — Picasso Frontend
Work on the backend API, database, or integrations 04 — Studio API
Work on AI features, chatbots, or embeddings 05 — Zweistein AI Platform
Deploy, debug infrastructure, or manage environments 06 — Infrastructure
Look up key terms and definitions 07 — Glossary
Configure AI agents 08 — Agent Configuration

Generated: February 2026 Next: 02 — Data Flows