How yesahmedyes/flow-llm-backend works
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