# premchandyadav369/quantapath architecture

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

- Interactive diagram: https://gitdiagram.com/premchandyadav369/quantapath
- Repository: https://github.com/premchandyadav369/quantapath

## Overview

##### Project type and purpose
- QuantaPath is a full-stack web application (Next.js + TypeScript + Tailwind CSS) that demonstrates a hybrid quantum-classical approach to solving the Traveling Salesperson Problem (TSP).
- It provides an interactive map UI, calls serverless API routes (OpenRouteService for distances/geocoding and a mock “optimize” API), compares classical and quantum-simulated solvers, and visualizes performance analytics.

##### File structure
- Top-level
- next.config.mjs, tsconfig.json, package.json, README.md
- public/ (static assets)
- styles/ (global CSS)
- .github/workflows (CI/CD)
- app/ (Next.js 13+ App Router)
- layout.tsx, page.tsx, globals.css
- api/ – serverless functions for directions, distance matrix, geocode, optimize
- components/ – React UI subcomponents (maps, controls, visualization, theme provider)
- components/ui/ – shared UI primitives (buttons, inputs, cards, etc.)
- lib/services/ – client-side adapters and solver wrappers
- api-client.ts (OpenRouteService wrapper)
- classical-service.ts (Nearest Neighbor, Simulated Annealing, 2-opt, 3-opt)
- quantum-service.ts (TypeScript simulation of HAWS-QAOA)
- scripts/qaoa_solver.py – standalone Python QAOA implementation using Qiskit (optional for deeper runs)
- No persistent database; “Like” feature likely uses browser storage or external persistence stub.

##### README for architecture insights
- Frontend: Next.js + React + TypeScript + Tailwind
- Serverless API: OpenRouteService integration + mock optimize endpoint
- Core solvers:
– Classical (Nearest Neighbor, Simulated Annealing, 2-opt, 3-opt)
– Quantum (HAWS-QAOA simulation in TS; optional Python/Qiskit script)
- Deployment on Vercel (serverless functions + static hosting)

##### Main components and interactions
a. Frontend (Client)
– Next.js pages/React components
– Map UI: components/google-map.tsx, interactive-map.tsx
– Controls & dashboards: simulation-controls.tsx, benchmark-dashboard.tsx, etc.
b. API Layer (Serverless Functions)
– /api/geocode → lib/services/api-client → OpenRouteService
– /api/distance/matrix → OpenRouteService distance matrix
– /api/directions → turn-by-turn directions via OpenRouteService
– /api/optimize → dispatch to classical-service OR quantum-service
c. Solver Services (Business Logic)
– ClassicalService (heuristic and local search)
– QuantumService (TS mock QAOA)
– Python QAOA script (optional offline heavy compute)
d. External Services
– OpenRouteService APIs
– (Optional) Qiskit if using Python script
e. UI State / Storage
– In-memory React state or browser storage for “liked” routes

