# ahmedelzaria/lab-result-extraction architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedelzaria/lab-result-extraction
- Repository: https://github.com/ahmedelzaria/lab-result-extraction

## Overview

##### Project type and purpose
- This is a backend microservice (FastAPI) for extracting structured data from lab-result PDFs.
- It validates incoming files, extracts raw text (via PDF libraries or OCR), parses and cleans it (Llama Parse), then runs a small LLM (GPT-4o-mini) to output JSON.

##### File structure
- Top level
- Dockerfile/.dockerignore: containerization
- README.md: architecture overview, tech stack
- requirements.txt: Python dependencies
- app/: main package
- app/main.py: FastAPI entrypoint
- app/models: AI-model interfaces (openai_models.py)
- app/processors: file-type handlers (pdf_processor.py inherits base_processor.py)
- app/validators: file checks (size, extension, MIME), composite_validator
- app/prompts: static prompt templates for Llama and OpenAI
- tests/: unit tests for validators and processors

##### Key insights from README
- Two-stage pipeline:
1. **Validation & Extraction**
2. **Parsing & Field Extraction**
- Modular, SOLID architecture: validators, processors, model handlers
- External services: Llama Parse API, OpenAI API
- Tech stack: Python, FastAPI, pdfplumber, PyPDF2, Docker, Pytest

##### Components
- Client / Consumer (e.g., curl, frontend)
- FastAPI App (app/main.py)
- CompositeValidator
- ExtensionValidator
- SizeValidator
- MimeValidator
- PDFProcessor (uses pdfplumber / PyPDF2 / OCR)
- TextParser (Llama Parse Service)
- FieldExtractor (OpenAI GPT-4o-mini Model Handler)
- JSON Formatter / Response
b. External services & libraries:
- Llama Parse API
- OpenAI API
- pdfplumber, PyPDF2 (local)
c. Data stores: none (stateless service)
d. Tests: separate test harness (not on the critical path)

1. Client → FastAPI endpoint (POST /extract)
2. FastAPI → CompositeValidator → each validator → return OK or error
3. Validated file → PDFProcessor → raw text (or OCR‐converted text)
4. Raw text → TextParser (Llama Parse) → structured Markdown/text
5. Parsed text → FieldExtractor (OpenAI API) → JSON fields
6. JSON → FastAPI → Client response

##### Architectural patterns & principles
- Modular pipeline: each step isolated in its own class
- SOLID:
- Single Responsibility: validators only validate, processors only extract, models only handle API calls
- Open/Closed: new file types or models added via subclassing
- Dependency Injection: FastAPI injects dependencies (e.g., validator, processor) into endpoints
- Stateless microservice: no persistent storage, scales horizontally

##### Don’t omit these essential details
- CompositeValidator orchestrating individual validators
- PDFProcessor’s fallback to OCR for scanned docs
- Two distinct AI steps: Llama Parse for text structuring + GPT-4o-mini for field extraction
- Docker boundary indicating environment variables (.env) and container ports

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client<br/>(curl, frontend)"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        FastAPI["FastAPI App<br/>(app/main.py)"]:::entrypoint
        click FastAPI "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/main.py"

        %% Validators Package
        subgraph "app/validators"
            direction TB
            CompositeValidator["CompositeValidator"]:::internal
            click CompositeValidator "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/validators/composite_validator.py"
            ExtensionValidator["ExtensionValidator"]:::internal
            click ExtensionValidator "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/validators/extention_validator.py"
            SizeValidator["SizeValidator"]:::internal
            click SizeValidator "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/validators/size_validator.py"
            MimeValidator["MimeValidator"]:::internal
            click MimeValidator "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/validators/mime_validator.py"
            BaseValidator["BaseValidator"]:::internal
            click BaseValidator "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/validators/base_validator.py"
        end

        %% Processors Package
        subgraph "app/processors"
            direction TB
            PDFProcessor["PDFProcessor"]:::internal
            click PDFProcessor "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/processors/pdf_processor.py"
            BaseProcessor["BaseProcessor"]:::internal
            click BaseProcessor "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/processors/base_processor.py"
        end

        %% AI & Parsing Components
        TextParser["TextParser<br/>(Llama Parse)"]:::internal
        click TextParser "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/prompts/llama_parser_prompt.txt"
        FieldExtractor["FieldExtractor<br/>(OpenAI GPT-4o-mini)"]:::internal
        click FieldExtractor "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/app/models/openai_models.py"

        JSONFormatter["JSON Formatter / Response"]:::internal

        %% Container Definitions & Docs
        DockerDef["Dockerfile/.dockerignore"]:::internal
        click DockerDef "https://github.com/ahmedelzaria/lab-result-extraction/tree/main/Dockerfile"
        Requirements["requirements.txt"]:::internal
        click Requirements "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/requirements.txt"
        README["README.md"]:::internal
        click README "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/README.md"
        UML["uml/structure.puml"]:::internal
        click UML "https://github.com/ahmedelzaria/lab-result-extraction/blob/main/uml/structure.puml"
        Tests["tests/"]:::internal
        click Tests "https://github.com/ahmedelzaria/lab-result-extraction/tree/main/tests/"
    end

    %% External Services
    LlamaAPI["Llama Parse API"]:::external
    OpenAIAPI["OpenAI API"]:::external
    PDFLibs["pdfplumber & PyPDF2 (local)"]:::external

    %% Data Flow
    Client -->|1. POST /extract| FastAPI
    FastAPI -->|2. validate| CompositeValidator
    CompositeValidator -->|calls| ExtensionValidator
    CompositeValidator -->|calls| SizeValidator
    CompositeValidator -->|calls| MimeValidator
    CompositeValidator -->|uses interface| BaseValidator
    CompositeValidator -->|3. validated file| PDFProcessor
    PDFProcessor -->|uses| PDFLibs
    PDFProcessor -->|4. raw text| TextParser
    TextParser -->|calls API| LlamaAPI
    TextParser -->|5. structured text| FieldExtractor
    FieldExtractor -->|calls API| OpenAIAPI
    FieldExtractor -->|6. JSON fields| JSONFormatter
    JSONFormatter -->|response| FastAPI
    FastAPI -->|response| Client

    %% Styles
    classDef internal fill:#ccffcc,stroke:#2d662d,color:#000;
    classDef external fill:#cce5ff,stroke:#1f4a9e,color:#000;
    classDef entrypoint fill:#ffe0b3,stroke:#b36b00,color:#000;
```
