# adityak74/pdf-extractor-api architecture

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

- Interactive diagram: https://gitdiagram.com/adityak74/pdf-extractor-api
- Repository: https://github.com/adityak74/pdf-extractor-api

## Overview

##### Project Type and Purpose
- This is a full-stack API application focused on extracting content from PDF files.
- The FastAPI framework is used to expose RESTful endpoints, and there’s heavy use of PDF processing libraries (PyMuPDF, pdfplumber, Pillow) along with SQLAlchemy and PostgreSQL for persistence.
- Background workers (APScheduler, file_cleanup in workers) add support for automatic cleanup tasks.

##### File Structure
- The top-level structure includes configuration files (Dockerfile, docker-compose.yml, .env.example), migration scripts (alembic), tests, and directories for uploads.
- The core application is located in the “app” folder, which is split into several components:
- Controllers (app/controllers): Responsible for handling API endpoint requests (pdf_controller, worker_controller).
- Services (app/services): Houses business logic (pdf_service).
- Database (app/database): Contains connection setup, ORM models, and repository patterns for persistence.
- Models (app/models): Defines request and response schemas.
- Workers (app/workers): Implements background processing (file_cleanup).
- Utils (app/utils): Contains helper functions (file_utils, check_config).
- The “main.py” in the “app” directory is the application’s entry point.
- Migration scripts are maintained under “alembic”, which shows database versioning is key.
- The “uploads” folder acts as a file storage location for both PDFs and image outputs.

a. Main Components:
- API Layer: Represent the FastAPI “app” with endpoints defined via the controllers.
- Business Logic Layer: The services, specifically pdf_service that performs extraction logic.
- Database Layer: Incorporate the SQLAlchemy models, connection, and repository from “app/database”, plus align to the Alembic migration mechanism.
- Background Workers: Include the file_cleanup worker process from “app/workers”.
- Utility Components: Represent file and configuration utilities.
- External Dependencies: PDF parsing libraries (PyMuPDF, pdfplumber, Pillow) along with the PostgreSQL database.
- Deployment and Infrastructure: Docker, docker-compose configuration, and environment management for containerized deployments.

b. Interactions and Data Flow:
- Controllers delegate to services where PDF extraction processing occurs.
- The service layer then interacts with the database layer for storing/retrieving metadata and extracted content.
- Background workers should be shown as periodically triggered (via APScheduler or similar mechanism) to perform tasks like cleaning up old files.
- Utility modules support multiple layers with helper functions.
- The external storage for uploads (PDFs and images) should be depicted, alongside the direct dependencies on third-party libraries.

c. Architectural Patterns and Design Principles:
- A layered, modular structure: separation of concerns between routing (controllers), business logic (services), and data persistence (database/repository).
- Incorporate a REST API pattern.
- That dependency injection might be in use via FastAPI.
- Background job management is part of the reliability design.

d. Technologies, Frameworks, and Libraries:
- FastAPI for the core API.
- Uvicorn as the ASGI server.
- SQLAlchemy (with Alembic) for ORM and migrations, connected to PostgreSQL.
- PDF extraction libraries: PyMuPDF, pdfplumber, Pillow.
- APScheduler for scheduling background cleanup tasks.
- Docker/Docker Compose for containerization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client"):::external

    subgraph "API Layer"
        A1["PDF Controller: Handles PDF extraction endpoints"]:::api
        A2["Worker Controller: Handles worker related endpoints"]:::api
    end

    subgraph "Business Logic Layer"
        BL["PDF Service: Extraction Logic"]:::service
    end

    subgraph "Database Layer"
        DB1["DB Connection & ORM Setup"]:::db
        DB2["ORM Models"]:::db
        DB3["Repository: Data Persistence"]:::db
    end

    subgraph "Models"
        M["Schemas: Request/Response"]:::util
    end

    subgraph "Background Workers"
        BW["File Cleanup Worker"]:::worker
    end

    subgraph "Utilities"
        U1["File Utils"]:::util
        U2["Config Checker"]:::util
    end

    subgraph "Deployment & Infrastructure"
        D1["Dockerfile"]:::deploy
        D2["Dockerfile.migrate"]:::deploy
        D3["docker-compose.yml"]:::deploy
        D4[".env.example"]:::deploy
        D5["Makefile"]:::deploy
        subgraph "Alembic Migrations"
            DM1["Alembic Env (env.py)"]:::deploy
            DM2["Initial Migration (alembic/versions)"]:::deploy
        end
    end

    subgraph "File Storage"
        FS["Uploads (PDFs & Images)"]:::storage
    end

    PDF_LIB["PDF Libraries (PyMuPDF, pdfplumber, Pillow)"]:::external
    POSTGRES["PostgreSQL Database"]:::external
    UVICORN["Uvicorn (ASGI Server)"]:::external

    Client --> A1
    Client --> A2
    A1 -->|"calls"| BL
    A2 -->|"calls"| BL
    BL -->|"validatesWith"| M
    BL -->|"persistsVia"| DB3
    DB3 -->|"uses"| DB1
    DB3 -->|"mapsWith"| DB2
    DB3 -->|"operatesOn"| POSTGRES
    BL -->|"utilizes"| PDF_LIB
    BL -->|"uses"| U1
    BL -->|"uses"| U2
    UVICORN --> A1
    UVICORN --> A2
    BW -->|"cleansFilesIn"| FS

    D1 --- D2
    D1 --- D3
    D1 --- D4
    D1 --- D5
    DM1 --- DM2

    click A1 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/controllers/pdf_controller.py"
    click A2 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/controllers/worker_controller.py"
    click BL "https://github.com/adityak74/pdf-extractor-api/blob/main/app/services/pdf_service.py"
    click DB1 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/database/connection.py"
    click DB2 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/database/models.py"
    click DB3 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/database/repository.py"
    click M "https://github.com/adityak74/pdf-extractor-api/blob/main/app/models/schemas.py"
    click BW "https://github.com/adityak74/pdf-extractor-api/blob/main/app/workers/file_cleanup.py"
    click U1 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/utils/file_utils.py"
    click U2 "https://github.com/adityak74/pdf-extractor-api/blob/main/app/utils/check_config.py"
    click D1 "https://github.com/adityak74/pdf-extractor-api/tree/main/Dockerfile"
    click D2 "https://github.com/adityak74/pdf-extractor-api/blob/main/Dockerfile.migrate"
    click D3 "https://github.com/adityak74/pdf-extractor-api/blob/main/docker-compose.yml"
    click D4 "https://github.com/adityak74/pdf-extractor-api/blob/main/.env.example"
    click D5 "https://github.com/adityak74/pdf-extractor-api/tree/main/Makefile"
    click DM1 "https://github.com/adityak74/pdf-extractor-api/blob/main/alembic/env.py"
    click DM2 "https://github.com/adityak74/pdf-extractor-api/blob/main/alembic/versions/initial_migration.py"
    click FS "https://github.com/adityak74/pdf-extractor-api/tree/main/uploads/"

    classDef api fill:#e8f4f8,stroke:#034f84,stroke-width:2px;
    classDef service fill:#f8e8f4,stroke:#a4047b,stroke-width:2px;
    classDef db fill:#f0f8e8,stroke:#2a7b2a,stroke-width:2px;
    classDef worker fill:#fff2cc,stroke:#d6b656,stroke-width:2px;
    classDef util fill:#e8eaf6,stroke:#3f51b5,stroke-width:2px;
    classDef deploy fill:#e0f7fa,stroke:#00838f,stroke-width:2px;
    classDef external fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef storage fill:#ffefd5,stroke:#d2691e,stroke-width:2px;
```
