Nuke Sim - Nuclear Reaction Simulator

An interactive web application to explore nuclear reactions, including fusion, fission, and decay processes.

Features

• 🔬 15 scientifically accurate nuclear reactions (fusion, fission, decay)
• � Animated 3D nuclear reactions with particle collision sequences
• �🎮 Interactive 3D visualization with Three.js
• 📊 Three view modes: 2D diagram, 3D interactive, Animated 3D
• ⚡ Fast reaction switching (<1 second)
• 💥 Physics-based animations using React Spring
• ♿ Accessible keyboard navigation
• 📱 Responsive design (desktop, tablet & mobile)
• 🔌 Offline-capable with embedded default reaction
• 🎓 Educational explanations and energy data
• 🎨 Color-coded particle identification with trail effects
• 🖱️ Interactive 3D controls (rotate, zoom, pan)
• 🔄 Replay animations on demand

Quick Start

Using Docker (Recommended)

# Start both services
bash infrastructure/scripts/dev.sh

# Or use docker compose directly
docker compose -f infrastructure/docker/docker-compose.yml up --build

Then open:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000/docs

Local Development

Backend:

cd backend
pip install -r requirements.txt
uvicorn src.api.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

Testing

Backend tests:

cd backend
pytest

Frontend tests:

cd frontend
npm test                  # Unit tests
npm run test:e2e         # Playwright integration tests

Architecture

• Backend: Python 3.11 + FastAPI
• Frontend: Next.js 14 + React + TypeScript + Three.js
• 3D Graphics: React Three Fiber + Three.js
• Animations: React Spring (physics-based)
• Infrastructure: Docker + Docker Compose

See specs/001-website-to-simulate/ for detailed architecture documentation.
See docs/enhancement-3d-visualization.md for 3D features and expanded reactions.
See docs/animated-3d-reactions.md for animation system details.

Reaction Categories

Fusion (5 reactions)

• Proton-Proton Fusion (stellar)
• Deuterium-Tritium Fusion (terrestrial)
• Helium-3 Deuterium Fusion (aneutronic)
• CNO Cycle First Step (massive stars)
• Lithium-6 Deuterium Fusion
• Boron-11 Proton Fusion (clean fusion)

Fission (3 reactions)

• U-235 Thermal Fission
• Pu-239 Thermal Fission
• Th-232 Neutron Capture

Decay (7 reactions)

• U-238 Alpha Decay
• Neutron Beta Decay
• Tritium Beta Decay
• C-14 Beta Decay (radiocarbon dating)
• Ra-226 Alpha Decay

License

MIT License - see LICENSE file for details.

Data Sources

All reaction data is sourced from IAEA Nuclear Data Services and NIST Physical Reference Data.