# langchain-ai/langconnect architecture

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

- Interactive diagram: https://gitdiagram.com/langchain-ai/langconnect
- Repository: https://github.com/langchain-ai/langconnect

## Overview

##### Project type and purpose
- LangConnect is a single microservice full‐stack application (backend‐only) offering a REST API for collection and document management plus semantic search via vector embeddings.
- Key indicators: “FastAPI‐based REST API,” “PostgreSQL with pgvector,” “LangChain” in README and the presence of api/, services/, database/ folders.

##### File structure
- Top‐level executables/configuration: Dockerfile, docker‐compose.yml, Makefile, .env.example
- Application code under langconnect/:
- __main__.py & server.py (entrypoint, ASGI server)
- api/ (REST endpoints/controllers: collections.py, documents.py)
- services/ (business logic: document_processor.py)
- database/ (storage adapters: connection.py, collections.py)
- models/ (Pydantic models for Collection, Document)
- auth.py, config.py (cross‐cutting concerns)
- tests/ (unit tests for API and imports)

##### README for additional insights
- Tech stack: FastAPI, LangChain, PostgreSQL+pgvector, Docker
- Runtime: one Docker service for the API, one for Postgres
- Exposed ports: 8080 for API docs & health

a. Clients and API Gateway
- External clients (browser, curl, Postman) calling HTTP endpoints (port 8080)
b. FastAPI service
- HTTP layer (uvicorn ASGI server in server.py)
- API controllers (langconnect/api/*.py)
- Auth and config (auth.py, config.py)
c. Business logic / Services
- DocumentProcessor (langconnect/services/document_processor.py) orchestrating:
- Content ingestion
- Embedding generation via LangChain (calls to LLM or embedding API)
- Vector storage operations
d. Persistence layer
- PostgreSQL with pgvector extension (containerized)
- DB adapter code (langconnect/database/connection.py, collections.py)
e. External dependencies
- LangChain library (for vector embedding generation and RAG flow)
- Docker / Docker Compose (for deployment orchestration)

##### Relationships and data flow
- Clients → HTTP POST/GET → FastAPI controllers
- Controllers → Business services →
- DocumentProcessor invokes LangChain embedding API (external HTTP/gRPC calls)
- Database adapter issues SQL commands to Postgres + pgvector
- Database → returns data (records + vectors) → service → controller → client

##### Architectural patterns / principles
- Layered architecture (Controller → Service → Data Access)
- Dependency injection via config.py for DB connection and environment variables
- Separation of concerns: models, services, API, and database modules
- Containerization for reproducibility and isolation

##### Technologies / frameworks to call out
- FastAPI (web framework)
- Uvicorn (ASGI server)
- LangChain (LLM orchestration)
- PostgreSQL + pgvector (vector store)
- Docker + Docker Compose (containers, networking)
- Pydantic (data validation models)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["External Client (Browser/Postman)"]:::external

    %% External Services
    LangChain["Embedding API / LLM Service"]:::external
    PostgresDB["PostgreSQL + pgvector"]:::db

    %% Deployment Config
    subgraph "Deployment Configuration"
        DockerfileNode["Dockerfile"]:::config
        DockerCompose["docker-compose.yml"]:::config
    end

    %% API Container
    subgraph "LangConnect API Service (Container)" 
        direction TB
        Entrypoint["ASGI Server / Uvicorn\n(langconnect/server.py)"]:::entry
        CLI["CLI Entrypoint\n(langconnect/__main__.py)"]:::entry

        subgraph "API Layer (Controllers)"
            direction TB
            CollectionsCtrl["CollectionsController\n(langconnect/api/collections.py)"]:::controller
            DocumentsCtrl["DocumentsController\n(langconnect/api/documents.py)"]:::controller
        end

        subgraph "Cross-Cutting Modules"
            direction TB
            Auth["Authentication\n(langconnect/auth.py)"]:::module
            Config["Configuration\n(langconnect/config.py)"]:::module
        end

        subgraph "Service Layer"
            direction TB
            DocProcessor["DocumentProcessor\n(langconnect/services/document_processor.py)"]:::service
        end

        subgraph "Data Access Layer"
            direction TB
            DBConn["DB Connection\n(langconnect/database/connection.py)"]:::data
            DBCollections["Collections Adapter\n(langconnect/database/collections.py)"]:::data
        end

        subgraph "Models"
            direction TB
            ModelCollection["Collection Model\n(langconnect/models/collection.py)"]:::model
            ModelDocument["Document Model\n(langconnect/models/document.py)"]:::model
        end
    end

    %% Flows
    Client -->|"HTTP Request"| Entrypoint
    Entrypoint -->|routes to| CollectionsCtrl
    Entrypoint -->|routes to| DocumentsCtrl

    CollectionsCtrl -->|"calls"| Auth
    DocumentsCtrl -->|"calls"| Auth
    CollectionsCtrl -->|uses| Config
    DocumentsCtrl -->|uses| Config

    CollectionsCtrl -->|"calls"| DocProcessor
    DocumentsCtrl -->|"calls"| DocProcessor

    DocProcessor -->|"generate embeddings"| LangChain
    DocProcessor -->|"uses"| DBCollections

    DBCollections -->|"connects via"| DBConn
    DBConn -->|"SQL queries"| PostgresDB

    ModelCollection -->|used by| CollectionsCtrl
    ModelDocument -->|used by| DocumentsCtrl
    ModelCollection -->|used by| DBCollections
    ModelDocument -->|used by| DBCollections

    %% Deployment links
    DockerCompose -->|deploys| PostgresDB
    DockerCompose -->|deploys| LangConnectAPI

    %% Click Events
    click Entrypoint "https://github.com/langchain-ai/langconnect/blob/main/langconnect/server.py"
    click CLI "https://github.com/langchain-ai/langconnect/blob/main/langconnect/__main__.py"
    click CollectionsCtrl "https://github.com/langchain-ai/langconnect/blob/main/langconnect/api/collections.py"
    click DocumentsCtrl "https://github.com/langchain-ai/langconnect/blob/main/langconnect/api/documents.py"
    click Auth "https://github.com/langchain-ai/langconnect/blob/main/langconnect/auth.py"
    click Config "https://github.com/langchain-ai/langconnect/blob/main/langconnect/config.py"
    click DocProcessor "https://github.com/langchain-ai/langconnect/blob/main/langconnect/services/document_processor.py"
    click DBConn "https://github.com/langchain-ai/langconnect/blob/main/langconnect/database/connection.py"
    click DBCollections "https://github.com/langchain-ai/langconnect/blob/main/langconnect/database/collections.py"
    click ModelCollection "https://github.com/langchain-ai/langconnect/blob/main/langconnect/models/collection.py"
    click ModelDocument "https://github.com/langchain-ai/langconnect/blob/main/langconnect/models/document.py"
    click DockerfileNode "https://github.com/langchain-ai/langconnect/tree/main/Dockerfile"
    click DockerCompose "https://github.com/langchain-ai/langconnect/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#eef,stroke:#888,stroke-width:1px
    classDef db fill:#ffb,stroke:#888,stroke-width:1px
    classDef config fill:#f5f5dc,stroke:#aaa,stroke-width:1px
    classDef entry fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef controller fill:#b3e6b3,stroke:#228B22,stroke-width:1px
    classDef module fill:#e6ccff,stroke:#800080,stroke-width:1px
    classDef service fill:#ffcccc,stroke:#ff0000,stroke-width:1px
    classDef data fill:#ffe6cc,stroke:#ff8c00,stroke-width:1px
    classDef model fill:#fff0b3,stroke:#deb887,stroke-width:1px
    class LangConnectAPI fill:#f9f,stroke:#333,stroke-width:2px
```
