# yaraberkelmans/upgraded-fortnight architecture

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

- Interactive diagram: https://gitdiagram.com/yaraberkelmans/upgraded-fortnight
- Repository: https://github.com/yaraberkelmans/upgraded-fortnight

## Overview

1. **Repository purpose**
   - This is an agent-based simulation project built on **Mesa**. The main domain is football-fan crowd dynamics: segregation on a grid, fight decisions, and police intervention. The repository also contains two smaller standalone models for segregation and civil/riot-like behavior.

2. **Primary architecture: `riot_model/`**
   - `riot_model/riot_model.py` is the orchestration layer. It defines the core `RiotModel` plus the parameter objects `SegregationParams` and `RiotParams`.
   - `riot_model/fan.py` holds the fan agent logic and related enums/strategy definitions.
   - `riot_model/police.py` holds the police agent logic.
   - This package is the canonical implementation used by both the UI and headless runs.

3. **Core simulation boundaries**
   - The model maintains the grid, agent population, phase control, and metrics collection.
   - Fan and police behavior is encapsulated inside agent classes; the model coordinates their interaction, placement, and replacement after arrests.
   - The simulation is split into a **warmup segregation phase** and a **main riot phase**, controlled by the model rather than by external scripts.

4. **Behavioral flow inside the riot model**
   - Fans first evaluate local neighborhood similarity and may move if unhappy.
   - Once the main phase starts, fans also compute perceived win/arrest probabilities and decide whether to fight.
   - Police patrol, move toward fighting fans, and arrest them.
   - Arrested fans are replaced to keep population size stable, so the model preserves density while allowing group counts to drift.

5. **Metrics and observability**
   - `RiotModel` uses a Mesa `DataCollector` to record step-level outputs such as happiness, segregation index, spatial entropy, moves, fighting fans, arrests, police count, and perception averages.
   - These metrics are the primary data product of the model and are what the plotting/visualization layers consume.

6. **Interactive runtime: `server_riot_model.py`**
   - This is the browser-facing entry point, intended to be run with **Solara**.
   - It instantiates the model, exposes parameter sliders, and renders live charts and the grid.
   - Architecturally, it is a thin presentation layer over the core model; it should not contain simulation logic.

7. **Headless/batch runtime**
   - `riot_model/run_aggression_and_plot.py` is the non-UI execution path for running experiments and plotting results.
   - The README’s example shows the intended usage pattern: create a `RiotModel`, call `run_model()`, then read `model.datacollector`.
   - This makes the model reusable for automation, calibration, and analysis without the UI.

8. **Standalone segregation model: `SIMPLE_SEG/`**
   - `SIMPLE_SEG/segregation.py` and `SIMPLE_SEG/run_segregation.py` form a simpler Schelling-style segregation-only simulation.
   - This package is separate from the riot model and likely exists as a pedagogical or baseline subsystem.
   - It is structurally parallel to the larger model: agent logic plus a run script.

9. **Standalone civil model: `SIMPLE_CIVIL/`**
   - `SIMPLE_CIVIL/civil.py` and `SIMPLE_CIVIL/run_civil.py` provide another simplified simulation variant.
   - Like `SIMPLE_SEG`, it appears to be a self-contained experiment rather than part of the main riot model pipeline.

10. **Top-level legacy/shared modules**
   - `fan.py`, `cop.py`, and `mixed_models.py` at the repo root look like earlier or shared implementations outside the packaged `riot_model/` namespace.
   - For architecture diagrams, treat these as auxiliary/legacy code paths unless the application entry points import them directly.

11. **Data and dependency flow**
   - External input is mostly configuration: model parameters, random seed, and UI slider values.
   - The simulation produces stepwise metrics and visualization state; there is no indication of a database, message bus, or network service backend.
   - The main runtime dependency is Mesa, with Solara used only for the interactive dashboard.

12. **Suggested diagram focus**
   - Show three layers: **entry points** (`server_riot_model.py`, `run_*` scripts), **model core** (`riot_model/`), and **supporting simulations** (`SIMPLE_SEG`, `SIMPLE_CIVIL`, legacy root modules).
   - Emphasize the one-way flow from UI/script → model parameters → step loop → datacollector/visualization outputs.

