# bruhat15/qvidya architecture

> Architecture diagram of the GitHub repository bruhat15/qvidya, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bruhat15/qvidya
- Repository: https://github.com/bruhat15/qvidya

## Overview

##### Project type & purpose (from README + tree)
This repo is an **educational/experimental collection of Jupyter notebooks** for “quirky qubits” / quantum computing demos. The only substantive artifacts are notebooks under `algorithms/src/`:

- `Deutsch-Jozsa.ipynb`
- `Grovers.ipynb`
- `helloworld*.ipynb`

##### Actors / entrypoints
- **User (learner/developer)**: opens and runs notebooks
- **Jupyter UI**: notebook browser/editor
- **Python Kernel**: executes cells

##### Code/artifact layer (repo)
- Deutsch–Jozsa notebook
- Grover’s notebook
- Hello-world notebooks
- (Optional) “Data/Notes” artifacts (`a.txt`, outputs)

##### Execution targets
- **Local quantum simulator** (often provided by the SDK)
- **Remote quantum backend** (optional): IBMQ / cloud provider / hardware QPU
- Only include if notebooks actually configure credentials/backends; otherwise show as “optional external”.

##### Outputs
- **Results**: measurement counts, statevectors, plots
- **Saved notebook outputs**: `.ipynb` with stored cell outputs

##### Quantum SDK → Execution Backend
- to **Local Simulator** (default)
- optionally to **Remote QPU/Cloud API**
##### Notebook persists outputs back to `.ipynb` (artifact update)

- **Control** (run cells)
- **Data** (circuits, measurement results)
- **External API calls** (remote backend)

##### Important patterns/design principles visible here
Given the repository’s structure, the “pattern” is:
- **Notebook-as-application**: each notebook encapsulates algorithm + execution + visualization.
- **Algorithm-per-notebook modularity**: loose coupling; shared code is not extracted into a library (yet).
- **Interactive compute workflow**: iterative exploration rather than packaged software.

##### Context / C4 Level 1-2 (System + Containers)
- Shows: User, Jupyter, Python kernel, notebooks, Quantum SDK, simulator, optional remote backend.

- “Run Grover’s notebook” sequence:
- Same template applies to Deutsch–Jozsa.

