# benlebich/ask-my-pdf-1hxbyzcwbscgzdxz architecture

> Architecture diagram of the GitHub repository benlebich/ask-my-pdf-1hxbyzcwbscgzdxz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz
- Repository: https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz

## Overview

##### Project Type and Purpose
- This is a full-stack Ruby on Rails application supplemented by React/TypeScript components (via Shakapacker).
- Its purpose is to take an input PDF, convert its pages into vector embeddings, store/cache those embeddings, expose a query interface, retrieve relevant pages for a user’s question, and finally produce a “completion” by calling the OpenAI Davinci API.

##### File-Structure Analysis & Architectural Insights
- Top-level “app” directory follows Rails MVC:
- app/controllers → HTTP endpoints (PagesController, QuestionsController, UsersController)
- app/models → ActiveRecord models (CachedResponse stores embeddings, questions, answers)
- app/views → ERB and React mounts for server-rendered pages
- app/services/pdf_to_embeddings.rb → encapsulates PDF parsing and embedding logic
- JavaScript lives under app/javascript:
- components/*.tsx → React components (AskMyPdf.tsx, Home.tsx)
- packs/*.js → webpack entry points for browser and SSR
- Persistence & config:
- config/database.yml → PostgreSQL (or other) for model storage
- config/storage.yml → local/disk or cloud storage for file uploads
- config/cable.yml → ActionCable WebSockets (unused for core flow unless streaming)
- Docker & Deployment:
- Dockerfile + .dockerignore → containerize Rails + web server (Puma)
- fly.toml → configuration for Fly.io deployment
- Data folder contains precomputed CSV embeddings for offline workflows or seed data.

##### Key Components & Interactions
A. Client (Web Browser)
B. Rails Web Application (Puma)
1. Controllers (Pages, Questions)
2. Service Layer (PDF→Embeddings)
3. Model Layer (CachedResponse)
4. Views / React Bundles
C. Database (PostgreSQL)
D. File Storage (Local Disk or S3 via ActiveStorage)
E. External API (OpenAI Davinci)
F. Optional: Webpack Dev Server (for local JS hot-reload)

##### Data-flow & Relationships
- User uploads/selects a PDF via the React UI → HTTP POST to Rails endpoint
- Rails Controller invokes PdfToEmbeddings service:
- Service reads PDF (ActiveStorage), splits pages, calls embedding routine
- Embeddings and page metadata persisted in CachedResponse model → Database
- User submits a query → QuestionsController retrieves top-K relevant embeddings from Database
- Rails assembles context pages and forwards a prompt to OpenAI API → receives completion
- Completion + metadata saved to CachedResponse (cache lookup on same question next time)
- Response JSON rendered back to React UI → displayed to user

##### Architectural Patterns & Design Principles
- MVC for HTTP and page rendering
- Service Object pattern (pdf_to_embeddings.rb) to isolate business logic
- ActiveRecord for persistence and caching
- Webpacker / Shakapacker for React integration
- External API integration abstracted in service calls
- Docker for environment consistency

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Web Browser (React UI)"]:::external

    %% Rails Application
    subgraph "Rails Application (Puma)" 
        direction TB
        subgraph "Controllers" 
            direction TB
            PagesController["PagesController (Ruby on Rails)"]:::internal
            QuestionsController["QuestionsController (Ruby on Rails)"]:::internal
            UsersController["UsersController (Ruby on Rails)"]:::internal
        end
        subgraph "Service Layer"
            direction TB
            PdfService["PdfToEmbeddings Service"]:::internal
        end
        subgraph "Model Layer"
            direction TB
            CachedResponse["CachedResponse Model"]:::internal
        end
        subgraph "Views / React Bundles"
            direction TB
            HomeView["home.html.erb & React Mount"]:::internal
            LayoutView["application.html.erb"]:::internal
        end
    end

    %% Data Stores
    Database["PostgreSQL Database"]:::datastore
    Storage["File Storage (ActiveStorage)"]:::datastore

    %% External Systems
    OpenAI["OpenAI Davinci API"]:::external
    WebpackDev["Webpack Dev Server"]:::external

    %% Connections
    Browser -->|"HTTP/JSON"| PagesController
    Browser -->|"HTTP/JSON"| QuestionsController

    PagesController -->|"invoke"| PdfService
    QuestionsController -->|"invoke"| PdfService

    PdfService -->|"SQL read/write"| CachedResponse
    CachedResponse -->|"persist embeddings"| Database

    PdfService -->|"file read/write"| Storage

    PdfService -->|"REST API (HTTP)"| OpenAI
    OpenAI -->|"response"| PdfService

    PagesController -->|"render"| HomeView
    PagesController -->|"render layout"| LayoutView

    QuestionsController -->|"render JSON"| Browser

    Browser -->|"hot-reload"| WebpackDev

    %% Click Events
    click Browser "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/javascript/components/AskMyPdf.tsx"
    click Browser "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/javascript/components/Home.tsx"
    click Browser "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/javascript/packs/application.js"
    click Browser "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/javascript/packs/server_rendering.js"

    click PagesController "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/controllers/pages_controller.rb"
    click QuestionsController "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/controllers/questions_controller.rb"
    click UsersController "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/controllers/users_controller.rb"

    click PdfService "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/services/pdf_to_embeddings.rb"

    click CachedResponse "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/models/cached_response.rb"
    click CachedResponse "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/db/migrate/20231020212820_create_cached_responses.rb"

    click HomeView "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/views/pages/home.html.erb"
    click LayoutView "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/app/views/layouts/application.html.erb"

    click Database "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/config/database.yml"

    click Storage "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/config/storage.yml"
    click Storage "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/tree/main/storage/"

    click WebpackDev "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/tree/main/bin/shakapacker-dev-server"
    click WebpackDev "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/config/webpack/webpack.config.js"

    click Dockerfile "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/tree/main/Dockerfile"
    click Dockerfile "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/.dockerignore"
    click Dockerfile "https://github.com/benlebich/ask-my-pdf-1hxbyzcwbscgzdxz/blob/main/fly.toml"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef datastore fill:#DFFFE0,stroke:#1A7F37,stroke-width:1px;
    classDef external fill:#FFE8D0,stroke:#D97706,stroke-width:1px;
```
