# komochristian/felsim architecture

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

- Interactive diagram: https://gitdiagram.com/komochristian/felsim
- Repository: https://github.com/komochristian/felsim

## Overview

FELsim is a web application for configuring and analyzing free-electron-laser beamlines. The user-facing workflow centers on editing a beamline and particle/beam settings, then viewing beam-parameter plots and simulation results. The backend includes beamline physics, lattice import, optimization, and several simulation-code integrations. Source excerpts establish selected module dependencies, but the API-to-UI request path and several unsampled capabilities are not verified; those subsystems are included without guessed call chains.

Main entry points: [`fel-app/src/App.jsx`](https://github.com/komochristian/felsim/blob/main/fel-app/src/App.jsx) (Application UI), [`backend/cosySimulator.py`](https://github.com/komochristian/felsim/blob/main/backend/cosySimulator.py) (COSY simulator), [`backend/AlgebraicOptimization.py`](https://github.com/komochristian/felsim/blob/main/backend/AlgebraicOptimization.py) (Algebraic optimization), [`backend/rftrackAdapter.py`](https://github.com/komochristian/felsim/blob/main/backend/rftrackAdapter.py) (RF-Track adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_app["Application UI<br/>[App.jsx]"]
  node_beamline_ui["Beamline editor<br/>[App.jsx]"]
  node_beam_settings["Beam settings<br/>[BeamSettings.jsx]"]
  node_particle_settings["Particle settings"]
  node_graph_ui["Plots and navigation<br/>[LineGraph.jsx]"]
  node_parameter_modal["Parameter analysis<br/>[ModalContent.jsx]"]
  node_beam_visual["Beamline view<br/>[ScrollableBeam.jsx]"]
end

subgraph group_api["Backend entry"]
  node_api["FEL API<br/>[felAPI.py]"]
end

subgraph group_physics["Beam physics"]
  node_beamline["Beamline elements<br/>[beamline.py]"]
  node_beam_evolution["Beam evolution<br/>[beamEvolution.py]"]
  node_ebeam["Electron beam<br/>[ebeam.py]"]
  node_constants["Physical constants"]
  node_algebraic_opt["Algebraic optimization"]
  node_beam_optimizer["Beam optimizer<br/>[beamOptimizer.py]"]
  node_schematic["Beamline schematic<br/>[schematic.py]"]
end

subgraph group_simulation["Simulation"]
  node_sim_base["Simulator interface<br/>[simulatorBase.py]"]
  node_sim_factory["Simulator selection"]
  node_multi_sim["Multi-code simulation"]
  node_cosy_sim["COSY simulator<br/>[cosySimulator.py]"]
  node_cosy_reader["COSY results"]
  node_cosy_particles["COSY particle simulator"]
  node_rftrack["RF-Track adapter<br/>[rftrackAdapter.py]"]
  node_xsuite["Xsuite adapter<br/>[xsuiteAdapter.py]"]
  node_felsim_adapter["FELsim adapter<br/>[felsimAdapter.py]"]
end

subgraph group_inputs["Lattice inputs"]
  node_lattice_load["Lattice loading"]
  node_lattice_builder["Beamline builder<br/>[beamlineBuilder.py]"]
  node_excel_import["Excel lattice import<br/>[excelToJson.py]"]
  node_yaml_import["YAML lattice import"]
  node_json_import["JSON lattice import"]
end

node_user(("FELsim user"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_beamline_ui
node_app -->|"renders"| node_beam_settings
node_app -->|"renders"| node_particle_settings
node_app -->|"renders"| node_graph_ui
node_app -->|"renders"| node_parameter_modal
node_app -.->|"exchanges data"| node_api
node_parameter_modal -->|"renders"| node_beam_visual
node_api -.->|"dispatches"| node_beamline
node_api -.->|"selects"| node_sim_factory
node_algebraic_opt -->|"uses"| node_beamline
node_algebraic_opt -->|"uses"| node_schematic
node_algebraic_opt -->|"uses"| node_ebeam
node_beamline -->|"uses"| node_constants
node_cosy_sim -->|"uses"| node_lattice_builder
node_cosy_sim -->|"reads results"| node_cosy_reader
node_cosy_sim -->|"uses"| node_constants
node_cosy_particles -->|"uses"| node_cosy_sim
node_cosy_particles -->|"uses"| node_constants
node_rftrack -->|"implements"| node_sim_base
node_rftrack -->|"uses"| node_beam_evolution
node_rftrack -->|"uses"| node_lattice_load

click node_app "https://github.com/komochristian/felsim/blob/main/fel-app/src/App.jsx"
click node_beamline_ui "https://github.com/komochristian/felsim/blob/main/fel-app/src/App.jsx"
click node_beam_settings "https://github.com/komochristian/felsim/blob/main/fel-app/src/components/BeamSettings/BeamSettings.jsx"
click node_particle_settings "https://github.com/komochristian/felsim/blob/main/fel-app/src/components/ParticleSettings/ParticleSettings.jsx"
click node_graph_ui "https://github.com/komochristian/felsim/blob/main/fel-app/src/components/LineGraph/LineGraph.jsx"
click node_parameter_modal "https://github.com/komochristian/felsim/blob/main/fel-app/src/components/ModalContent/ModalContent.jsx"
click node_beam_visual "https://github.com/komochristian/felsim/blob/main/fel-app/src/components/ScrollableBeam/ScrollableBeam.jsx"
click node_api "https://github.com/komochristian/felsim/blob/main/backend/felAPI.py"
click node_beamline "https://github.com/komochristian/felsim/blob/main/backend/beamline.py"
click node_beam_evolution "https://github.com/komochristian/felsim/blob/main/backend/beamEvolution.py"
click node_ebeam "https://github.com/komochristian/felsim/blob/main/backend/ebeam.py"
click node_constants "https://github.com/komochristian/felsim/blob/main/backend/physicalConstants.py"
click node_algebraic_opt "https://github.com/komochristian/felsim/blob/main/backend/AlgebraicOptimization.py"
click node_beam_optimizer "https://github.com/komochristian/felsim/blob/main/backend/beamOptimizer.py"
click node_schematic "https://github.com/komochristian/felsim/blob/main/backend/schematic.py"
click node_sim_base "https://github.com/komochristian/felsim/blob/main/backend/simulatorBase.py"
click node_sim_factory "https://github.com/komochristian/felsim/blob/main/backend/simulatorFactory.py"
click node_multi_sim "https://github.com/komochristian/felsim/blob/main/backend/multiCodeSimulator.py"
click node_cosy_sim "https://github.com/komochristian/felsim/blob/main/backend/cosySimulator.py"
click node_cosy_reader "https://github.com/komochristian/felsim/blob/main/backend/cosyResultsReader.py"
click node_cosy_particles "https://github.com/komochristian/felsim/blob/main/backend/cosyParticleSimulator.py"
click node_rftrack "https://github.com/komochristian/felsim/blob/main/backend/rftrackAdapter.py"
click node_xsuite "https://github.com/komochristian/felsim/blob/main/backend/xsuiteAdapter.py"
click node_felsim_adapter "https://github.com/komochristian/felsim/blob/main/backend/felsimAdapter.py"
click node_lattice_load "https://github.com/komochristian/felsim/blob/main/backend/latticeLoaderBase.py"
click node_lattice_builder "https://github.com/komochristian/felsim/blob/main/backend/beamlineBuilder.py"
click node_excel_import "https://github.com/komochristian/felsim/blob/main/backend/excelToJson.py"
click node_yaml_import "https://github.com/komochristian/felsim/blob/main/backend/yamlLatticeLoader.py"
click node_json_import "https://github.com/komochristian/felsim/blob/main/backend/jsonLatticeLoader.py"

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_app,node_beamline_ui,node_beam_settings,node_particle_settings,node_graph_ui,node_parameter_modal,node_beam_visual,node_user toneBlue
class node_api toneAmber
class node_beamline,node_beam_evolution,node_ebeam,node_constants,node_algebraic_opt,node_beam_optimizer,node_schematic toneMint
class node_sim_base,node_sim_factory,node_multi_sim,node_cosy_sim,node_cosy_reader,node_cosy_particles,node_rftrack,node_xsuite,node_felsim_adapter toneRose
class node_lattice_load,node_lattice_builder,node_excel_import,node_yaml_import,node_json_import toneIndigo
```

## Components

### Web interface

- [Application UI](https://github.com/komochristian/felsim/blob/main/fel-app/src/App.jsx): `fel-app/src/App.jsx`
- [Beamline editor](https://github.com/komochristian/felsim/blob/main/fel-app/src/App.jsx): `fel-app/src/App.jsx`
- [Beam settings](https://github.com/komochristian/felsim/blob/main/fel-app/src/components/BeamSettings/BeamSettings.jsx): `fel-app/src/components/BeamSettings/BeamSettings.jsx`
- [Particle settings](https://github.com/komochristian/felsim/blob/main/fel-app/src/components/ParticleSettings/ParticleSettings.jsx): `fel-app/src/components/ParticleSettings/ParticleSettings.jsx`
- [Plots and navigation](https://github.com/komochristian/felsim/blob/main/fel-app/src/components/LineGraph/LineGraph.jsx): `fel-app/src/components/LineGraph/LineGraph.jsx`
- [Parameter analysis](https://github.com/komochristian/felsim/blob/main/fel-app/src/components/ModalContent/ModalContent.jsx): `fel-app/src/components/ModalContent/ModalContent.jsx`
- [Beamline view](https://github.com/komochristian/felsim/blob/main/fel-app/src/components/ScrollableBeam/ScrollableBeam.jsx): `fel-app/src/components/ScrollableBeam/ScrollableBeam.jsx`

### Backend entry

- [FEL API](https://github.com/komochristian/felsim/blob/main/backend/felAPI.py): `backend/felAPI.py`

### Beam physics

- [Beamline elements](https://github.com/komochristian/felsim/blob/main/backend/beamline.py): `backend/beamline.py`
- [Beam evolution](https://github.com/komochristian/felsim/blob/main/backend/beamEvolution.py): `backend/beamEvolution.py`
- [Electron beam](https://github.com/komochristian/felsim/blob/main/backend/ebeam.py): `backend/ebeam.py`
- [Physical constants](https://github.com/komochristian/felsim/blob/main/backend/physicalConstants.py): `backend/physicalConstants.py`
- [Algebraic optimization](https://github.com/komochristian/felsim/blob/main/backend/AlgebraicOptimization.py): `backend/AlgebraicOptimization.py`
- [Beam optimizer](https://github.com/komochristian/felsim/blob/main/backend/beamOptimizer.py): `backend/beamOptimizer.py`
- [Beamline schematic](https://github.com/komochristian/felsim/blob/main/backend/schematic.py): `backend/schematic.py`

### Simulation

- [Simulator interface](https://github.com/komochristian/felsim/blob/main/backend/simulatorBase.py): `backend/simulatorBase.py`
- [Simulator selection](https://github.com/komochristian/felsim/blob/main/backend/simulatorFactory.py): `backend/simulatorFactory.py`
- [Multi-code simulation](https://github.com/komochristian/felsim/blob/main/backend/multiCodeSimulator.py): `backend/multiCodeSimulator.py`
- [COSY simulator](https://github.com/komochristian/felsim/blob/main/backend/cosySimulator.py): `backend/cosySimulator.py`
- [COSY results](https://github.com/komochristian/felsim/blob/main/backend/cosyResultsReader.py): `backend/cosyResultsReader.py`
- [COSY particle simulator](https://github.com/komochristian/felsim/blob/main/backend/cosyParticleSimulator.py): `backend/cosyParticleSimulator.py`
- [RF-Track adapter](https://github.com/komochristian/felsim/blob/main/backend/rftrackAdapter.py): `backend/rftrackAdapter.py`
- [Xsuite adapter](https://github.com/komochristian/felsim/blob/main/backend/xsuiteAdapter.py): `backend/xsuiteAdapter.py`
- [FELsim adapter](https://github.com/komochristian/felsim/blob/main/backend/felsimAdapter.py): `backend/felsimAdapter.py`

### Lattice inputs

- [Lattice loading](https://github.com/komochristian/felsim/blob/main/backend/latticeLoaderBase.py): `backend/latticeLoaderBase.py`
- [Beamline builder](https://github.com/komochristian/felsim/blob/main/backend/beamlineBuilder.py): `backend/beamlineBuilder.py`
- [Excel lattice import](https://github.com/komochristian/felsim/blob/main/backend/excelToJson.py): `backend/excelToJson.py`
- [YAML lattice import](https://github.com/komochristian/felsim/blob/main/backend/yamlLatticeLoader.py): `backend/yamlLatticeLoader.py`
- [JSON lattice import](https://github.com/komochristian/felsim/blob/main/backend/jsonLatticeLoader.py): `backend/jsonLatticeLoader.py`

### Other components

- **FELsim user**

## Connections

- FELsim user → Application UI: uses
- Application UI → Beamline editor: renders (evidence: `fel-app/src/App.jsx`)
- Application UI → Beam settings: renders (evidence: `fel-app/src/App.jsx`)
- Application UI → Particle settings: renders (evidence: `fel-app/src/App.jsx`)
- Application UI → Plots and navigation: renders (evidence: `fel-app/src/App.jsx`)
- Application UI → Parameter analysis: renders (evidence: `fel-app/src/App.jsx`)
- Application UI → FEL API: exchanges data
- Parameter analysis → Beamline view: renders (evidence: `fel-app/src/components/ModalContent/ModalContent.jsx`)
- FEL API → Beamline elements: dispatches
- FEL API → Simulator selection: selects
- Algebraic optimization → Beamline elements: uses (evidence: `backend/AlgebraicOptimization.py`)
- Algebraic optimization → Beamline schematic: uses (evidence: `backend/AlgebraicOptimization.py`)
- Algebraic optimization → Electron beam: uses (evidence: `backend/AlgebraicOptimization.py`)
- Beamline elements → Physical constants: uses (evidence: `backend/beamline.py`)
- COSY simulator → Beamline builder: uses (evidence: `backend/cosySimulator.py`)
- COSY simulator → COSY results: reads results (evidence: `backend/cosySimulator.py`)
- COSY simulator → Physical constants: uses (evidence: `backend/cosySimulator.py`)
- COSY particle simulator → COSY simulator: uses (evidence: `backend/cosyParticleSimulator.py`)
- COSY particle simulator → Physical constants: uses (evidence: `backend/cosyParticleSimulator.py`)
- RF-Track adapter → Simulator interface: implements (evidence: `backend/rftrackAdapter.py`)
- RF-Track adapter → Beam evolution: uses (evidence: `backend/rftrackAdapter.py`)
- RF-Track adapter → Lattice loading: uses (evidence: `backend/rftrackAdapter.py`)
