# verma-lab/platlas architecture

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

- Interactive diagram: https://gitdiagram.com/verma-lab/platlas
- Repository: https://github.com/verma-lab/platlas

## Overview

##### Project Type and Purpose
- PLATLAS is a full-stack web application for exploring genome-wide association (GWAS/PheWAS) data across multiple ancestries.
- Frontend: React.js SPA with interactive plots (Manhattan, QQ, Hudson) and pages for GWAS, PheWAS, downloads, etc.
- Backend: Node.js + Express REST API that serves filtered data and handles AI-powered text processing.
- Data: File-based storage of summary statistics plus Firestore for vector/document storage used by the RAG/AI service.

##### High-Level Components
a. User Interface (Frontend)
– React.js application (Frontend/src)
– Components: plots (Manhattan.js, QQ.js, Hudson.js), pages (GWASPage, PhewasPage, Downloads), shared UI (NavigationBar, SearchBar).
– Client-side routing: React Router (Routes.js).
– Styling: Tailwind CSS, React Bootstrap.
b. API Layer (Backend)
– Express.js server (Backend/src/index.js)
– Routes (aiRoutes.js, phenotypeRoutes.js, index.js).
– Controllers (gwasController, phewasController, phenotypeController, snpMappingController).
– Middleware: auth.js.
c. Business Logic & Services
– Core services: gwasService, phewasService, phenotypeService, tabixService, snpMappingService, findFiles.
– AI & RAG: RagService orchestrates:
- TextProcessor, gemini (AI modules)
- chatService/TextOptimizer
- Firestore vector store (ai/db/firestore.js) and document store (ai/storage/documents.js, vectors.js)
d. Data Layer
– File system: compressed GWAS/PheWAS summary statistics (.gz, .tbi), pre-rendered plot images
– Firestore: vector embeddings and documents for retrieval-augmented generation
e. External Services
– OpenAI (or similar) APIs called by AI modules in services/ai
– Firestore (Google Cloud) for vector and document storage

##### Relationships and Data Flows
- User → Frontend UI
- Frontend → REST API calls (`/api/queryGWASData`, `/api/phewas`, `/api/getTopResults`, `/api/findfiles`, `/api/…AI`)
- API Layer → Controllers → Services
- Services:
- Data services read compressed files or Tabix indices
- AI services call external LLM endpoints and Firestore queries
- Services → Responses → Frontend
- Frontend → updates UI components/plots

##### Architectural Patterns and Design Principles
- Separation of Concerns: UI, API routing, controllers, business services, storage
- Component-based UI (React) for reusability
- Layered backend: routes → controllers → services → data/external
- RAG pattern: uses vector store + LLM for AI-driven features
- Lazy loading & caching in frontend to optimize large data sets

