# runningbrute/starforge architecture

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

- Interactive diagram: https://gitdiagram.com/runningbrute/starforge
- Repository: https://github.com/runningbrute/starforge

## Overview

StarForge is a modular C particle-simulation engine. Its main workflow is to create an engine and particle systems, emit particles, update them under world forces using a selected storage/update backend, then expose particles to a frontend for rendering. Major documented branches include continuous rain and fire/smoke emitters, burst emitters, ASCII and Raylib frontends, and AoS, SoA, and optional AVX2 backends. The graph follows sampled engine and system dispatch; some capability links are documented in the README, while unsampled demo wiring is not inferred.

Main entry points: [`src/starforge_particlesystem.c`](https://github.com/runningbrute/starforge/blob/main/src/starforge_particlesystem.c) (Particle system), [`src/starforge_engine.c`](https://github.com/runningbrute/starforge/blob/main/src/starforge_engine.c) (Engine), [`include/starforge_frontend.h`](https://github.com/runningbrute/starforge/blob/main/include/starforge_frontend.h) (Frontend interface), [`src/starforge_backend_soa_cpu.c`](https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_soa_cpu.c) (SoA CPU backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Engine orchestration"]
  node_engine["Engine<br/>[starforge_engine.c]"]
  node_world["World forces<br/>[starforge_world.c]"]
  node_system["Particle system"]
end

subgraph group_simulation["Particle simulation"]
  node_particle["Particle model"]
  node_emitters["Emitter variants"]
  node_backend_api["Backend interface"]
  node_backend_aos["AoS backend"]
  node_backend_soa["SoA CPU backend"]
  node_backend_avx["SoA AVX2 backend"]
end

subgraph group_storage["Particle storage"]
  node_pool[("AoS / SoA pools")]
  node_accessor["Pool accessor"]
end

subgraph group_presentation["Frontends"]
  node_frontend_api["Frontend interface"]
  node_ascii["ASCII frontend"]
  node_raylib["Raylib frontend"]
end

node_user(("Demo user"))

node_user -->|"runs demos"| node_engine
node_engine -->|"initializes"| node_world
node_engine -->|"creates systems"| node_system
node_engine -->|"updates systems"| node_system
node_engine -->|"dispatches render"| node_frontend_api
node_system -->|"dispatches emission"| node_emitters
node_system -->|"updates backend"| node_backend_api
node_system -->|"creates pool"| node_pool
node_system -->|"selects backend"| node_backend_aos
node_system -->|"selects backend"| node_backend_soa
node_system -->|"selects backend"| node_backend_avx
node_backend_aos -->|"uses pool API"| node_pool
node_backend_soa -->|"uses pool API"| node_pool
node_backend_avx -->|"uses CPU backend API"| node_backend_soa
node_system -->|"passes forces"| node_world
node_system -->|"exposes particles"| node_particle
node_backend_api -->|"defines access"| node_accessor
node_frontend_api -->|"implemented by"| node_ascii
node_frontend_api -->|"implemented by"| node_raylib
node_ascii -->|"reads particles"| node_engine
node_raylib -->|"reads particles"| node_engine

click node_engine "https://github.com/runningbrute/starforge/blob/main/src/starforge_engine.c"
click node_world "https://github.com/runningbrute/starforge/blob/main/src/starforge_world.c"
click node_system "https://github.com/runningbrute/starforge/blob/main/src/starforge_particlesystem.c"
click node_particle "https://github.com/runningbrute/starforge/blob/main/include/starforge_particle.h"
click node_emitters "https://github.com/runningbrute/starforge/tree/main/src"
click node_backend_api "https://github.com/runningbrute/starforge/blob/main/include/starforge_backend.h"
click node_backend_aos "https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_aos.c"
click node_backend_soa "https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_soa_cpu.c"
click node_backend_avx "https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_soa_avx2.c"
click node_pool "https://github.com/runningbrute/starforge/tree/main/src"
click node_accessor "https://github.com/runningbrute/starforge/blob/main/include/starforge_particle_pool_accessor.h"
click node_frontend_api "https://github.com/runningbrute/starforge/blob/main/include/starforge_frontend.h"
click node_ascii "https://github.com/runningbrute/starforge/blob/main/src/starforge_frontend_ascii.c"
click node_raylib "https://github.com/runningbrute/starforge/blob/main/src/starforge_frontend_raylib.c"

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_engine,node_world,node_system,node_user toneBlue
class node_particle,node_emitters,node_backend_api,node_backend_aos,node_backend_soa,node_backend_avx toneAmber
class node_pool,node_accessor toneMint
class node_frontend_api,node_ascii,node_raylib toneRose
```

## Components

### Engine orchestration

- [Engine](https://github.com/runningbrute/starforge/blob/main/src/starforge_engine.c): `src/starforge_engine.c`
- [World forces](https://github.com/runningbrute/starforge/blob/main/src/starforge_world.c): `src/starforge_world.c`
- [Particle system](https://github.com/runningbrute/starforge/blob/main/src/starforge_particlesystem.c): `src/starforge_particlesystem.c`

### Particle simulation

- [Particle model](https://github.com/runningbrute/starforge/blob/main/include/starforge_particle.h): `include/starforge_particle.h`
- [Emitter variants](https://github.com/runningbrute/starforge/tree/main/src): `src`
- [Backend interface](https://github.com/runningbrute/starforge/blob/main/include/starforge_backend.h): `include/starforge_backend.h`
- [AoS backend](https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_aos.c): `src/starforge_backend_aos.c`
- [SoA CPU backend](https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_soa_cpu.c): `src/starforge_backend_soa_cpu.c`
- [SoA AVX2 backend](https://github.com/runningbrute/starforge/blob/main/src/starforge_backend_soa_avx2.c): `src/starforge_backend_soa_avx2.c`

### Particle storage

- [AoS / SoA pools](https://github.com/runningbrute/starforge/tree/main/src): `src`
- [Pool accessor](https://github.com/runningbrute/starforge/blob/main/include/starforge_particle_pool_accessor.h): `include/starforge_particle_pool_accessor.h`

### Frontends

- [Frontend interface](https://github.com/runningbrute/starforge/blob/main/include/starforge_frontend.h): `include/starforge_frontend.h`
- [ASCII frontend](https://github.com/runningbrute/starforge/blob/main/src/starforge_frontend_ascii.c): `src/starforge_frontend_ascii.c`
- [Raylib frontend](https://github.com/runningbrute/starforge/blob/main/src/starforge_frontend_raylib.c): `src/starforge_frontend_raylib.c`

### Other components

- **Demo user**

## Connections

- Demo user → Engine: runs demos (evidence: `README.md`)
- Engine → World forces: initializes (evidence: `src/starforge_engine.c`)
- Engine → Particle system: creates systems (evidence: `src/starforge_engine.c`)
- Engine → Particle system: updates systems (evidence: `src/starforge_engine.c`)
- Engine → Frontend interface: dispatches render (evidence: `src/starforge_engine.c`)
- Particle system → Emitter variants: dispatches emission (evidence: `src/starforge_particlesystem.c`)
- Particle system → Backend interface: updates backend (evidence: `src/starforge_particlesystem.c`)
- Particle system → AoS / SoA pools: creates pool (evidence: `src/starforge_particlesystem.c`)
- Particle system → AoS backend: selects backend (evidence: `src/starforge_particlesystem.c`)
- Particle system → SoA CPU backend: selects backend (evidence: `src/starforge_particlesystem.c`)
- Particle system → SoA AVX2 backend: selects backend (evidence: `src/starforge_particlesystem.c`)
- AoS backend → AoS / SoA pools: uses pool API (evidence: `src/starforge_backend_aos.c`)
- SoA CPU backend → AoS / SoA pools: uses pool API (evidence: `src/starforge_backend_soa_cpu.c`)
- SoA AVX2 backend → SoA CPU backend: uses CPU backend API (evidence: `src/starforge_backend_soa_avx2.c`)
- Particle system → World forces: passes forces (evidence: `src/starforge_particlesystem.c`)
- Particle system → Particle model: exposes particles
- Backend interface → Pool accessor: defines access (evidence: `include/starforge_backend.h`)
- Frontend interface → ASCII frontend: implemented by
- Frontend interface → Raylib frontend: implemented by
- ASCII frontend → Engine: reads particles (evidence: `src/starforge_frontend_ascii.c`)
- Raylib frontend → Engine: reads particles (evidence: `src/starforge_frontend_raylib.c`)