# mintplex-labs/vector-admin architecture

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

- Interactive diagram: https://gitdiagram.com/mintplex-labs/vector-admin
- Repository: https://github.com/mintplex-labs/vector-admin

## Overview

##### Main components
- Frontend (React/Vite UI)
- Backend API (Node.js + Express + Prisma)
- Relational metadata store (Postgres/MySQL via Prisma)
- Vector database connectors (Pinecone, Chroma, Qdrant, Weaviate)
- Document-processor service (Python/Flask)
- Background workers (InngestJS functions)
- Telemetry (PostHog)
- Docker orchestration (docker-compose)

##### Relationships and data–flow
a. User → Frontend: browser requests UI (login, dashboards, CRUD on documents, connectors, RAG tests).
b. Frontend → Backend API: HTTP REST calls (auth, system settings, organizations, workspaces, documents, embeddings, jobs, RAG tests).
c. Backend → Relational DB: Prisma client for all metadata and user/organization/workspace/join tables.
d. Backend → Vector DBs: through “utils/vectordatabases/providers/*” modules to perform search, insert, delete, copy, migrate embeddings.
e. Backend ↔ Document-processor: HTTP to Flask on port 8888 for text extraction, parsing, initial embedding.
f. Backend → Inngest: publish job events (addDocumentsJob, syncJobs, ragTestJobRun, etc.).
g. Workers (Inngest functions) → Vector DBs: perform long-running tasks asynchronously (add, update, delete embeddings; clone, migrate, sync).
h. Backend & Workers → Telemetry: calls to PostHog to record usage events.

##### Architectural patterns
- Monorepo with four services and shared config (env, .nvmrc, linting).
- Microservices for specialized tasks: Flask for doc processing, InngestJS for background jobs.
- Layered backend: endpoints → models → utils → vectordb providers.
- Plugin-style vector DB connectors for extensibility.
- API-driven UI with React Context for auth and state.
- Docker Compose for full-stack local deployment.

##### Relevant technologies
- Frontend: React, Vite, TypeScript, Tailwind CSS
- Backend: Node.js, Express, Prisma ORM, JWT auth, Multer for file uploads
- Doc-processor: Python 3.9+, Flask, various parser scripts
- Workers: InngestJS, Node.js functions
- Databases: Postgres (or MySQL) via Prisma; Pinecone, ChromaDB, Qdrant, Weaviate
- Telemetry: PostHog API

##### Don’t forget these details
- Meta-data store: Prisma schema.prisma with migrations folder.
- Env management: .env.example files in each service.
- Authentication flows: auth endpoint issuing JWT, React AuthContext.
- File upload path: Multer → storage/settings.json.
- Background job examples: “createRagTestJobRun” → runs RAG test and writes results back to relational DB.
- Vector DB providers folder, demonstrating plugin approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose grouping
    subgraph "Docker Compose"
        direction TB
        Browser["User Browser"]:::external
        Frontend["Frontend (React/Vite UI)"]:::frontend
        subgraph "Backend Service"
            direction TB
            BackendIndex["index.js"]:::backend
            Endpoints["endpoints/"]:::backend
            PrismaSchema["schema.prisma"]:::database
            Migrations["migrations/"]:::database
            VectorProviders["vectordatabases/providers/"]:::backend
            BackendTelemetry["metrics/index.js"]:::backend
        end
        subgraph "Document-Processor"
            direction TB
            DocProcessorAPI["api.py"]:::docproc
            DocProcessorDir["document-processor/"]:::docproc
        end
        subgraph "Workers Service"
            direction TB
            WorkersIndex["index.js"]:::workers
            Functions["functions/"]:::workers
            WorkersTelemetry["telemetryHelpers.js"]:::workers
        end
    end

    %% External Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["Postgres (Prisma ORM)"]:::database
        VectorDBs["Vector Databases"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PostHog["PostHog Telemetry"]:::telemetry
    end

    %% Vector DB Providers Detail
    subgraph "Vector DB Providers"
        direction TB
        Pinecone["Pinecone"]
        Chroma["ChromaDB"]
        Qdrant["Qdrant"]
        Weaviate["Weaviate"]
    end

    %% Flows
    Browser -->|"Load UI (HTTP/JSON)"| Frontend
    Frontend -->|"REST API Calls"| BackendIndex
    BackendIndex -->|"SQL (Prisma Client)"| Postgres
    Endpoints -->|"/v1/... endpoints"| BackendIndex
    BackendIndex -->|"SDK/API"| VectorProviders
    VectorProviders -->|"connectors"| Pinecone
    VectorProviders -->|"connectors"| Chroma
    VectorProviders -->|"connectors"| Qdrant
    VectorProviders -->|"connectors"| Weaviate
    BackendIndex -->|"HTTP/JSON"| DocProcessorAPI
    BackendIndex -->|"Publish Events"| WorkersIndex
    WorkersIndex -->|"Long-running Jobs"| VectorProviders
    BackendIndex -->|"PostHog.capture()"| PostHog
    WorkersIndex -->|"PostHog.capture()"| PostHog

    %% Click Events
    click Frontend "https://github.com/mintplex-labs/vector-admin/tree/master/frontend/"
    click BackendIndex "https://github.com/mintplex-labs/vector-admin/blob/master/backend/index.js"
    click Endpoints "https://github.com/mintplex-labs/vector-admin/tree/master/backend/endpoints/"
    click PrismaSchema "https://github.com/mintplex-labs/vector-admin/blob/master/backend/prisma/schema.prisma"
    click Migrations "https://github.com/mintplex-labs/vector-admin/tree/master/backend/prisma/migrations/"
    click VectorProviders "https://github.com/mintplex-labs/vector-admin/tree/master/backend/utils/vectordatabases/providers/"
    click DocProcessorAPI "https://github.com/mintplex-labs/vector-admin/blob/master/document-processor/api.py"
    click DocProcessorDir "https://github.com/mintplex-labs/vector-admin/tree/master/document-processor/"
    click WorkersIndex "https://github.com/mintplex-labs/vector-admin/blob/master/workers/index.js"
    click Functions "https://github.com/mintplex-labs/vector-admin/tree/master/workers/functions/"
    click BackendTelemetry "https://github.com/mintplex-labs/vector-admin/blob/master/backend/utils/metrics/index.js"
    click WorkersTelemetry "https://github.com/mintplex-labs/vector-admin/blob/master/workers/utils/telemetryHelpers.js"
    click DockerCompose "https://github.com/mintplex-labs/vector-admin/blob/master/docker/docker-compose.yml"
    click Dockerfile "https://github.com/mintplex-labs/vector-admin/tree/master/docker/Dockerfile"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#000
    classDef backend fill:#d4edda,stroke:#000
    classDef workers fill:#fff3cd,stroke:#000
    classDef docproc fill:#e2e3e5,stroke:#000
    classDef database fill:#f0f0f0,stroke:#000
    classDef telemetry fill:#fff2cc,stroke:#000
    classDef external fill:#ffffff,stroke:#000,stroke-dasharray: 5 5
```
