# mr-rahul-paul/quantum-sim-hackiiitv architecture

> Architecture diagram of the GitHub repository mr-rahul-paul/quantum-sim-hackiiitv, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mr-rahul-paul/quantum-sim-hackiiitv
- Repository: https://github.com/mr-rahul-paul/quantum-sim-hackiiitv

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js and TypeScript. Its purpose is to provide an interactive quantum chemistry simulation (Variational Quantum Eigensolver) by combining a rich React-based UI, serverless API routes, and a standalone TypeScript backend that orchestrates calls to IBM Quantum APIs, an AI prediction model, and a MongoDB database.

##### File Structure
- app/
- “Project-Overview”, “curated-list”, “details”, “simulation” pages under the Next.js 13 “app” router
- serverless API routes in app/api/predict/route.ts and app/api/simulate/route.ts
- layout.tsx, globals.css – global layout and styling
- backend/
- main.ts – standalone TypeScript backend (likely Express or similar) listening on port 8000
- interfaces with IBM Quantum API, AI model, and MongoDB
- assets/ and public/ – static assets & video content
- Configuration & tooling
- next.config.ts, tsconfig.json – Next.js and TypeScript config
- package.json, package-lock.json – dependencies, scripts
- eslint.config.mjs, postcss.config.mjs – linting and CSS tooling

##### README
- Tech Stack confirms: Next.js front-end, TypeScript, Framer Motion, IBM Quantum APIs, AI model, MongoDB
- There’s a backend TypeScript API server for quantum calculations
- Environment variables: NEXT_PUBLIC_API_URL, MONGODB_ATLAS_URI, IBMQ_API_TOKEN
- Deployment: Frontend on Vercel, backend on a separate Node host or serverless function

##### Components & Interactions
a. Main Components
– Client Browser (React UI)
– Next.js Frontend (Pages & SSR)
– Next.js Serverless API Routes (“/api/predict”, “/api/simulate”)
– Standalone Backend Service (Node/Express in backend/main.ts)
– AI Prediction Model (internal to backend)
– IBM Quantum Cloud Service
– MongoDB Atlas Database
– Static Asset Store (Vercel or CDN)
b. Relationships & Data Flow
– Client → Next.js Pages (SSR or CSR)
– Pages → Serverless API Routes (fetch)
– API Routes ↔ Backend Service (HTTP POST to NEXT_PUBLIC_API_URL)
– Backend → IBM Quantum API (POST quantum circuits & retrieve results)
– Backend → AI Model (local inference or separate microservice)
– Backend ↔ MongoDB Atlas (read/write user data or simulation history)
– Static assets served from CDN/public
c. Architectural Patterns & Principles
– Separation of Concerns: UI vs. API vs. Quantum compute
– Serverless functions (Next.js app/api) for low-latency endpoints
– Dedicated long-running backend for compute-intensive tasks
– Environment-driven configuration for stage-wise deployment
d. Key Technologies & Frameworks
– Next.js 13 (app router, React 18)
– TypeScript end-to-end
– Framer Motion for animations
– Node/Express-style backend
– IBMQ REST APIs
– AI model (TensorFlow/PyTorch?) embedded in backend
– MongoDB Atlas

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client Browser"]:::frontend

    %% Frontend Layer
    subgraph "Frontend (Next.js 13 App Router)"
        direction TB
        RootPage["Root Landing Page"]:::frontend
        POverview["Project-Overview Page"]:::frontend
        Curated["Curated-List Page"]:::frontend
        Details["Details Page"]:::frontend
        SimulationPage["Simulation Page"]:::frontend
        Layout["Global Layout Component"]:::frontend
        Styles["Global Styles (globals.css)"]:::frontend
    end

    %% Serverless API Layer
    subgraph "Serverless API Routes"
        direction TB
        PredictAPI["/api/predict Route"]:::api
        SimulateAPI["/api/simulate Route"]:::api
    end

    %% Backend Layer
    subgraph "Backend Service (Node/Express)"
        direction TB
        BackendServer["Backend Entry Point (main.ts)"]:::backend
        EnvVars["Env Vars:\nNEXT_PUBLIC_API_URL\nMONGODB_ATLAS_URI\nIBMQ_API_TOKEN"]:::note
    end

    %% External Services
    subgraph "External Services"
        direction TB
        IBMQ[(IBM Quantum Cloud Service)]:::external
        AIModel["AI Prediction Model"]:::external
        Mongo[(MongoDB Atlas)]:::external
        CDN["Static Asset Store (public/, assets/)"]:::external
    end

    %% Connections
    Client -->|"renders"| RootPage
    Client -->|"navigates to"| POverview
    Client -->|"navigates to"| Curated
    Client -->|"navigates to"| Details
    Client -->|"navigates to"| SimulationPage
    RootPage -->|uses| Layout
    POverview -->|uses| Layout
    Curated -->|uses| Layout
    Details -->|uses| Layout
    SimulationPage -->|uses| Layout
    Layout -->|imports| Styles

    SimulationPage -->|"fetch"| PredictAPI
    SimulationPage -->|"fetch"| SimulateAPI

    PredictAPI -->|POST to| BackendServer
    SimulateAPI -->|POST to| BackendServer
    BackendServer -->|calls| IBMQ
    BackendServer -->|runs inference| AIModel
    BackendServer -->|reads/writes| Mongo
    Client -->|loads assets from| CDN

    BackendServer -->|reads config| EnvVars

    %% Click Events
    click RootPage "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/page.tsx"
    click POverview "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/Project-Overview/page.tsx"
    click Curated "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/curated-list/page.tsx"
    click Details "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/details/page.tsx"
    click SimulationPage "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/simulation/page.tsx"
    click Layout "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/layout.tsx"
    click Styles "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/globals.css"
    click PredictAPI "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/api/predict/route.ts"
    click SimulateAPI "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/app/api/simulate/route.ts"
    click BackendServer "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/backend/main.ts"
    click CDN "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/tree/main/public/"
    click CDN "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/assets/winning-team-video.mov"
    click nextConfig "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/next.config.ts"
    click tsConfig "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/tsconfig.json"
    click pkgJSON "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/package.json"
    click pkgLock "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/package-lock.json"
    click eslintConfig "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/eslint.config.mjs"
    click postcssConfig "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/postcss.config.mjs"
    click LICENSE "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/tree/main/LICENSE"
    click README "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/README.md"
    click gitignore "https://github.com/mr-rahul-paul/quantum-sim-hackiiitv/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#21618C,color:#1B2631
    classDef api fill:#A9DFBF,stroke:#196F3D,color:#1B2631
    classDef backend fill:#F5B041,stroke:#B9770E,color:#1B2631
    classDef external fill:#D5D8DC,stroke:#566573,color:#1B2631
    classDef note fill:#F9E79F,stroke:#B7950B,color:#1B2631
```
