# yfermi/dr-yo-plasmax architecture

> Architecture diagram of the GitHub repository yfermi/dr-yo-plasmax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yfermi/dr-yo-plasmax
- Repository: https://github.com/yfermi/dr-yo-plasmax

## Overview

1. **Overall shape**
   - This repository is a monorepo-style plasma diagnostics project, but the **feature-complete application lives in `Plasma-X-V1.0-main/plasmax/`**.
   - The rest of the repo contains **supporting server/proxy code, dataset generation scripts, harvested NIST data, and verification tooling**.

2. **Primary runtime**
   - The main app is a **TypeScript + React + Vite** browser application.
   - Its entry points are `plasmax/src/main.tsx` and `plasmax/src/App.tsx`, with a parallel root-level app shell also present in `src/`, likely for a simpler or earlier build variant.

3. **UI composition**
   - The UI is organized into feature components rather than route-heavy pages.
   - Major user-facing areas include:
     - spectrum upload and analysis,
     - spectrum visualization,
     - periodic table / element browsing,
     - 3D atom viewer,
     - plasma diagnostic calculators,
     - project/session management,
     - AI assistant and help content.
   - Layout is supported by reusable shells such as `Sidebar` and `Dashboard`.

4. **Spectral analysis pipeline**
   - User spectra enter through upload/import components and are processed by analysis-oriented modules.
   - The flow typically goes from **file ingestion → peak detection / parsing → line matching → diagnostic interpretation**.
   - Core analysis components include Boltzmann, Stark, continuum, permittivity, thermodynamics, and molecule synthesis tools.

5. **Physics and solver boundary**
   - The app separates UI from numerical logic via `services/`, `utils/`, and analysis-specific hooks/solvers.
   - Examples include:
     - `spectralSolver` for spectral computation/matching,
     - `useBoltzmannSolver` for excitation temperature workflows,
     - `StarkSolver` for electron density estimation,
     - molecular and continuum radiation utilities.
   - This boundary is important: most calculation logic is kept out of the UI components.

6. **NIST data access strategy**
   - A major architectural feature is the **hybrid local/remote NIST line database**.
   - The app can use prepackaged local data from `plasmax/public/nist/` and `plasmax/src/data/`, while also supporting remote or proxied access through:
     - `api/nist-proxy.ts`
     - `api/nist-direct-proxy.ts`
     - `nist-proxy-worker.js`
     - services such as `nistApi`, `nistLocal`, and `NISTLocalService`.
   - This creates an offline-friendly path with fallback/proxy-based retrieval when needed.

7. **Data model and domain catalogs**
   - Domain data is precomputed and stored as JSON/TS assets rather than fetched from a database at runtime.
   - Key datasets include:
     - NIST elemental line catalogs,
     - spectral databases,
     - molecular constants and molecular indices,
     - Stark and transition databases,
     - advisor/element metadata tables.
   - The app is therefore largely a **client-side data-driven scientific tool** rather than a traditional CRUD backend.

8. **Diagnostic workflow and planning**
   - Beyond raw analysis, the app generates **measurement plans / diagnostic protocols**.
   - This logic uses detected species and spectral matches to guide the user toward the right analysis tools, forming a workflow from **observation → identification → recommended diagnostics**.
   - Components like `AnalysisPipeline`, `AnalyticFramework`, `PlasmaAdvisor`, and `ReportGenerator` suggest a workflow orchestration layer above the low-level calculators.

9. **3D visualization subsystem**
   - The 3D atomic viewer is a dedicated subsystem with its own components and geometry helpers.
   - It presents atomic structure, transitions, and orbital concepts using interactive visual models.
   - Supporting components include 3D setup/geometry modules plus element, Grotrian, and atom viewer interfaces.

10. **State and session boundaries**
   - App-wide state is organized through React context and service layers.
   - Notable context/state boundaries include:
     - project/session state,
     - sound/audio state,
     - persistent settings and saved projects.
   - The app supports **project save/load as JSON** and browser-session persistence, so user work is treated as a portable project artifact.

11. **AI and external service integration**
   - There is an optional **Gemini-based assistant** exposed through `geminiService`.
   - This appears to be an adjunct feature for scientific guidance and interpretation, not a core dependency of the analysis pipeline.

12. **Build, deployment, and hosting**
   - The frontend is configured for Vite-based builds and Vercel deployment (`vercel.json` appears in the app trees).
   - The root also contains a **Node/TypeScript tooling layer** for harvesting, parsing, rebuilding, and validating NIST datasets, plus small scripts for proxies and server behavior.
   - In architecture terms, this repo has a **client-heavy scientific app** backed by **static datasets and lightweight proxy endpoints**, with an offline-preferred design.

