# yesahmedyes/flow-llm-backend architecture

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

- Interactive diagram: https://gitdiagram.com/yesahmedyes/flow-llm-backend
- Repository: https://github.com/yesahmedyes/flow-llm-backend

## Overview

##### Project type and purpose
- This is a single microservice (“Document Parser”) built with FastAPI.
- Its purpose is to accept document-parsing requests, extract or OCR text/images, generate embeddings via AI models, and store those embeddings in a vector database.

##### File structure
- Top-level files: Dockerfile, render.yaml (deployment), requirements.txt, main.py (API entry), README.md.
- Python modules:
- handlers.py – orchestrates document-type dispatch
- parsers.py – PDF/text extraction/chunking
- image_handler.py – OCR and image captioning
- model_calls.py – communicates with Cohere/OpenRouter/OpenAI
- s3_handler.py – AWS S3 upload/download
- handlers.py & model_calls.py & s3_handler.py form the core integration glue.
- No separate “frontend”; it’s purely a backend microservice.

##### README for additional insights
- External dependencies: AWS S3, Pinecone vector DB, Cohere embed-4.0, OpenRouter/OpenAI API, Tesseract OCR.
- Deployment on Render via render.yaml, containerized via Dockerfile.
- Single HTTP POST endpoint: /api/parse-and-embed.

a. Main components:
- Client (CLI, UI, another service)
- FastAPI service (container)
– API layer (main.py + uvicorn)
– Business logic module (handlers.py)
– Document parsers (parsers.py, image_handler.py)
– Model integration (model_calls.py)
– Storage integration (s3_handler.py)
- External services: AWS S3, Pinecone DB, Cohere API, OpenRouter/OpenAI API, Tesseract OCR (local or container).
- Deployment platform: Render.com (via render.yaml & Dockerfile)
b. Relationships & data flow:
1. Client → HTTP POST → FastAPI endpoint
2. FastAPI → handlers.py decides parser based on file type
3. handlers.py calls s3_handler to fetch document from S3
4. Document passed to parsers.py (for PDF/text) or image_handler.py (for images + OCR)
5. Parsed text chunks → model_calls.py → Cohere/OpenRouter APIs for embeddings
6. model_calls returns embedding vectors → handlers.py → Pinecone SDK call to store vectors
7. handlers.py returns success response to client
c. Architectural patterns & design principles:
- Separation of concerns: API layer vs parsing vs AI calls vs storage.
- Single-responsibility modules for each integration.
- Microservice design: stateless container interacting with managed services.
d. Technologies & frameworks:
- FastAPI + Uvicorn
- Python modules (handlers, parsers, model_calls, s3_handler, image_handler)
- AWS S3 SDK, Pinecone SDK
- Cohere embed-4.0, OpenRouter/OpenAI
- Tesseract OCR
- Docker & Render.com for deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["Client"]:::external

    %% FastAPI Container
    subgraph "FastAPI Service (Container)" 
        direction TB
        APILayer["API Layer (main.py)"]:::internal
        Handlers["Business Logic (handlers.py)"]:::internal
        Parsers["Document Parsers (parsers.py)"]:::internal
        ImageHandler["Image Handler (image_handler.py)"]:::internal
        ModelCalls["Model Integration (model_calls.py)"]:::internal
        S3Handler["Storage Integration (s3_handler.py)"]:::internal
    end

    %% External Services
    AWSS3["AWS S3"]:::external
    Pinecone["Pinecone Vector DB"]:::external
    CohereAPI["Cohere/OpenAI API"]:::external
    Tesseract["Tesseract OCR"]:::external

    %% Configuration Files
    subgraph "Configuration" 
        direction TB
        Dockerfile["Dockerfile"]:::config
        RenderConfig["render.yaml"]:::config
        Requirements["requirements.txt"]:::config
        README["README.md"]:::config
    end

    %% Data Flows
    Client -->|"POST /api/parse-and-embed"| APILayer
    APILayer -->|"delegate request"| Handlers
    Handlers -->|"fetch file from S3"| S3Handler
    S3Handler -->|"download file"| AWSS3
    Handlers -->|"route to parser"| Parsers
    Handlers -->|"route to image handler"| ImageHandler
    Parsers -->|"text chunks"| ModelCalls
    ImageHandler -->|"OCR & caption"| Tesseract
    ImageHandler -->|"image text"| ModelCalls
    ModelCalls -->|"embed via API"| CohereAPI
    CohereAPI -->|"return vectors"| ModelCalls
    ModelCalls -->|"vectors"| Handlers
    Handlers -->|"store vectors"| Pinecone
    Pinecone -->|"ack"| Handlers
    Handlers -->|"return response"| APILayer
    APILayer -->|"200 OK"| Client

    %% Click Events
    click APILayer "https://github.com/yesahmedyes/flow-llm-backend/blob/main/main.py"
    click Handlers "https://github.com/yesahmedyes/flow-llm-backend/blob/main/handlers.py"
    click Parsers "https://github.com/yesahmedyes/flow-llm-backend/blob/main/parsers.py"
    click ImageHandler "https://github.com/yesahmedyes/flow-llm-backend/blob/main/image_handler.py"
    click ModelCalls "https://github.com/yesahmedyes/flow-llm-backend/blob/main/model_calls.py"
    click S3Handler "https://github.com/yesahmedyes/flow-llm-backend/blob/main/s3_handler.py"
    click Dockerfile "https://github.com/yesahmedyes/flow-llm-backend/tree/main/Dockerfile"
    click RenderConfig "https://github.com/yesahmedyes/flow-llm-backend/blob/main/render.yaml"
    click Requirements "https://github.com/yesahmedyes/flow-llm-backend/blob/main/requirements.txt"
    click README "https://github.com/yesahmedyes/flow-llm-backend/blob/main/README.md"

    %% Styles
    classDef internal fill:#D6EFFF,stroke:#3B83BD,stroke-width:1px
    classDef external fill:#E6FFED,stroke:#38A169,stroke-width:1px
    classDef config fill:#F5F5F5,stroke:#A0AEC0,stroke-width:1px
```