This pair captures both **static architecture** (components) and **dynamic behavior** (execution flow), which is the most accurate representation for a notebook-first repo.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Context / C4 L1-2 Diagram
    %% =========================
    subgraph "Context / Containers (Notebook-centric quantum demos)"
        direction TB

        User["User (Learner/Developer)"]:::actor

        subgraph "Interactive Runtime"
            direction TB
            Jupyter["Jupyter UI (Notebook editor/browser)"]:::runtime
            Kernel["Python Kernel (executes cells)"]:::runtime
        end

        subgraph "Repository Artifacts (this repo)"
            direction TB
            Readme["README.md (project intent)"]:::doc

            subgraph "Quantum Algorithms Module Boundary"
                direction TB
                AlgorithmsDir["algorithms/"]:::repo

                subgraph "Notebooks Source of Truth"
                    direction TB
                    SrcDir["algorithms/src/"]:::repo

                    DJ["Deutsch–Jozsa notebook\n(circuit construction + run + measure)"]:::notebook
                    Grover["Grover's notebook\n(oracle + diffusion + iterations + execution)"]:::notebook

                    subgraph "HelloWorld Notebooks"
                        direction TB
                        HW1["helloworld.ipynb (intro/demo)"]:::notebook
                        HW2["helloworld2.ipynb (variant/demo)"]:::notebook
                    end

                    Scratch["a.txt (scratch/notes; non-core)"]:::artifact
                end
            end
        end

        subgraph "Dependency Layer (Runtime Libraries)"
            direction TB
            QuantumSDK["Quantum SDK (e.g., Qiskit/Cirq)\n(inferred; not declared)"]:::sdk
            PyDeps["Common Python libs\n(numpy/matplotlib/etc.) (optional)"]:::sdk
        end

        subgraph "Execution Targets"
            direction TB
            Simulator[("Local Quantum Simulator\n(often via SDK)")]:::backend
            RemoteQPU[("Remote QPU / Cloud Backend\n(IBMQ/etc.) (optional external)")]:::backendExternal
        end

        subgraph "Outputs"
            direction TB
            Results["Results in notebook\n(measurement counts/statevectors)"]:::output
            Plots["Visualizations / Plots"]:::output
            SavedNB["Saved notebook with cell outputs\n(.ipynb updated)"]:::output
        end

        %% ---- Main control/data flows (vertical) ----
        User -->|"open/run_notebooks"| Jupyter
        Jupyter -->|"execute_cells"| Kernel
        Kernel -->|"run_notebook_code"| DJ
        Kernel -->|"run_notebook_code"| Grover
        Kernel -->|"run_notebook_code"| HW1
        Kernel -->|"run_notebook_code"| HW2

        DJ -->|"Python_API_calls"| QuantumSDK
        Grover -->|"Python_API_calls"| QuantumSDK
        HW1 -->|"Python_API_calls"| QuantumSDK
        HW2 -->|"Python_API_calls"| QuantumSDK

        DJ -->|"use_py_libs"| PyDeps
        Grover -->|"use_py_libs"| PyDeps
        HW1 -->|"use_py_libs"| PyDeps
        HW2 -->|"use_py_libs"| PyDeps

        QuantumSDK -->|"execute_on_default"| Simulator
        QuantumSDK -.->|"HTTPS_API+auth_if_configured"| RemoteQPU

        Simulator -->|"measurement_results"| QuantumSDK
        RemoteQPU -.->|"measurement_results"| QuantumSDK

        QuantumSDK -->|"return_results"| DJ
        QuantumSDK -->|"return_results"| Grover
        QuantumSDK -->|"return_results"| HW1
        QuantumSDK -->|"return_results"| HW2

        DJ -->|"render_results"| Results
        Grover -->|"render_results"| Results
        HW1 -->|"render_results"| Results
        HW2 -->|"render_results"| Results

        Results -->|"visualize"| Plots
        Plots -->|"display"| Jupyter
        Jupyter -->|"view"| User

        DJ -->|"persist_cell_outputs"| SavedNB
        Grover -->|"persist_cell_outputs"| SavedNB
        HW1 -->|"persist_cell_outputs"| SavedNB
        HW2 -->|"persist_cell_outputs"| SavedNB

        %% Notes / patterns
        Note1["Pattern: Notebook-as-application\nEach notebook is an independent mini-program;\nno shared module/library layer in repo (yet)."]:::note
        SrcDir -.->|"organizational_boundary"| Note1
    end

    %% =========================
    %% Algorithm Execution Flow
    %% =========================
    subgraph "Algorithm Execution Flow (example: run Grover's notebook)"
        direction TB

        AUser["User"]:::actor
        AJupyter["Jupyter UI"]:::runtime
        AKernel["Python Kernel"]:::runtime
        ANB["Grover's notebook (.ipynb)"]:::notebook

        Build["Build circuit\n(registers, oracle, diffusion, iterations)"]:::step
        Transpile["Transpile/compile circuit\n(SDK-provided)"]:::step
        Execute["Execute job\n(simulate or run)"]:::step
        Measure["Measure / sample results\n(counts/statevector)"]:::step
        Visualize["Visualize results\n(histograms/plots)"]:::step
        Persist["Persist outputs back into\nnotebook file (.ipynb)"]:::step

        ASDK["Quantum SDK (inferred)"]:::sdk
        ABackend[("Simulator backend (local)")]:::backend
        ARemote[("Remote QPU (optional)")]:::backendExternal
        AOut["Displayed outputs in Jupyter"]:::output

        AUser -->|"run_all_cells"| AJupyter
        AJupyter -->|"cell_exec_requests"| AKernel
        AKernel -->|"execute_cells"| ANB
        ANB -->|"step_1"| Build
        Build -->|"Python_API_calls"| ASDK
        ASDK -->|"step_2"| Transpile
        Transpile -->|"step_3"| Execute
        Execute -->|"execute_on"| ABackend
        Execute -.->|"or_execute_on (optional)"| ARemote
        ABackend -->|"results"| ASDK
        ARemote -.->|"results"| ASDK
        ASDK -->|"step_4"| Measure
        Measure -->|"step_5"| Visualize
        Visualize -->|"display"| AOut
        AOut -->|"render_in"| AJupyter
        ANB -->|"step_6"| Persist
        Persist -->|"saved_outputs"| ANB
    end

    %% =========================
    %% Click Events (mapped paths)
    %% =========================
    click Readme "https://github.com/bruhat15/qvidya/blob/main/README.md"
    click AlgorithmsDir "https://github.com/bruhat15/qvidya/tree/main/algorithms/"
    click SrcDir "https://github.com/bruhat15/qvidya/tree/main/algorithms/src/"
    click DJ "https://github.com/bruhat15/qvidya/blob/main/algorithms/src/Deutsch-Jozsa.ipynb"
    click Grover "https://github.com/bruhat15/qvidya/blob/main/algorithms/src/Grovers.ipynb"
    click HW1 "https://github.com/bruhat15/qvidya/blob/main/algorithms/src/helloworld.ipynb"
    click HW2 "https://github.com/bruhat15/qvidya/blob/main/algorithms/src/helloworld2.ipynb"
    click Scratch "https://github.com/bruhat15/qvidya/blob/main/algorithms/src/a.txt"

    %% =========================
    %% Styles
    %% =========================
    classDef actor fill:#111827,stroke:#111827,color:#ffffff,stroke-width:1px
    classDef runtime fill:#d1fae5,stroke:#065f46,color:#064e3b,stroke-width:1px
    classDef repo fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a,stroke-width:1px
    classDef notebook fill:#bfdbfe,stroke:#1d4ed8,color:#1e3a8a,stroke-width:1px
    classDef artifact fill:#e0f2fe,stroke:#0284c7,color:#075985,stroke-width:1px
    classDef sdk fill:#ede9fe,stroke:#6d28d9,color:#4c1d95,stroke-width:1px
    classDef backend fill:#e5e7eb,stroke:#374151,color:#111827,stroke-width:1px
    classDef backendExternal fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-dasharray: 4 3,stroke-width:1px
    classDef output fill:#ffedd5,stroke:#c2410c,color:#7c2d12,stroke-width:1px
    classDef doc fill:#fff7ed,stroke:#c2410c,color:#7c2d12,stroke-width:1px
    classDef note fill:#fef9c3,stroke:#a16207,color:#713f12,stroke-width:1px
    classDef step fill:#ecfccb,stroke:#3f6212,color:#1a2e05,stroke-width:1px
```
