# chinanagooo/kallangflow architecture

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

- Interactive diagram: https://gitdiagram.com/chinanagooo/kallangflow
- Repository: https://github.com/chinanagooo/kallangflow

## Overview

KallangFlow combines an in-memory synthetic event crowd simulator, personalised journey recommendations, and a browser map/control interface; it also includes a scripted crowd-scale demo and shared attendee-profile persistence. The main web flow runs from attendee preferences and simulation controls through Flask, which supplies world/profile context to the agent and returns a route recommendation for display. The agent’s monitor–predict–recommend–act–adapt loop and the documented map, accessibility, and simulated-clock features are represented. Some Flask calls and frontend implementation details are omitted from excerpts, so those links rely on the README or SOURCE INDEX evidence.

Main entry points: [`app.py`](https://github.com/chinanagooo/kallangflow/blob/main/app.py) (Flask API), [`kallangflow/agent.py`](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py) (Monitor conditions), [`templates/index.html`](https://github.com/chinanagooo/kallangflow/blob/main/templates/index.html) (Web interface), [`kallangflow/demo.py`](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/demo.py) (Scripted demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Web interface<br/>[index.html]"]
  node_flask["Flask API<br/>[app.py]"]
  node_map["Journey map<br/>[index.html]"]
end

subgraph group_simulation["Crowd simulation"]
  node_world["World models<br/>[models.py]"]
  node_simulator["Crowd simulator<br/>[simulator.py]"]
end

subgraph group_agent["Journey agent"]
  node_monitor["Monitor conditions<br/>[agent.py]"]
  node_tools["World-query tools<br/>[tools.py]"]
  node_predict["Predict changes<br/>[agent.py]"]
  node_recommend["Personalised plan<br/>[agent.py]"]
  node_act["Guardian update<br/>[agent.py]"]
  node_adapt["Adapt loop<br/>[agent.py]"]
  node_guardian_log["Guardian log<br/>[tools.py]"]
end

subgraph group_profiles["Profiles and scale demo"]
  node_profile_db[("Attendee profiles<br/>[db.py]")]
  node_demo["Scripted demo<br/>[demo.py]"]
  node_population["Population model<br/>[population.py]"]
end

node_attendee(("Attendee"))
node_osm["OpenStreetMap tiles"]
node_bedrock["Amazon Bedrock"]

node_attendee -->|"sets preferences"| node_browser
node_browser -->|"sends API requests"| node_flask
node_flask -->|"returns JSON"| node_browser
node_flask -->|"renders page"| node_browser
node_browser -->|"displays route"| node_map
node_map -->|"loads map tiles"| node_osm
node_flask -->|"advances or resets"| node_simulator
node_flask -->|"serializes state"| node_world
node_simulator -->|"updates state"| node_world
node_flask -->|"loads and saves"| node_profile_db
node_flask -->|"starts planning"| node_monitor
node_monitor -->|"invokes tools"| node_tools
node_tools -->|"projects congestion"| node_simulator
node_monitor -->|"passes findings"| node_predict
node_predict -->|"passes forecast"| node_recommend
node_recommend -->|"passes recommendation"| node_act
node_act -->|"records milestone"| node_adapt
node_adapt -->|"repeats if needed"| node_monitor
node_monitor -->|"queries model"| node_bedrock
node_predict -->|"queries model"| node_bedrock
node_recommend -->|"queries model"| node_bedrock
node_act -->|"writes message"| node_bedrock
node_act -->|"notifies"| node_guardian_log
node_demo -->|"loads and saves"| node_profile_db
node_demo -->|"runs scenarios"| node_simulator
node_demo -->|"generates scale"| node_population
node_demo -->|"requests plans"| node_monitor
node_population -->|"weights by congestion"| node_world

click node_browser "https://github.com/chinanagooo/kallangflow/blob/main/templates/index.html"
click node_flask "https://github.com/chinanagooo/kallangflow/blob/main/app.py"
click node_map "https://github.com/chinanagooo/kallangflow/blob/main/templates/index.html"
click node_world "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/models.py"
click node_simulator "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/simulator.py"
click node_monitor "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py"
click node_tools "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/tools.py"
click node_predict "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py"
click node_recommend "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py"
click node_act "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py"
click node_adapt "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py"
click node_guardian_log "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/tools.py"
click node_profile_db "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/db.py"
click node_demo "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/demo.py"
click node_population "https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/population.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_browser,node_flask,node_map toneBlue
class node_world,node_simulator toneAmber
class node_monitor,node_tools,node_predict,node_recommend,node_act,node_adapt,node_guardian_log toneMint
class node_profile_db,node_demo,node_population toneRose
class node_attendee,node_osm,node_bedrock toneIndigo
```

## Components

### Web experience

- [Web interface](https://github.com/chinanagooo/kallangflow/blob/main/templates/index.html): `templates/index.html`
- [Flask API](https://github.com/chinanagooo/kallangflow/blob/main/app.py): `app.py`
- [Journey map](https://github.com/chinanagooo/kallangflow/blob/main/templates/index.html): `templates/index.html`

### Crowd simulation

- [World models](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/models.py): `kallangflow/models.py`
- [Crowd simulator](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/simulator.py): `kallangflow/simulator.py`

### Journey agent

- [Monitor conditions](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py): `kallangflow/agent.py`
- [World-query tools](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/tools.py): `kallangflow/tools.py`
- [Predict changes](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py): `kallangflow/agent.py`
- [Personalised plan](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py): `kallangflow/agent.py`
- [Guardian update](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py): `kallangflow/agent.py`
- [Adapt loop](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/agent.py): `kallangflow/agent.py`
- [Guardian log](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/tools.py): `kallangflow/tools.py`

### Profiles and scale demo

- [Attendee profiles](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/db.py): `kallangflow/db.py`
- [Scripted demo](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/demo.py): `kallangflow/demo.py`
- [Population model](https://github.com/chinanagooo/kallangflow/blob/main/kallangflow/population.py): `kallangflow/population.py`

### Other components

- **Attendee**
- **OpenStreetMap tiles**
- **Amazon Bedrock**

## Connections

- Attendee → Web interface: sets preferences (evidence: `README.md`)
- Web interface → Flask API: sends API requests (evidence: `README.md`)
- Flask API → Web interface: returns JSON (evidence: `README.md`)
- Flask API → Web interface: renders page (evidence: `app.py`)
- Web interface → Journey map: displays route (evidence: `README.md`)
- Journey map → OpenStreetMap tiles: loads map tiles (evidence: `README.md`)
- Flask API → Crowd simulator: advances or resets (evidence: `app.py`)
- Flask API → World models: serializes state (evidence: `app.py`)
- Crowd simulator → World models: updates state (evidence: `kallangflow/simulator.py`)
- Flask API → Attendee profiles: loads and saves (evidence: `app.py`)
- Flask API → Monitor conditions: starts planning (evidence: `app.py`)
- Monitor conditions → World-query tools: invokes tools (evidence: `kallangflow/agent.py`)
- World-query tools → Crowd simulator: projects congestion (evidence: `kallangflow/tools.py`)
- Monitor conditions → Predict changes: passes findings (evidence: `kallangflow/agent.py`)
- Predict changes → Personalised plan: passes forecast (evidence: `kallangflow/agent.py`)
- Personalised plan → Guardian update: passes recommendation (evidence: `kallangflow/agent.py`)
- Guardian update → Adapt loop: records milestone (evidence: `kallangflow/agent.py`)
- Adapt loop → Monitor conditions: repeats if needed (evidence: `kallangflow/agent.py`)
- Monitor conditions → Amazon Bedrock: queries model (evidence: `kallangflow/agent.py`)
- Predict changes → Amazon Bedrock: queries model (evidence: `kallangflow/agent.py`)
- Personalised plan → Amazon Bedrock: queries model (evidence: `kallangflow/agent.py`)
- Guardian update → Amazon Bedrock: writes message (evidence: `kallangflow/agent.py`)
- Guardian update → Guardian log: notifies (evidence: `kallangflow/agent.py`)
- Scripted demo → Attendee profiles: loads and saves (evidence: `kallangflow/demo.py`)
- Scripted demo → Crowd simulator: runs scenarios (evidence: `kallangflow/demo.py`)
- Scripted demo → Population model: generates scale (evidence: `kallangflow/demo.py`)
- Scripted demo → Monitor conditions: requests plans (evidence: `kallangflow/demo.py`)
- Population model → World models: weights by congestion (evidence: `kallangflow/population.py`)