Main entry points: [`Plasma-X-V1.0-main/plasmax/src/components/Dashboard.tsx`](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/Dashboard.tsx) (Dashboard), [`Plasma-X-V1.0-main/plasmax/src/App.tsx`](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/App.tsx) (PlasmaX app), [`Plasma-X-V1.0-main/components/AnalysisPipeline.tsx`](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/components/AnalysisPipeline.tsx) (Analysis pipeline), [`Plasma-X-V1.0-main/plasmax/src/services`](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services) (Services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Client App"]
  node_root_main(("Root entry<br/>entrypoint<br/>[main.tsx]"))
  node_root_app["Root shell<br/>app shell<br/>[App.tsx]"]
  node_plasmax_main(("PlasmaX entry<br/>entrypoint<br/>[main.tsx]"))
  node_plasmax_app["PlasmaX app<br/>app shell<br/>[App.tsx]"]
  node_dashboard["Dashboard<br/>ui shell<br/>[Dashboard.tsx]"]
  node_sidebar["Sidebar<br/>nav layout<br/>[Sidebar.tsx]"]
  node_upload["Spectrum import<br/>ingest ui<br/>[SpectrumImport.tsx]"]
  node_visualizer["Spectrum view<br/>visualization ui"]
  node_periodic["Periodic table<br/>catalog ui<br/>[PeriodicTable.tsx]"]
  node_atom3d{{"Atom viewer<br/>3d ui<br/>[AtomViewer3D.tsx]"}}
  node_analysis_pipe["Analysis pipeline<br/>workflow"]
  node_analysis_tools["Analysis engines<br/>physics tools<br/>[components]"]
  node_advisor["Advisor<br/>recommendation<br/>[PlasmaAdvisor.tsx]"]
  node_project[("Project state<br/>session state<br/>[ProjectContext.tsx]")]
  node_sound[("Sound state<br/>ui state<br/>[SoundContext.tsx]")]
end

subgraph group_data["Data & Access"]
  node_services["Services<br/>[services]"]
  node_solver{{"Spectral solver<br/>matching engine<br/>[spectralSolver.ts]"}}
  node_nist_local[("Local NIST<br/>offline data service<br/>[nistLocal.ts]")]
  node_nist_api[("NIST API<br/>remote proxy client<br/>[nistApi.ts]")]
  node_data_assets[("Catalog assets<br/>scientific datasets<br/>[data]")]
  node_nist_pack[("NIST pack<br/>offline catalog<br/>[nist]")]
  node_api_proxy["Proxy endpoints<br/>serverless api<br/>[api]"]
  node_worker(("Proxy worker<br/>edge worker"))
end

subgraph group_tooling["Tooling"]
  node_tooling_scripts["Harvest tools<br/>dataset tooling"]
  node_build_root["Root tooling<br/>node tooling"]
end

node_root_main -->|"boots"| node_root_app
node_plasmax_main -->|"boots"| node_plasmax_app
node_plasmax_app -->|"composes"| node_dashboard
node_plasmax_app -->|"navigates"| node_sidebar
node_dashboard -->|"ingests"| node_upload
node_dashboard -->|"shows"| node_visualizer
node_dashboard -->|"browses"| node_periodic
node_dashboard -->|"renders"| node_atom3d
node_dashboard -->|"orchestrates"| node_analysis_pipe
node_analysis_pipe -->|"invokes"| node_analysis_tools
node_analysis_pipe -->|"recommends"| node_advisor
node_analysis_pipe -->|"queries"| node_services
node_project -->|"persists"| node_plasmax_app
node_sound -->|"feeds"| node_plasmax_app
node_services -->|"computes"| node_solver
node_services -->|"reads"| node_nist_local
node_services -->|"falls back"| node_nist_api
node_nist_local -->|"loads"| node_nist_pack
node_nist_local -->|"indexes"| node_data_assets
node_nist_api -->|"routes"| node_api_proxy
node_api_proxy -->|"delegates"| node_worker
node_data_assets -->|"mirrors"| node_nist_pack
node_tooling_scripts -->|"builds"| node_data_assets
node_tooling_scripts -->|"updates"| node_nist_pack
node_build_root -.->|"drives"| node_tooling_scripts
node_build_root -.->|"supports"| node_api_proxy
node_root_app -.->|"adjacent"| node_build_root

click node_root_main "https://github.com/yfermi/dr-yo-plasmax/blob/main/src/main.tsx"
click node_root_app "https://github.com/yfermi/dr-yo-plasmax/blob/main/src/App.tsx"
click node_plasmax_main "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/main.tsx"
click node_plasmax_app "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/App.tsx"
click node_dashboard "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/Dashboard.tsx"
click node_sidebar "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/components/layout/Sidebar.tsx"
click node_upload "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/SpectrumImport.tsx"
click node_visualizer "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/SpectrumVisualizer.tsx"
click node_periodic "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/PeriodicTable.tsx"
click node_atom3d "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/AtomViewer3D.tsx"
click node_analysis_pipe "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/components/AnalysisPipeline.tsx"
click node_analysis_tools "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components"
click node_advisor "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/PlasmaAdvisor.tsx"
click node_project "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/context/ProjectContext.tsx"
click node_sound "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/contexts/SoundContext.tsx"
click node_services "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services"
click node_solver "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services/spectralSolver.ts"
click node_nist_local "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services/nistLocal.ts"
click node_nist_api "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services/nistApi.ts"
click node_data_assets "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/data"
click node_nist_pack "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/public/nist"
click node_api_proxy "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/api"
click node_worker "https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/nist-proxy-worker.js"
click node_tooling_scripts "https://github.com/yfermi/dr-yo-plasmax/tree/main/scripts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_main,node_root_app,node_plasmax_main,node_plasmax_app,node_dashboard,node_sidebar,node_upload,node_visualizer,node_periodic,node_atom3d,node_analysis_pipe,node_analysis_tools,node_advisor,node_project,node_sound toneBlue
class node_services,node_solver,node_nist_local,node_nist_api,node_data_assets,node_nist_pack,node_api_proxy,node_worker toneAmber
class node_tooling_scripts,node_build_root toneMint
```

## Components

### Client App

Primary browser application and its UI subsystems

- [Root entry](https://github.com/yfermi/dr-yo-plasmax/blob/main/src/main.tsx): entrypoint · Top-level React entry used by the root build variant · `src/main.tsx`
- [Root shell](https://github.com/yfermi/dr-yo-plasmax/blob/main/src/App.tsx): app shell · Simpler root app container for the alternate frontend variant · `src/App.tsx`
- [PlasmaX entry](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/main.tsx): entrypoint · Main feature-complete app bootstrap · `Plasma-X-V1.0-main/plasmax/src/main.tsx`
- [PlasmaX app](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/App.tsx): app shell · Primary application composition and top-level navigation · `Plasma-X-V1.0-main/plasmax/src/App.tsx`
- [Dashboard](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/Dashboard.tsx): ui shell · Main workspace layout and orchestration surface · `Plasma-X-V1.0-main/plasmax/src/components/Dashboard.tsx`
- [Sidebar](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/components/layout/Sidebar.tsx): nav layout · Reusable navigation and section switching shell · `Plasma-X-V1.0-main/components/layout/Sidebar.tsx`
- [Spectrum import](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/SpectrumImport.tsx): ingest ui · File import and spectrum ingestion entry point · `Plasma-X-V1.0-main/plasmax/src/components/SpectrumImport.tsx`
- [Spectrum view](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/SpectrumVisualizer.tsx): visualization ui · Spectrum charting and exploration surface · `Plasma-X-V1.0-main/plasmax/src/components/SpectrumVisualizer.tsx`
- [Periodic table](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/PeriodicTable.tsx): catalog ui · Element browsing and selection workspace · `Plasma-X-V1.0-main/plasmax/src/components/PeriodicTable.tsx`
- [Atom viewer](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/AtomViewer3D.tsx): 3d ui · Interactive atomic structure and transition viewer · `Plasma-X-V1.0-main/plasmax/src/components/AtomViewer3D.tsx`
- [Analysis pipeline](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/components/AnalysisPipeline.tsx): workflow · Coordinates identification, fitting, and diagnostic workflows · `Plasma-X-V1.0-main/components/AnalysisPipeline.tsx`
- [Analysis engines](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components): physics tools · Boltzmann, Stark, continuum, permittivity, thermodynamics, and molecular analysis components · `Plasma-X-V1.0-main/plasmax/src/components`
- [Advisor](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/components/PlasmaAdvisor.tsx): recommendation · Guidance layer that proposes diagnostic paths and reports · `Plasma-X-V1.0-main/plasmax/src/components/PlasmaAdvisor.tsx`
- [Project state](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/context/ProjectContext.tsx): session state · Saved project/session persistence and user workspace state · `Plasma-X-V1.0-main/plasmax/src/context/ProjectContext.tsx`
- [Sound state](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/contexts/SoundContext.tsx): ui state · Application-wide audio/sound context · `Plasma-X-V1.0-main/plasmax/src/contexts/SoundContext.tsx`

### Data & Access

Local scientific datasets plus NIST retrieval/proxy boundary

- [Services](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services): domain services · Client-side service boundary for solvers, data access, and AI helpers · `Plasma-X-V1.0-main/plasmax/src/services`
- [Spectral solver](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services/spectralSolver.ts): matching engine · Spectrum computation, matching, and interpretation logic · `Plasma-X-V1.0-main/plasmax/src/services/spectralSolver.ts`
- [Local NIST](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services/nistLocal.ts): offline data service · Offline-first access to packaged NIST line data · `Plasma-X-V1.0-main/plasmax/src/services/nistLocal.ts`
- [NIST API](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/services/nistApi.ts): remote proxy client · Remote or proxied NIST retrieval interface · `Plasma-X-V1.0-main/plasmax/src/services/nistApi.ts`
- [Catalog assets](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/src/data): scientific datasets · Precomputed spectral, Stark, molecular, and advisor datasets · `Plasma-X-V1.0-main/plasmax/src/data`
- [NIST pack](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/plasmax/public/nist): offline catalog · Packaged NIST JSON catalogs shipped with the app · `Plasma-X-V1.0-main/plasmax/public/nist`
- [Proxy endpoints](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/api): serverless api · NIST proxy and direct-proxy endpoints for fallback access · `Plasma-X-V1.0-main/api`
- [Proxy worker](https://github.com/yfermi/dr-yo-plasmax/blob/main/Plasma-X-V1.0-main/nist-proxy-worker.js): edge worker · Worker-based NIST proxy mediation · `Plasma-X-V1.0-main/nist-proxy-worker.js`

### Tooling

Build, harvest, verify, and server-side support scripts

- [Harvest tools](https://github.com/yfermi/dr-yo-plasmax/tree/main/scripts): dataset tooling · Scripts for harvest, parse, verify, and rebuild workflows · `scripts`
- **Root tooling**: node tooling · Monorepo-level build, ingest, and verification scripts

## Connections

- Root entry → Root shell: boots · Root variant initializes the root application shell
- PlasmaX entry → PlasmaX app: boots · Main Vite entry mounts the feature-complete app
- PlasmaX app → Dashboard: composes · Top-level app renders the central dashboard
- PlasmaX app → Sidebar: navigates · App shell uses the shared sidebar for section switching
- Dashboard → Spectrum import: ingests · Dashboard exposes spectrum import flows
- Dashboard → Spectrum view: shows · Dashboard presents spectrum visualization
- Dashboard → Periodic table: browses · Dashboard includes element and catalog browsing
- Dashboard → Atom viewer: renders · Dashboard launches the 3D atom viewer
- Dashboard → Analysis pipeline: orchestrates · Dashboard routes work into the analysis pipeline
- Analysis pipeline → Analysis engines: invokes · Workflow delegates to the physics calculators and engines
- Analysis pipeline → Advisor: recommends · Pipeline feeds diagnostic recommendations and reports
- Analysis pipeline → Services: queries · Workflow depends on shared services for computation and retrieval
- Project state → PlasmaX app: persists · Project/session state is consumed by the main app
- Sound state → PlasmaX app: feeds · Audio and UI effects are managed at app scope
- Services → Spectral solver: computes · Service layer wraps spectral matching and interpretation
- Services → Local NIST: reads · Services prefer packaged local NIST access when possible
- Services → NIST API: falls back · Services can reach remote/proxied NIST retrieval
- Local NIST → NIST pack: loads · Local service reads shipped NIST datasets
- Local NIST → Catalog assets: indexes · Local access joins app datasets with NIST catalogs
- NIST API → Proxy endpoints: routes · Remote access is mediated through proxy endpoints
- Proxy endpoints → Proxy worker: delegates · Proxy endpoints are supported by the worker bridge
- Catalog assets → NIST pack: mirrors · Data assets and NIST pack form the offline scientific catalog layer
- Harvest tools → Catalog assets: builds · Scripts harvest and rebuild the dataset bundles
- Harvest tools → NIST pack: updates · Scripts refresh packaged NIST content
- Root tooling → Harvest tools: drives · Root-level scripts coordinate harvesting and validation workflows
- Root tooling → Proxy endpoints: supports · Root tooling also exercises the proxy and server-adjacent flows
- Root shell → Root tooling: adjacent · Root variant sits near the Node tooling and dataset pipeline