Main entry points: [`riot_model/riot_model.py`](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py) (Riot model), [`server_riot_model.py`](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_riot_model.py) (Riot server), [`riot_model/run_aggression_and_plot.py`](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/run_aggression_and_plot.py) (Batch run), [`mixed_models.py`](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/mixed_models.py) (Mixed models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_server_riot_model_py["Riot server<br/>solara ui"]
  node_server_seg_py["Seg server<br/>ui entry<br/>[server_seg.py]"]
  node_server_civ_py["Civil server<br/>ui entry<br/>[server_civ.py]"]
end

subgraph group_core["Riot model"]
  node_run_aggression_and_plot_py["Batch run<br/>experiment script"]
  node_riot_model_py["Riot model<br/>mesa model<br/>[riot_model.py]"]
  node_riot_fan_py(("Fan agent<br/>agent logic<br/>[fan.py]"))
  node_riot_police_py(("Police agent<br/>agent logic<br/>[police.py]"))
  node_seg_params["Seg params<br/>config object<br/>[riot_model.py]"]
  node_riot_params["Riot params<br/>config object<br/>[riot_model.py]"]
  node_datacollector[("Metrics<br/>mesa collector<br/>[riot_model.py]")]
end

subgraph group_support["Supporting sims"]
  node_simple_seg_py["Segregation model<br/>schelling sim<br/>[segregation.py]"]
  node_run_segregation_py["Seg run<br/>script<br/>[run_segregation.py]"]
  node_simple_civil_py["Civil model<br/>crowd sim<br/>[civil.py]"]
  node_run_civil_py["Civil run<br/>script<br/>[run_civil.py]"]
  node_fan_legacy_py(("Legacy fan<br/>shared legacy<br/>[fan.py]"))
  node_cop_py(("Legacy cop<br/>shared legacy<br/>[cop.py]"))
  node_mixed_models_py["Mixed models<br/>legacy variants<br/>[mixed_models.py]"]
end

node_server_riot_model_py -->|"instantiates"| node_riot_model_py
node_run_aggression_and_plot_py -->|"runs"| node_riot_model_py
node_riot_model_py -->|"uses"| node_seg_params
node_riot_model_py -->|"uses"| node_riot_params
node_riot_model_py -->|"coordinates"| node_riot_fan_py
node_riot_model_py -->|"coordinates"| node_riot_police_py
node_riot_model_py -->|"records"| node_datacollector
node_riot_fan_py -.->|"acts in"| node_riot_model_py
node_riot_police_py -.->|"acts in"| node_riot_model_py
node_server_riot_model_py -->|"visualizes"| node_datacollector
node_run_aggression_and_plot_py -->|"plots"| node_datacollector
node_server_seg_py -->|"instantiates"| node_simple_seg_py
node_run_segregation_py -->|"runs"| node_simple_seg_py
node_server_civ_py -->|"instantiates"| node_simple_civil_py
node_run_civil_py -->|"runs"| node_simple_civil_py
node_mixed_models_py -.->|"references"| node_fan_legacy_py
node_mixed_models_py -.->|"references"| node_cop_py
node_riot_model_py -.->|"parallel code"| node_fan_legacy_py
node_riot_model_py -.->|"parallel code"| node_cop_py

click node_server_riot_model_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_riot_model.py"
click node_run_aggression_and_plot_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/run_aggression_and_plot.py"
click node_server_seg_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_seg.py"
click node_server_civ_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_civ.py"
click node_riot_model_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py"
click node_riot_fan_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/fan.py"
click node_riot_police_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/police.py"
click node_seg_params "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py"
click node_riot_params "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py"
click node_datacollector "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py"
click node_simple_seg_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_SEG/segregation.py"
click node_run_segregation_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_SEG/run_segregation.py"
click node_simple_civil_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_CIVIL/civil.py"
click node_run_civil_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_CIVIL/run_civil.py"
click node_fan_legacy_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/fan.py"
click node_cop_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/cop.py"
click node_mixed_models_py "https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/mixed_models.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_server_riot_model_py,node_server_seg_py,node_server_civ_py toneBlue
class node_run_aggression_and_plot_py,node_riot_model_py,node_riot_fan_py,node_riot_police_py,node_seg_params,node_riot_params,node_datacollector toneAmber
class node_simple_seg_py,node_run_segregation_py,node_simple_civil_py,node_run_civil_py,node_fan_legacy_py,node_cop_py,node_mixed_models_py toneMint
```

## Components

### Entry points

UI and batch scripts that start simulations and experiments.

- [Riot server](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_riot_model.py): solara ui · Browser-facing dashboard and parameter controls for the main model. · `server_riot_model.py`
- [Seg server](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_seg.py): ui entry · Entry point for the standalone segregation simulation UI. · `server_seg.py`
- [Civil server](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/server_civ.py): ui entry · Entry point for the standalone civil simulation UI. · `server_civ.py`

### Riot model

Canonical Mesa-based crowd simulation used by both UI and headless runs.

- [Batch run](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/run_aggression_and_plot.py): experiment script · Headless execution path for running the riot model and plotting results. · `riot_model/run_aggression_and_plot.py`
- [Riot model](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py): mesa model · Orchestrates the main crowd simulation, phases, movement, fights, arrests, and metrics. · `riot_model/riot_model.py`
- [Fan agent](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/fan.py): agent logic · Fan behavior, neighborhood evaluation, movement, and fight decisions. · `riot_model/fan.py`
- [Police agent](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/police.py): agent logic · Police movement, patrol, pursuit, and arrest behavior. · `riot_model/police.py`
- [Seg params](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py): config object · Parameters for the warmup segregation phase and related tuning. · `riot_model/riot_model.py`
- [Riot params](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py): config object · Parameters controlling the main riot phase, policing, and perceptions. · `riot_model/riot_model.py`
- [Metrics](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/riot_model/riot_model.py): mesa collector · Step-level outputs such as happiness, segregation, entropy, moves, arrests, and perceptions. · `riot_model/riot_model.py`

### Supporting sims

Smaller standalone models and legacy shared modules.

- [Segregation model](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_SEG/segregation.py): schelling sim · Standalone segregation-only simulation core. · `SIMPLE_SEG/segregation.py`
- [Seg run](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_SEG/run_segregation.py): script · Execution script for the standalone segregation model. · `SIMPLE_SEG/run_segregation.py`
- [Civil model](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_CIVIL/civil.py): crowd sim · Standalone simplified civil or riot-like simulation core. · `SIMPLE_CIVIL/civil.py`
- [Civil run](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/SIMPLE_CIVIL/run_civil.py): script · Execution script for the standalone civil simulation. · `SIMPLE_CIVIL/run_civil.py`
- [Legacy fan](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/fan.py): shared legacy · Top-level fan implementation outside the packaged riot model namespace. · `fan.py`
- [Legacy cop](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/cop.py): shared legacy · Top-level police/cop implementation outside the packaged riot model namespace. · `cop.py`
- [Mixed models](https://github.com/yaraberkelmans/upgraded-fortnight/blob/main/mixed_models.py): legacy variants · Older or auxiliary model combinations and experiments. · `mixed_models.py`

## Connections

- Riot server → Riot model: instantiates · Interactive runtime constructs and drives the canonical model.
- Batch run → Riot model: runs · Batch script executes the same model headlessly.
- Riot model → Seg params: uses · Model configuration for the segregation warmup phase.
- Riot model → Riot params: uses · Model configuration for the riot phase and policing behavior.
- Riot model → Fan agent: coordinates · Model creates, places, updates, and replaces fan agents.
- Riot model → Police agent: coordinates · Model manages police agents and their interaction with fans.
- Riot model → Metrics: records · Simulation state is summarized into step-level metrics.
- Fan agent → Riot model: acts in · Fan decisions are evaluated within the model grid and phase loop.
- Police agent → Riot model: acts in · Police behavior is executed under model control.
- Riot server → Metrics: visualizes · UI reads collected metrics for charts and live displays.
- Batch run → Metrics: plots · Headless workflow consumes collected outputs for analysis.
- Seg server → Segregation model: instantiates · Standalone segregation UI wraps its model core.
- Seg run → Segregation model: runs · Batch path for the segregation-only simulation.
- Civil server → Civil model: instantiates · Standalone civil UI wraps its model core.
- Civil run → Civil model: runs · Batch path for the civil simulation.
- Mixed models → Legacy fan: references · Legacy model compositions reuse the older fan implementation.
- Mixed models → Legacy cop: references · Legacy model compositions reuse the older cop implementation.
- Riot model → Legacy fan: parallel code · Top-level legacy modules appear to be auxiliary rather than canonical.
- Riot model → Legacy cop: parallel code · Top-level legacy modules appear to be auxiliary rather than canonical.