musica-javascript refactor

[K20shores]

Texas A&M students are rewriting music box interactive to use our new music-box javascript package. This will allow us to remove the server component entirely which should lead to a more stable user experience and reduce hosting costs.

Below is a listing of all features in the current python-based model so that the students can track what may or may not need to be done.

You can preview both versions

• python
• javascript (the refactor)

Features

Mechanism Management

• Load pre-built example mechanisms (CHAPMAN, FLOW_TUBE, FULL_GAS_PHASE, TS1)
• Gas-phase species editing (add, remove, configure properties)
• Reaction management (add, remove, configure)
• Rate constant and temperature dependency configuration
• Reactant and product stoichiometry configuration
• Species property lists and shared property management
• Aerosol mechanism configuration (feature-flagged: PART_MC — disabled in production)
• Aerosol representation settings
• Surface reaction initial conditions support

---

Simulation Conditions Setup

• Set species initial concentrations in many units
• Configure initial environmental parameters (pressure, temperature, rate params)
• Upload evolving conditions from CSV
• Download evolving conditions CSV templates
• Add/remove time steps for evolving conditions in the app

---

Simulation Execution

• Submit simulation jobs via RabbitMQ message queue
• Distributed model execution (6 worker replicas)
• Session-based run tracking (WAITING → RUNNING → DONE/ERROR)
• Error capture and reporting

---

PartMC Aerosol Modeling (optional, feature-flagged)

• Particle number and mass concentration tracking (25 time points)
• PartMC output archival
• PartMC results download as ZIP
• Feature flag: disabled in production, enabled in development

---

Results & Visualization

• Interactive line plots (D3.js)
• Multi-variable plot selection and filtering
• Flow diagram
• Integrated reaction rate plots
• CSV results download
• ZIP download

---

Configuration Management

• Save configurations as compressed ZIP archives
• Load configurations from ZIP files
• Configuration JSON serialization

---

User Interface — Pages

• Home (about, sponsors, developers, contact)
• Getting Started (quick start guide, example loader)
• Mechanism (gas species + reaction editing)
• Mechanism — Aerosol tab (only when PART_MC enabled)
• Conditions (initial + evolving conditions)
• Results
• Plots
• Downloads (config and results export)
• Flow Diagram (feature-flagged)

Backend REST API

• GET /api/load-example — load a built-in example config
• POST /api/run — submit a simulation job
• GET /api/run-status — poll run status
• GET /api/load-results — fetch completed results
• POST /api/compress-config — download config as ZIP
• POST /api/extract-config — upload and extract a ZIP config
• GET /api/download-results — download results as CSV or ZIP
• GET /manage/health — server health check
• GET /manage/swagger — OpenAPI/Swagger docs
• Prometheus metrics (/metrics via django-prometheus)

---

Infrastructure & Deployment

Docker

• Multi-stage Dockerfile (Fedora base with scientific stack: cmake, fortran, netcdf, lapack)
• Conditional PyPartMC installation via build arg (INSTALL_PyPartMC)
• api-server service
• model-runner service (RabbitMQ consumer, 6 replicas)
• rabbitmq service
• frontend service
• Persistent volumes: SQLite DB, PartMC data, RabbitMQ data

Kubernetes

• Kustomize-based configuration management
• Devel and production overlays
• Automated image tag updates via CI/CD
• Deploy branch strategy (bypasses branch protection for CI commits)

---

CI/CD (GitHub Actions)

• pytest.yml — Django integration tests on push/PR (Docker Compose-based)
• build_deploy.yml — build and push container images, update kustomization tags
• auto_format.yml — automated code formatting
• close_stale_issues.yml — stale issue maintenance
• test.yml — frontend linting (appears legacy/deprecated)

---

Testing

• Backend integration tests via Django REST Framework APIClient
• Example round-trip tests (Chapman, FlowTube, FullGasPhase)
• API response structure validation
• Frontend model tests (models.test.jsx)
• Frontend transformer tests (transformers.test.jsx)

---

Feature Flags

Flag	Dev	Prod	Status
FLOW_DIAGRAM	true	true	Enabled
PART_MC	true	false	Optional dependency, disabled in prod

[K20shores]

MusicBox Interactive — JavaScript Refactor Status

Tracking the transition from the Python-based application to a pure JavaScript frontend using the @ncar/music-box package. The Python server, RabbitMQ, and Django REST API have been removed entirely.

---

Known Incomplete Items

