# oguzsh/semantica architecture

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

- Interactive diagram: https://gitdiagram.com/oguzsh/semantica
- Repository: https://github.com/oguzsh/semantica

## Overview

##### Project Type and Purpose
- Type: Backend microservice (no built-in frontend)
- Purpose: Ingest PDF files, chunk them, generate embeddings, and perform vector-based semantic search using Qdrant.

##### Main Components
a. Client / API Consumer
b. FastAPI Server (main.py + config.py)
c. PDF Processing Module (services/pdf_service.py using pymupdf4llm)
d. Text Chunking Module (LangChain MarkdownTextSplitter via services/pdf_service.py)
e. Embedding Module (services/embedding_service.py using HuggingFace MiniLM)
f. Vector Storage Module (services/qdrant_service.py interacting with Qdrant vector DB)
g. Qdrant Vector Database (external Docker container)

##### Relationships & Data Flow
- Upload Flow (POST /upload):
1. Client → FastAPI
2. FastAPI calls PDF Service → Extract pages/text
3. Text passed to Chunker → Results in text chunks
4. Chunks sent to Embedding Service → Produces vectors
5. Vectors + metadata handed to Qdrant Service → Stored in Qdrant
6. FastAPI returns success to Client
- Search Flow (POST /search):
1. Client → FastAPI
2. FastAPI calls Embedding Service → Query vector
3. Query vector → Qdrant Service → Similarity search
4. Qdrant returns top-N chunks → FastAPI maps to JSON model (models/search_request.py) → Returns to Client

##### Architectural Patterns & Design Principles
- Layered architecture:
– Presentation/API layer (FastAPI endpoints)
– Domain/Service layer (PDF parsing, chunking, embedding, DB interactions)
– Infrastructure layer (external Qdrant service)
- Single responsibility: each service module handles one concern
- Dependency injection via config.py for Qdrant URL, model settings
- Asynchronous I/O (FastAPI + Uvicorn) for high throughput

##### Technologies & Frameworks
- FastAPI (web framework + API documentation)
- pymupdf4llm (PDF parsing)
- LangChain MarkdownTextSplitter (text chunking)
- sentence-transformers MiniLM (embedding)
- Qdrant (vector database, running in Docker)
- Python models (Pydantic) for request/response schemas

##### Elements
- Component name labels (e.g., “PDF Service”)
– API layer (FastAPI)
– Processing modules (PDF, Chunking, Embedding)
– Data store (Qdrant)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entity
    Client["Client / API Consumer"]:::external

    subgraph "API Layer"
        API["FastAPI Server\n(main.py)"]:::api
        Config["Configuration\n(config.py)"]:::api
        SearchModel["Search Request Model\n(models/search_request.py)"]:::api
    end

    subgraph "Service Layer"
        PDFService["PDF Processing Service\n(services/pdf_service.py)"]:::processing
        Chunker["Text Chunker\n(LangChain MarkdownTextSplitter)"]:::processing
        EmbedService["Embedding Service\n(services/embedding_service.py)"]:::processing
        StorageService["Qdrant Service\n(services/qdrant_service.py)"]:::processing
    end

    subgraph "Infrastructure"
        QdrantDB["Qdrant Vector Database\n(Docker on port 6333)"]:::external
    end

    %% Upload Flow
    Client -->|"POST /upload\nraw PDF"| API
    API -->|"uses PDFService"| PDFService
    PDFService -->|"extracted text"| Chunker
    Chunker -->|"text chunks"| EmbedService
    EmbedService -->|"vectors + metadata"| StorageService
    StorageService -->|"HTTP to Qdrant"| QdrantDB
    StorageService -->|"ack"| API
    API -->|"200 OK\nJSON"| Client

    %% Search Flow
    Client -->|"POST /search\nJSON"| API
    API -->|"validate via SearchModel"| SearchModel
    API -->|"generate query vector"| EmbedService
    EmbedService -->|"query vector"| StorageService
    StorageService -->|"top-N chunks"| API
    API -->|"200 OK\nJSON"| Client

    %% Click Events
    click API "https://github.com/oguzsh/semantica/blob/main/main.py"
    click Config "https://github.com/oguzsh/semantica/blob/main/config.py"
    click PDFService "https://github.com/oguzsh/semantica/blob/main/services/pdf_service.py"
    click EmbedService "https://github.com/oguzsh/semantica/blob/main/services/embedding_service.py"
    click StorageService "https://github.com/oguzsh/semantica/blob/main/services/qdrant_service.py"
    click SearchModel "https://github.com/oguzsh/semantica/blob/main/models/search_request.py"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef processing fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
```
