# bl19/sumhub architecture

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

- Interactive diagram: https://gitdiagram.com/bl19/sumhub
- Repository: https://github.com/bl19/sumhub

## Overview

##### Main Components
- User Interface / Frontend:
– Built using Next.js (React based) with server-side rendering.
– Handles page routing, SEO friendly content, and provides UI components (using Tailwind CSS and ShadCN UI).
– Exists as a separate module (“frontend/sumhub”) packaged into a Docker image.

- Backend API Server:
– An Express.js application running in Bun.
– Provides various API endpoints (e.g., /api/routes for paper search, get, and post operations).
– Serves as a bridge to database access and external services.

- Database Services:
– MongoDB Atlas is used to store all papers and supporting data.
– Pinecone acts as the vector database to store document embeddings.

- AI/Embedding Service:
– Google Gemini is used to generate 768-dimensional vectors for research papers.

- DevOps / CI-CD Pipeline:
– GitHub Actions (configured in the .github/workflows directory) to build and publish Docker images upon pushes to main.
– These images are pushed to Docker Hub (for both frontend and backend).

##### Relationships and Interactions
- Users access the frontend application via a web browser.

- The Frontend interacts with the Backend API for data fetching and search operations.

- The Backend communicates with two principal data stores: MongoDB Atlas (for structured paper metadata) and Pinecone (for vector search).

- Before or during the ingestion process, the Backend calls out to Google Gemini to obtain the embeddings.

- Both Frontend and Backend are independently containerized.
– Group them with “Docker Containers” and indicate their deployment via Docker Compose or Kubernetes.

- CI/CD Integration:
– Include “GitHub Actions” as a distinct component that pushes to “Docker Hub”.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– Differentiate the UI (Next.js) from the API & business logic (Express/Bun) and data management layers.

- Containerization & Continuous Deployment:
– Emphasize that both modules are built, tested, and deployed in isolation via Docker, fostering reproducible builds.

- Data Flow and Microservices Elements:
– Although not strictly microservices, the modular separation paints a similar picture: the Frontend consumes data from a clearly defined API, and the API further orchestrates between multiple services (MongoDB, Pinecone, Gemini).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction
    U("User"):::user

    %% Web Layer
    subgraph "Web Layer"
        FE("Frontend (Next.js)"):::frontend
        BE("Backend API (Express on Bun)"):::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        MDB("MongoDB Atlas"):::db
        PC("Pinecone Vector DB"):::db
    end

    %% External Services
    subgraph "External Services"
        GEM("Google Gemini Embeddings"):::external
    end

    %% Containerization
    subgraph "Containerization"
        FCont("Frontend Docker"):::container
        BCont("Backend Docker"):::container
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GHA("GitHub Actions"):::cicd
        DHF("Docker Hub (Frontend)"):::cicd
        DHB("Docker Hub (Backend)"):::cicd
    end

    %% Connections
    U -->|"HTTP_request"| FE
    FE -->|"API_call"| BE
    BE -->|"CRUD_ops"| MDB
    BE -->|"Vector_search"| PC
    BE -->|"Embedding_gen"| GEM
    FE -->|"Deployed_as"| FCont
    BE -->|"Deployed_as"| BCont
    GHA -->|"Publish_images"| DHF
    GHA -->|"Publish_images"| DHB

    %% Click Events
    click FE "https://github.com/bl19/sumhub/tree/main/frontend/sumhub"
    click BE "https://github.com/bl19/sumhub/tree/main/backend/src/api"
    click MDB "https://github.com/bl19/sumhub/tree/main/backend/src/db"
    click PC "https://github.com/bl19/sumhub/blob/main/backend/src/lib/pinecone.ts"
    click GEM "https://github.com/bl19/sumhub/blob/main/backend/src/lib/gemini.ts"
    click GHA "https://github.com/bl19/sumhub/blob/main/.github/workflows/build-and-publish-docker.yml"
    click FCont "https://github.com/bl19/sumhub/tree/main/frontend/sumhub/Dockerfile"
    click BCont "https://github.com/bl19/sumhub/tree/main/backend/Dockerfile"

    %% Styles
    classDef user fill:#f9c,stroke:#333,stroke-width:2px;
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#bfb,stroke:#333,stroke-width:2px;
    classDef db fill:#ffc,stroke:#333,stroke-width:2px;
    classDef external fill:#fc9,stroke:#333,stroke-width:2px;
    classDef container fill:#edf,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fdd,stroke:#333,stroke-width:2px;
```
