# voynow/chat-with-jfk-files architecture

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

- Interactive diagram: https://gitdiagram.com/voynow/chat-with-jfk-files
- Repository: https://github.com/voynow/chat-with-jfk-files

## Overview

##### Project Type and Purpose
- This project is a full-stack application. The backend is primarily implemented in Python (using a modular package named “chat_with_jfk_files”), which handles core functionality (chat logic, integrating with LLMs, OCR processing, embeddings management, etc.). The frontend is built separately under the “webapp” directory using Next.js with TypeScript, React components, and Tailwind CSS.
- The README (“the name speaks for itself”) together with the file structure suggests that the project’s intent is to interactively chat with document files (possibly historical or similar to JFK documentation), utilizing OCR to process text, language models (LLMs) for conversation, and embeddings to enhance search or similarity matching.

##### Analyzing the File Structure
- There are two top-level application parts:
– The Python backend with core functionality in the “src/chat_with_jfk_files” directory. This submodule includes files like chat.py (potentially coordinating conversation logic), llm.py (to interface with large language models), ocr.py (to handle optical character recognition), prompts.py, and constants.
– A separate “webapp” directory that contains the frontend using Next.js and related configurations (e.g., next.config.ts, tailwind.config.ts, package.json). The webapp components include a ChatInterface, Landing page, and a SupportModal which suggests a dedicated UI for user interaction.
- Additionally, there are supporting scripts like create_embeddings.ipynb (likely for testing or preprocessing embeddings), download.py (for fetching external resources), and containerization (a dockerfile) for deployment.
- Testing is done using the “tests” directory, implying that core functionality has unit tests (e.g., tests/test_chat.py).

##### Architectural Components and Relationships
- Main components:
- Frontend (Webapp):
▪ Built with Next.js/React using TypeScript.
▪ Contains UI components such as ChatInterface, Landing page, and SupportModal.
- Backend Core (chat_with_jfk_files package):
▪ Chat Module: Manages conversation protocols.
▪ LLM Module: Interfaces with language models to generate responses.
▪ OCR Module: Processes image or file inputs to extract text.
▪ Prompts & Constants Module: Manage prompt templates and configuration constants.
▪ Embeddings: Stored in “embeddings.parquet”, possibly used for text similarity or retrieval.
- Supporting Scripts & Tools:
▪ Data processing (create_embeddings.ipynb and download.py).
▪ Testing modules to ensure the quality and correctness of backend logic.
- Containerization (dockerfile) indicates that the entire application can be deployed inside containers.
- Interactions:
- The Frontend sends user requests (chat messages or file uploads) to the Backend.
- The Backend processes these requests by possibly running OCR on images/files, querying or calculating LLM responses, and utilizing stored embeddings.
- The responses are then supplied back to the Frontend.

##### Important Architectural Patterns and Principles
- Modular Separation: Clearly separated concerns between the presentation layer (webapp) and the business logic (Python backend). This supports the Single Responsibility Principle in each module.
- Service/Component Communication: Likely a RESTful API or similar communication method between the web frontend and backend.
- Containerization: With the presence of a dockerfile, the architecture supports deployment via Docker, ensuring consistency across environments.
- Testing in Isolation: The “tests” directory ensures that backend components (e.g., chat logic) are independently verified.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend"
        F1("ChatInterface Component"):::frontend
        F2("Landing Page Component"):::frontend
        F3("SupportModal Component"):::frontend
    end

    %% Backend Subgraph
    subgraph "Backend"
        B0("Python Backend Package"):::backend
        B1("Chat Module"):::backend
        B2("LLM Processing"):::backend
        B3("OCR Processing"):::backend
        B4("Prompts"):::backend
        B5("Constants"):::backend
        B6("Embeddings Management"):::backend
    end

    %% Supporting Tools Subgraph
    subgraph "Supporting Tools"
        S1("Create Embeddings Script"):::support
        S2("Resource Downloader"):::support
        S3("Backend Testing"):::support
        S4("Containerization"):::support
    end

    %% Frontend to Backend Communication
    F1 -->|"api_call"| B1
    F2 -->|"api_call"| B1
    F3 -->|"api_call"| B1

    %% Backend Internal Communications
    B1 -->|"callsLLM"| B2
    B1 -->|"callsOCR"| B3
    B1 -->|"usesPrompts"| B4
    B1 -->|"usesConfig"| B5
    B1 -->|"retrievesEmbeddings"| B6

    %% Supporting Tools Interactions
    S1 -->|"preprocesses"| B6
    S2 -->|"fetches"| B6
    S3 -->|"tests"| B1
    S4 -->|"deploys"| B0

    %% Click Events for Component Mapping
    click B0 "https://github.com/voynow/chat-with-jfk-files/tree/main/src/chat_with_jfk_files"
    click B1 "https://github.com/voynow/chat-with-jfk-files/blob/main/src/chat_with_jfk_files/chat.py"
    click B2 "https://github.com/voynow/chat-with-jfk-files/blob/main/src/chat_with_jfk_files/llm.py"
    click B3 "https://github.com/voynow/chat-with-jfk-files/blob/main/src/chat_with_jfk_files/ocr.py"
    click B4 "https://github.com/voynow/chat-with-jfk-files/blob/main/src/chat_with_jfk_files/prompts.py"
    click B5 "https://github.com/voynow/chat-with-jfk-files/blob/main/src/chat_with_jfk_files/constants.py"
    click B6 "https://github.com/voynow/chat-with-jfk-files/blob/main/src/chat_with_jfk_files/embeddings.parquet"
    click F1 "https://github.com/voynow/chat-with-jfk-files/blob/main/webapp/src/app/components/ChatInterface.tsx"
    click F2 "https://github.com/voynow/chat-with-jfk-files/blob/main/webapp/src/app/components/Landing.tsx"
    click F3 "https://github.com/voynow/chat-with-jfk-files/blob/main/webapp/src/app/components/SupportModal.tsx"
    click S1 "https://github.com/voynow/chat-with-jfk-files/blob/main/create_embeddings.ipynb"
    click S2 "https://github.com/voynow/chat-with-jfk-files/blob/main/download.py"
    click S3 "https://github.com/voynow/chat-with-jfk-files/blob/main/tests/test_chat.py"
    click S4 "https://github.com/voynow/chat-with-jfk-files/tree/main/dockerfile"

    %% Class Definitions for Colors
    classDef frontend fill:#a0d468,stroke:#333,stroke-width:2px,color:#000;
    classDef backend fill:#4a89dc,stroke:#333,stroke-width:2px,color:#fff;
    classDef support fill:#f6bb42,stroke:#333,stroke-width:2px,color:#000;
```
