# manavtriv/qsm-ci-platform architecture

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

- Interactive diagram: https://gitdiagram.com/manavtriv/qsm-ci-platform
- Repository: https://github.com/manavtriv/qsm-ci-platform

## Overview

##### Project type and purpose
- This is a single-page React application (built with Vite) that serves as a front-end “platform” for visualizing, comparing, and ranking Quantitative Susceptibility Mapping (QSM) algorithms.
- It relies on a Backend-as-a-Service (Parse/Back4App) for data persistence and ELO ranking logic.

##### File structure
- Top-level:
- .github/workflows – CI jobs (tests, Vercel deploy)
- public + index.html – static assets & host page
- src/ – all front-end code:
◦ components/ – UI building blocks (Algorithm pages, Niivue viewer, charts, tables, filters)
◦ pages/ – route entry points (Home, Overview, Compare, etc.)
◦ hooks/ – custom React hooks encapsulating data-fetching and business logic
◦ api/ – Parse JS SDK initialization & API wrappers
◦ config/ – metrics & tag-group definitions
◦ routes/ – React Router setup
◦ utils/ – helper functions
◦ styles/ – global CSS (Tailwind)
- test/ + __tests__ – Vitest + React Testing Library setup and tests
- Vite, ESLint, Vitest, and environment (.env.example) files configure build, lint, test, and runtime.

##### Insights from README
- SPA with React Router v7
- Styling via Tailwind CSS
- Interactive 3D imaging via Niivue
- Charts via Recharts
- Data persistence and ranking logic via Parse/Back4App JS SDK
- Deployment to Vercel, CI via GitHub Actions

##### Detail
- Break the front end into **Pages**, **Components**, and **Hooks**.
- **config** modules feeding into Hooks or Components.
- **public/index.html** + Vite build as the entry point.
- Don’t omit the **.env** → API keys → Parse SDK relationship.
- **CI workflows** for testing & deployment.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client & Frontend
    subgraph "Client & Frontend"
        direction TB
        Browser["User Browser"]:::external
        Index["index.html"]:::external
        Main["src/main.jsx"]:::logic
        App["src/App.jsx"]:::logic
        Router["src/routes/AppRouter.jsx"]:::logic

        subgraph "Pages" 
            direction TB
            Home["Home.jsx"]:::ui
            Overview["Overview.jsx"]:::ui
            Compare["Compare.jsx"]:::ui
            AlgorithmPage["Algorithm.jsx"]:::ui
            MetricPage["Metric.jsx"]:::ui
            GraphsPage["Graphs.jsx"]:::ui
            ImagesPage["Images.jsx"]:::ui
            Contribute["Contribute.jsx"]:::ui
        end

        subgraph "UI Components"
            direction TB
            ComponentsDir["src/components/"]:::ui
        end

        subgraph "Custom Hooks"
            direction TB
            HooksDir["src/hooks/"]:::logic
        end

        ConfigDir["src/config/"]:::config
        UtilsDir["src/utils/"]:::config
        Styles["src/styles/index.css"]:::config

    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        ParseConfig["src/api/parseConfig.js"]:::logic
    end

    %% BaaS Backend
    subgraph "Parse/Back4App"
        direction TB
        ParseServer["Parse Server"]:::external
        DB[(MongoDB)]:::external
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        TestYML[".github/workflows/test.yml"]:::ci
        DeployYML[".github/workflows/vercel-deploy.yml"]:::ci
        Vercel["Vercel Hosting"]:::external
    end

    %% Connections
    Browser -->|loads| Index
    Index -->|boots| Main
    Main -->|renders| App
    App -->|routes via| Router
    Router -->|renders| Home
    Router -->|renders| Overview
    Router -->|renders| Compare
    Router -->|renders| AlgorithmPage
    Router -->|renders| MetricPage
    Router -->|renders| GraphsPage
    Router -->|renders| ImagesPage
    Router -->|renders| Contribute

    Router --> ComponentsDir
    App --> HooksDir
    HooksDir --> ParseConfig
    ConfigDir --> HooksDir
    UtilsDir --> HooksDir
    Styles --> App

    ParseConfig -->|SDK calls| ParseServer
    ParseServer -->|reads/writes| DB

    GitHubActions --> TestYML
    GitHubActions --> DeployYML
    DeployYML -->|deploys build to| Vercel

    %% CI Trigger
    GitPush((Git Push)):::external --> GitHubActions

    %% Asset fetch
    Browser -->|fetch static assets| Vercel

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef logic fill:#d4edda,stroke:#333,stroke-width:1px
    classDef config fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef ci fill:#f8d7da,stroke:#333,stroke-width:1px

    %% Click Events
    click Index "https://github.com/manavtriv/qsm-ci-platform/blob/main/index.html"
    click Main "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/main.jsx"
    click App "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/App.jsx"
    click Router "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/routes/AppRouter.jsx"
    click Home "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Home.jsx"
    click Overview "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Overview.jsx"
    click Compare "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Compare.jsx"
    click AlgorithmPage "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Algorithm.jsx"
    click MetricPage "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Metric.jsx"
    click GraphsPage "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Graphs.jsx"
    click ImagesPage "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Images.jsx"
    click Contribute "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/pages/Contribute.jsx"
    click ComponentsDir "https://github.com/manavtriv/qsm-ci-platform/tree/main/src/components/"
    click HooksDir "https://github.com/manavtriv/qsm-ci-platform/tree/main/src/hooks/"
    click ConfigDir "https://github.com/manavtriv/qsm-ci-platform/tree/main/src/config/"
    click UtilsDir "https://github.com/manavtriv/qsm-ci-platform/tree/main/src/utils/"
    click Styles "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/styles/index.css"
    click ParseConfig "https://github.com/manavtriv/qsm-ci-platform/blob/main/src/api/parseConfig.js"
    click TestYML "https://github.com/manavtriv/qsm-ci-platform/blob/main/.github/workflows/test.yml"
    click DeployYML "https://github.com/manavtriv/qsm-ci-platform/blob/main/.github/workflows/vercel-deploy.yml"
    click Vercel "https://github.com/manavtriv/qsm-ci-platform/blob/main/vercel.json"
```
