# rohitdayal-jktech/pdf-management architecture

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

- Interactive diagram: https://gitdiagram.com/rohitdayal-jktech/pdf-management
- Repository: https://github.com/rohitdayal-jktech/pdf-management

## Overview

##### Project type and purpose
- A React/Vite/Tailwind frontend
- A Python (FastAPI) backend
- A PostgreSQL database
- AI/LLM integrations (Gemini, Ollama)
- Docker and Kubernetes (via Terraform) for containerization and deployment

##### File structure
Top‐level:
- frontend/ – React app with components, hooks, pages, store, Vite config, Tailwind
- backend/ – Python app (FastAPI style) with api/, core/, crud/, db/, services/, llm/, utils/
- terraform/ – Kubernetes deployment manifests for frontend, backend, Postgres
- docker‐compose.yml – local multi‐container setup
Patterns & layers in backend:
- API layer (app/api/v1/*.py)
- Business logic/services (app/services/*)
- Data access (app/crud/*, app/db/models, schemas, session)
- Utilities (PDF parsing in app/utils/pdf_utils.py)
- LLM adapters (app/llm/*)

##### Key points from the README
- “AI‐powered book management” – must show AI summarization/categorization flows
- Emphasis on generative AI – show external LLM services as separate components

##### Main components & interactions
a. Frontend (React/Vite)
- Hosts UI pages (Login, Signup, Dashboard, Book Table, Modals)
- Calls Backend REST API over HTTPS
b. Backend (FastAPI)
- Exposes /api/v1/{auth, users, books} endpoints
- Business layer invokes CRUD for DB, PDF utils, LLM adapters
- Maintains session to Postgres
c. Database (PostgreSQL)
- Stores users and book metadata
d. PDF storage & processing
- Local or cloud file store for uploaded PDFs
- PDF utility module processes file, extracts text
e. AI/LLM services
- Gemini chatbot, Ollama chatbot (selected via chatbot_selector)
- Called by backend to generate summaries, categories
f. Infrastructure layer
- Docker containers for frontend, backend, Postgres
- Kubernetes cluster (Terraform) orchestrates deployments, services

##### Architectural patterns & design principles
- Layered (“Clean”) architecture in backend: API → Services → CRUD/Data layer → DB
- Separation of concerns: UI vs API vs Data vs AI Integrations
- Micro‐deployment: each major service (frontend, backend, DB) runs in its own container/pod
- Stateless backend pods behind a load balancer, persistent Postgres storage

##### How to represent this
Components:
- UI Layer: Browser/Client → Frontend container
- API Layer: Backend container (FastAPI)
- Data Layer: PostgreSQL container
- Storage: PDF file store (volume or S3)
- AI Layer: External LLM services (Gemini, Ollama – treat as external APIs)
- Infrastructure: Docker & Kubernetes (control plane, deployments, services)

Relationships & data flow:
1. User interacts with Frontend (HTTP)
2. Frontend calls Backend REST API (HTTPS)
3. Backend ↔ PostgreSQL (SQL over TCP)
4. Backend → PDF storage (upload/download)
5. Backend → LLM services (chatbot_selector routes to Gemini/Ollama API endpoints)
6. Terraform/K8s manages container deployments, load balancing

##### Must‐include elements
- Annotations for critical interactions (e.g., “Generate Summary → LLM API”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["User Browser"]:::ui
        Frontend["Frontend Container"]:::ui
    end

    Browser -->|HTTP| Frontend

    %% API Layer / Backend
    subgraph "API Layer / Backend"
        direction TB
        Backend["FastAPI Backend"]:::api
        subgraph "Clean Architecture"
            direction TB
            APIEndpoints["app/api/v1 endpoints"]:::api
            Services["app/services layer"]:::api
            CRUDLayer["app/crud & data layer"]:::api
            DBModels["app/db/models & schemas"]:::api
            PDFUtils["PDF Utils (pdf_utils.py)"]:::api
            LLMAdapters["LLM Adapters"]:::api
        end
    end

    Frontend -->|HTTPS REST| APIEndpoints
    APIEndpoints -->|invoke| Services
    Services -->|use CRUD| CRUDLayer
    CRUDLayer -->|SQL over TCP| Postgres
    Services -->|process PDF| PDFUtils
    Services -->|call LLM| LLMAdapters

    %% AI / LLM Flow
    subgraph "External AI Services"
        direction TB
        ChatSelector["Chatbot Selector"]:::external
        Gemini["Gemini LLM"]:::external
        Ollama["Ollama LLM"]:::external
    end

    LLMAdapters -->|select| ChatSelector
    ChatSelector -->|to Gemini API| Gemini
    ChatSelector -->|to Ollama API| Ollama

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres(("PostgreSQL")):::data
    end

    %% Storage
    subgraph "Storage"
        direction TB
        FileStore(("PDF File Store")):::data
    end

    Backend -->|upload/download| FileStore

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        DockerCompose["docker-compose.yml"]:::infra
        Kubernetes["Kubernetes via Terraform"]:::infra
    end

    DockerCompose -.-> Frontend
    DockerCompose -.-> Backend
    DockerCompose -.-> Postgres

    Kubernetes -.-> Frontend
    Kubernetes -.-> Backend
    Kubernetes -.-> Postgres

    %% Click Events
    click Frontend "https://github.com/rohitdayal-jktech/pdf-management/tree/main/rohit-dayal-pdf-management/frontend/"
    click APIEndpoints "https://github.com/rohitdayal-jktech/pdf-management/tree/main/rohit-dayal-pdf-management/backend/app/api/v1/"
    click Services "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/backend/app/services/book.py"
    click CRUDLayer "https://github.com/rohitdayal-jktech/pdf-management/tree/main/rohit-dayal-pdf-management/backend/app/crud/"
    click DBModels "https://github.com/rohitdayal-jktech/pdf-management/tree/main/rohit-dayal-pdf-management/backend/app/db/"
    click PDFUtils "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/backend/app/utils/pdf_utils.py"
    click LLMAdapters "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/backend/app/llm/chatbot_selector.py"
    click ChatSelector "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/backend/app/llm/chatbot_selector.py"
    click Gemini "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/backend/app/llm/gemini_chatbot.py"
    click Ollama "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/backend/app/llm/ollama_chatbot.py"
    click DockerCompose "https://github.com/rohitdayal-jktech/pdf-management/blob/main/rohit-dayal-pdf-management/docker-compose.yml"
    click Kubernetes "https://github.com/rohitdayal-jktech/pdf-management/tree/main/rohit-dayal-pdf-management/terraform/"

    %% Styles
    classDef ui fill:#CCE5FF,stroke:#333,stroke-width:1px
    classDef api fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef data fill:#FFDD99,stroke:#333,stroke-width:1px
    classDef external fill:#E0B3FF,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
```