• CI/CD — pipelines exist but are not running correctly (path mismatches in test.yml and build_deploy.yml)
• Plot performance — lags when displaying too many species at once; implement a maximum species count or more efficient rendering
• Species search UX — search works but can be difficult to find some species; consider improvements
• Example data consistency — conditions for examples are inconsistently sourced (some from @ncar/music-box package, some from CSV files); prefer all conditions stored uniformly in JSON or files, not mixed
• Evolving conditions UI — currently only shows temperature and pressure fields; needs update to expose evolving species concentrations and other evolving parameters
• Start from scratch — functionality exists in code but needs UI polish
• Initial concentrations — needs a dropdown/autocomplete to select from species already in the mechanism instead of free-text entry
• Run Simulation guard — consider disabling the button until all required parameters are set, with clear feedback indicating what is missing
• Add feedback if running the simulation doesn’t work due to missing data
• Load configuration is currently a disabled feature. This feature appears to work with uploading a configuration json such as the example json files. CSV data would need to be uploaded and input separately. Change this to be a zip file for faster loading speeds.
• Fix reaction rates plots and check environment plots
• Add options to edit Species and Reactions in the mechanism tab after they’ve been added. Currently, you need to delete and add it again completely from scratch.
• Flux species naming can be fixed to be more organized and less conflicting. It’s currently named after the reactions name (i.e. A -> B, species name = A___B)
• Recommend earlier error feedback in some cases when adding reactions with non-existent species used.
• Some dropdowns show as white text on a white background
• Raw numerical input in conditions tabs don’t allow numbers to be completely deleted. Inconvenient for entering numbers.
• Want a signal that the simulation is running and for the user to wait.
• Error caused when user enters too large of numbers (User entered large number for total runtime of simulation). Suggest adding a reasonable range.

---

Mechanism Management

• Load pre-built example mechanisms (Chapman, TS1, Flow-Tube, CB-5, Analytical)
• Gas-phase species editing (add, remove, configure properties)
  • (Jiwon) The handleAddSpecies function SpeciesEditor.jsx:64-111 is commented-out, and the same logic is seen in speciesUtils.js. Was this logic refactored? If so, should we clean up the dead code?
• Reaction management (add, remove, configure) — 11+ reaction types supported
• Rate constant and temperature dependency configuration
• Reactant and product stoichiometry configuration
• Species property lists and shared property management
  • (Jiwon) What does shared property management mean? properties: {} is initialized as an empty object in speciesUtils.js:61 but it doesn't seem to be populated anywhere.
• Aerosol mechanism configuration (PART_MC) — not applicable; PartMC is a Python dependency removed in the JS refactor
• Aerosol representation settings — not applicable
• Surface reaction initial conditions support — not applicable

---

Simulation Conditions Setup

• Set species initial concentrations with unit selection — concentrations work but no dropdown to select mechanism species; see incomplete items above
• Configure initial environmental parameters (pressure, temperature, rate params)
• Upload evolving conditions from CSV
• Download evolving conditions CSV templates
• Add/remove time steps for evolving conditions in the app

---

Simulation Execution

• Submit simulation jobs via RabbitMQ — not applicable; replaced by local WASM/native solver
• Distributed model execution (6 worker replicas) — not applicable
• Run status tracking (running → done / error)
• Error capture and reporting (toast notifications, Redux error state)

---

Results & Visualization

• Interactive line plots (Recharts)
• Multi-variable plot selection and filtering — functional but laggy at scale; see incomplete items above
• Flow diagram
• Integrated reaction rate plots
• CSV results download
• ZIP download of results — not implemented

---

Configuration Management

• Save/load configurations as ZIP archives — currently saves/loads as JSON only; ZIP not implemented
• Configuration JSON serialization and export
• Copy configuration to clipboard

---

User Interface — Pages

• Home (about, sponsors, developers, contact)
• Getting Started / Dashboard (example loader, start from scratch)
• Mechanism (gas species + reaction editing)
• Mechanism — Aerosol tab (PART_MC) — not applicable
• Conditions (initial + evolving conditions, 4-tab layout)
• Plots (species, reaction rates, environment, flow diagram)
• Downloads (config export)
• Flow Diagram
• Config file upload — UI button exists but is hardcoded as disabled

---

CI/CD (GitHub Actions)

• build_deploy.yml — builds and pushes frontend image, updates Kustomize tags; broken (incorrect directory path references)
• test.yml — runs frontend Jest/Vitest tests; broken (hardcoded ./frontend working directory doesn't match repo structure)
• auto_format.yml — runs Prettier on JS, autopep8 on Python
• close_stale_issues.yml — stale issue maintenance
• pytest.yml — not applicable; no Python backend

---

Testing

• Frontend integration tests — 5 round-trip tests for RunSimulationButton across example mechanisms (Analytical, Chapman, TS1, Flow-Tube, CB-5)
• Backend integration tests (Django APIClient) — not applicable
• API response structure validation — not applicable

---

Infrastructure & Deployment

• Dockerfile (single-stage frontend build + Nginx)
• Kubernetes/Kustomize configuration (devel and production overlays)
• Nginx config for SPA routing
• RabbitMQ, api-server, model-runner services — not applicable; no backend
• Persistent volumes (SQLite, PartMC, RabbitMQ) — not applicable

---

Feature Flags

Flag	Dev	Prod	Status
FLOW_DIAGRAM	true	true	Enabled everywhere
PART_MC	—	—	Removed; not applicable to JS refactor