##### Architectural patterns and design principles
- Separation of concerns: UI vs. API vs. business logic (“services”)
- Serverless micro–endpoints in Next.js App Router
- Modular React components (atomic design in components/ui)
- Pluggable solver strategy pattern (classical vs. quantum)
- Hybrid compute: client-side TS simulate + optional Python/Qiskit run

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend (Client)"
        direction TB
        MainPage["Main Page"]:::frontend
        Layout["Global Layout"]:::frontend
        AppGlobalsCSS["App Globals CSS"]:::frontend
        StylesGlobalsCSS["Styles Globals CSS"]:::frontend

        subgraph "UI Components"
            direction TB
            subgraph "Map Components"
                direction TB
                GoogleMap["GoogleMap"]:::frontend
                InteractiveMap["InteractiveMap"]:::frontend
                OptimizedRouteMap["GoogleOptimizedRouteMap"]:::frontend
            end
            subgraph "Controls & Dashboards"
                direction TB
                SimulationControls["SimulationControls"]:::frontend
                BenchmarkDashboard["BenchmarkDashboard"]:::frontend
                EfficiencyComparison["EfficiencyComparison"]:::frontend
                CarbonCalculator["CarbonFootprintCalculator"]:::frontend
                NavigationPanel["NavigationPanel"]:::frontend
                ResultsVisualization["ResultsVisualization"]:::frontend
                AdvancedParams["AdvancedParameterControls"]:::frontend
            end
            ThemeProvider["ThemeProvider"]:::frontend
            TodoManager["TodoManager"]:::frontend
        end

        subgraph "Atomic UI Primitives"
            direction TB
            Button["Button"]:::frontend
            Input["Input"]:::frontend
            Select["Select"]:::frontend
            Slider["Slider"]:::frontend
            Switch["Switch"]:::frontend
            AutocompleteInput["AutocompleteInput"]:::frontend
            Card["Card"]:::frontend
            Badge["Badge"]:::frontend
            Label["Label"]:::frontend
            Progress["Progress"]:::frontend
            Separator["Separator"]:::frontend
            Tabs["Tabs"]:::frontend
            Tooltip["Tooltip"]:::frontend
        end
    end

    %% API Layer
    subgraph "Serverless API (Next.js App Router)"
        direction TB
        GeocodeAPI["/api/geocode"]:::api
        DistanceMatrixAPI["/api/distance/matrix"]:::api
        DirectionsAPI["/api/directions"]:::api
        OptimizeAPI["/api/optimize"]:::api
    end

    %% Services Layer
    subgraph "Business Logic Services"
        direction TB
        ApiClient["ApiClient (OpenRouteService)"]:::service
        DistanceService["DistanceService"]:::service
        ClassicalService["ClassicalService"]:::service
        QuantumService["QuantumService"]:::service
    end

    %% Utils & Scripts
    subgraph "Utilities & Config"
        direction TB
        Types["Types"]:::util
        Utils["Utils"]:::util
        QAOAScript["scripts/qaoa_solver.py"]:::util
        ConfigFiles["Config & CI/CD"]:::util
    end

    %% External Dependencies
    subgraph "External Services"
        direction TB
        ORS["OpenRouteService API"]:::external
        Qiskit["Qiskit/Python Runtime"]:::external
    end

    %% Data Flows
    MainPage -->|renders| GoogleMap
    MainPage -->|renders| InteractiveMap
    MainPage -->|renders| OptimizedRouteMap
    MainPage -->|uses| SimulationControls
    MainPage -->|uses| BenchmarkDashboard
    MainPage -->|uses| EfficiencyComparison
    MainPage -->|uses| CarbonCalculator
    MainPage -->|uses| NavigationPanel
    MainPage -->|uses| ResultsVisualization
    MainPage -->|uses| AdvancedParams

    GoogleMap -->|calls| GeocodeAPI
    InteractiveMap -->|calls| DistanceMatrixAPI
    ResultsVisualization -->|calls| DirectionsAPI
    SimulationControls -->|calls| OptimizeAPI

    GeocodeAPI -->|uses| ApiClient
    DirectionsAPI -->|uses| ApiClient
    DistanceMatrixAPI -->|uses| DistanceService
    OptimizeAPI -->|uses| ClassicalService
    OptimizeAPI -->|uses| QuantumService

    ApiClient -->|requests| ORS
    DistanceService -->|requests| ORS
    QuantumService -->|optional call| Qiskit
    QAOAScript -->|direct run| Qiskit

    %% Click Events
    click MainPage "https://github.com/premchandyadav369/quantapath/blob/main/app/page.tsx"
    click Layout "https://github.com/premchandyadav369/quantapath/blob/main/app/layout.tsx"
    click AppGlobalsCSS "https://github.com/premchandyadav369/quantapath/blob/main/app/globals.css"
    click StylesGlobalsCSS "https://github.com/premchandyadav369/quantapath/blob/main/styles/globals.css"

    click GeocodeAPI "https://github.com/premchandyadav369/quantapath/blob/main/app/api/geocode/route.ts"
    click DistanceMatrixAPI "https://github.com/premchandyadav369/quantapath/blob/main/app/api/distance/matrix/route.ts"
    click DirectionsAPI "https://github.com/premchandyadav369/quantapath/blob/main/app/api/directions/route.ts"
    click OptimizeAPI "https://github.com/premchandyadav369/quantapath/blob/main/app/api/optimize/route.ts"

    click GoogleMap "https://github.com/premchandyadav369/quantapath/blob/main/components/google-map.tsx"
    click InteractiveMap "https://github.com/premchandyadav369/quantapath/blob/main/components/interactive-map.tsx"
    click OptimizedRouteMap "https://github.com/premchandyadav369/quantapath/blob/main/components/google-optimized-route-map.tsx"

    click SimulationControls "https://github.com/premchandyadav369/quantapath/blob/main/components/simulation-controls.tsx"
    click BenchmarkDashboard "https://github.com/premchandyadav369/quantapath/blob/main/components/benchmark-dashboard.tsx"
    click EfficiencyComparison "https://github.com/premchandyadav369/quantapath/blob/main/components/efficiency-comparison.tsx"
    click CarbonCalculator "https://github.com/premchandyadav369/quantapath/blob/main/components/carbon-footprint-calculator.tsx"
    click NavigationPanel "https://github.com/premchandyadav369/quantapath/blob/main/components/navigation-panel.tsx"
    click ResultsVisualization "https://github.com/premchandyadav369/quantapath/blob/main/components/results-visualization.tsx"
    click AdvancedParams "https://github.com/premchandyadav369/quantapath/blob/main/components/advanced-parameter-controls.tsx"

    click ThemeProvider "https://github.com/premchandyadav369/quantapath/blob/main/components/theme-provider.tsx"
    click TodoManager "https://github.com/premchandyadav369/quantapath/blob/main/components/todo-manager.tsx"

    click Button "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/button.tsx"
    click Input "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/input.tsx"
    click Select "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/select.tsx"
    click Slider "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/slider.tsx"
    click Switch "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/switch.tsx"
    click AutocompleteInput "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/autocomplete-input.tsx"
    click Card "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/card.tsx"
    click Badge "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/badge.tsx"
    click Label "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/label.tsx"
    click Progress "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/progress.tsx"
    click Separator "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/separator.tsx"
    click Tabs "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/tabs.tsx"
    click Tooltip "https://github.com/premchandyadav369/quantapath/blob/main/components/ui/tooltip.tsx"

    click ApiClient "https://github.com/premchandyadav369/quantapath/blob/main/lib/services/api-client.ts"
    click DistanceService "https://github.com/premchandyadav369/quantapath/blob/main/lib/services/distance-service.ts"
    click ClassicalService "https://github.com/premchandyadav369/quantapath/blob/main/lib/services/classical-service.ts"
    click QuantumService "https://github.com/premchandyadav369/quantapath/blob/main/lib/services/quantum-service.ts"

    click Types "https://github.com/premchandyadav369/quantapath/blob/main/lib/types.ts"
    click Utils "https://github.com/premchandyadav369/quantapath/blob/main/lib/utils.ts"
    click QAOAScript "https://github.com/premchandyadav369/quantapath/blob/main/scripts/qaoa_solver.py"

    click ConfigFiles "https://github.com/premchandyadav369/quantapath/blob/main/next.config.mjs"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#21618C,color:#1B4F72
    classDef api fill:#D5F5E3,stroke:#1D8348,color:#145A32
    classDef service fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef external fill:#FADBD8,stroke:#C0392B,color:#78281F
    classDef util fill:#EAECEE,stroke:#566573,color:#2C3E50
```