##### Detail Level
- Drill into critical flows: e.g., a user click on a “Manhattan point” triggers `/api/queryGWASData` → gwasController → gwasService → file read → JSON response
- Caching or lazy-loading if relevant

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User (Browser)"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        FrontendApp["React.js SPA"]:::frontend
        Routes["Routes.js"]:::frontend
        Manhattan["Manhattan.js"]:::frontend
        QQ["QQ.js"]:::frontend
        Hudson["Hudson.js"]:::frontend
        PheWASPlot["PheWASPlot.js"]:::frontend
        TopResults["TopResults.js"]:::frontend
        GWASPage["GWASPage.js"]:::frontend
        PhewasPage["PhewasPage.js"]:::frontend
        DownloadsPage["Downloads.js"]:::frontend
        NavBar["NavigationBar.js"]:::frontend
        SearchBar["SearchBar.js"]:::frontend
        ProtectedRoute["ProtectedRoute.js"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        direction TB
        Index["index.js"]:::api
        subgraph "Routes"
            AIRoutes["aiRoutes.js"]:::api
            PhenotypeRoutes["phenotypeRoutes.js"]:::api
            MainRouter["index.js"]:::api
        end
        AuthMiddleware["auth.js"]:::api
        subgraph "Controllers"
            GWASController["gwasController.js"]:::api
            PheWASController["phewasController.js"]:::api
            PhenotypeController["phenotypeController.js"]:::api
            SNPMController["snpMappingController.js"]:::api
            GPTController["gptController.js"]:::api
        end
    end

    %% Business Services Layer
    subgraph "Business Services"
        direction TB
        GWASService["gwasService.js"]:::service
        PheWASService["phewasService.js"]:::service
        PhenotypeService["phenotypeService.js"]:::service
        SNPMService["snpMappingService.js"]:::service
        TabixService["tabixService.js"]:::service
        FindFilesService["findFiles.js"]:::service
        GPTService["gptService.js"]:::service
        RagService["RagService.js"]:::service
        subgraph "AI Modules"
            direction TB
            TextProcessor["TextProcessor.js"]:::service
            GeminiModule["gemini.js"]:::service
        end
        subgraph "Chat Services"
            direction TB
            ChatService["chatService.js"]:::service
            TextOptimizer["TextOptimizer.js"]:::service
        end
        FirestoreDB["firestore.js"]:::service
        DocStorage["documents.js"]:::service
        VectorStorage["vectors.js"]:::service
    end

    %% Data Storage
    subgraph "Data Storage"
        direction TB
        GWASFiles["Summary Stats (.gz/.tbi)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        FirestoreCloud["Firestore (Cloud)"]:::external
    end

    %% Connections
    User -->|uses| FrontendApp
    FrontendApp -->|routes| Routes
    FrontendApp -->|renders| Manhattan
    FrontendApp -->|renders| QQ
    FrontendApp -->|renders| Hudson
    FrontendApp -->|renders| PheWASPlot
    FrontendApp -->|renders| TopResults
    FrontendApp -->|pages| GWASPage
    FrontendApp -->|pages| PhewasPage
    FrontendApp -->|pages| DownloadsPage
    FrontendApp -->|uses| NavBar
    FrontendApp -->|uses| SearchBar
    FrontendApp -->|uses| ProtectedRoute

    FrontendApp -->|HTTP REST| Index
    Index -->|uses| AIRoutes
    Index -->|uses| PhenotypeRoutes
    Index -->|uses| MainRouter
    AIRoutes -->|calls| GPTController
    PhenotypeRoutes -->|calls| PhenotypeController
    MainRouter -->|calls| GWASController
    MainRouter -->|calls| PheWASController
    MainRouter -->|calls| SNPMController
    AuthMiddleware -->|secures| MainRouter

    GWASController -->|invokes| GWASService
    PheWASController -->|invokes| PheWASService
    PhenotypeController -->|invokes| PhenotypeService
    SNPMController -->|invokes| SNPMService
    GPTController -->|invokes| GPTService

    GWASService -->|reads| TabixService
    PheWASService -->|reads| TabixService
    SNPMService -->|reads| FindFilesService
    PhenotypeService -->|reads| FindFilesService

    GPTService -->|orchestrates| RagService
    RagService -->|uses| TextProcessor
    RagService -->|uses| GeminiModule
    RagService -->|uses| ChatService
    ChatService -->|uses| TextOptimizer
    RagService -->|accesses| FirestoreDB
    RagService -->|accesses| DocStorage
    RagService -->|accesses| VectorStorage

    TabixService -->|reads files| GWASFiles
    FindFilesService -->|finds files| GWASFiles

    RagService -->|LLM calls| OpenAI
    FirestoreDB -->|cloud storage| FirestoreCloud

    %% Click Events
    click FrontendApp "https://github.com/verma-lab/platlas/tree/main/Frontend/src"
    click Routes "https://github.com/verma-lab/platlas/blob/main/Frontend/src/Routes.js"
    click Manhattan "https://github.com/verma-lab/platlas/blob/main/Frontend/src/plots/Manhattan.js"
    click QQ "https://github.com/verma-lab/platlas/blob/main/Frontend/src/plots/QQ.js"
    click Hudson "https://github.com/verma-lab/platlas/blob/main/Frontend/src/plots/Hudson.js"
    click PheWASPlot "https://github.com/verma-lab/platlas/blob/main/Frontend/src/plots/PheWASPlot.js"
    click TopResults "https://github.com/verma-lab/platlas/blob/main/Frontend/src/plots/TopResults.js"
    click GWASPage "https://github.com/verma-lab/platlas/blob/main/Frontend/src/pages/GWASPage.js"
    click PhewasPage "https://github.com/verma-lab/platlas/blob/main/Frontend/src/pages/PhewasPage.js"
    click DownloadsPage "https://github.com/verma-lab/platlas/blob/main/Frontend/src/pages/Downloads.js"
    click NavBar "https://github.com/verma-lab/platlas/blob/main/Frontend/src/components/NavigationBar.js"
    click SearchBar "https://github.com/verma-lab/platlas/blob/main/Frontend/src/components/SearchBar.js"
    click ProtectedRoute "https://github.com/verma-lab/platlas/blob/main/Frontend/src/components/ProtectedRoute.js"
    click Index "https://github.com/verma-lab/platlas/blob/main/Backend/src/index.js"
    click AIRoutes "https://github.com/verma-lab/platlas/blob/main/Backend/src/routes/aiRoutes.js"
    click PhenotypeRoutes "https://github.com/verma-lab/platlas/blob/main/Backend/src/routes/phenotypeRoutes.js"
    click MainRouter "https://github.com/verma-lab/platlas/blob/main/Backend/src/routes/index.js"
    click GWASController "https://github.com/verma-lab/platlas/blob/main/Backend/src/controllers/gwasController.js"
    click PheWASController "https://github.com/verma-lab/platlas/blob/main/Backend/src/controllers/phewasController.js"
    click PhenotypeController "https://github.com/verma-lab/platlas/blob/main/Backend/src/controllers/phenotypeController.js"
    click SNPMController "https://github.com/verma-lab/platlas/blob/main/Backend/src/controllers/snpMappingController.js"
    click GPTController "https://github.com/verma-lab/platlas/blob/main/Backend/src/controllers/gptController.js"
    click AuthMiddleware "https://github.com/verma-lab/platlas/blob/main/Backend/src/middleware/auth.js"
    click GWASService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/gwasService.js"
    click PheWASService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/phewasService.js"
    click PhenotypeService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/phenotypeService.js"
    click SNPMService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/snpMappingService.js"
    click TabixService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/tabixService.js"
    click FindFilesService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/findFiles.js"
    click GPTService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/gptService.js"
    click RagService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/RagService.js"
    click TextProcessor "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/AI/TextProcessor.js"
    click GeminiModule "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/AI/gemini.js"
    click ChatService "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/chat/chatService.js"
    click TextOptimizer "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/chat/TextOptimizer.js"
    click FirestoreDB "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/db/firestore.js"
    click DocStorage "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/storage/documents.js"
    click VectorStorage "https://github.com/verma-lab/platlas/blob/main/Backend/src/services/ai/storage/vectors.js"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef api fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef service fill:#e6f5d0,stroke:#333,stroke-width:1px
    classDef storage fill:#ffd699,stroke:#333,stroke-width:1px
    classDef external fill:#d5ccff,stroke:#333,stroke-width:1px
    classDef externalStorage fill:#ffdead,stroke:#333,stroke-width:1px
```
