# kspeiris/bot-detection_01 architecture

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

- Interactive diagram: https://gitdiagram.com/kspeiris/bot-detection_01
- Repository: https://github.com/kspeiris/bot-detection_01

## Overview

This is a Flask-based behavioral bot-detection platform. Human visitors and Selenium simulations use the demo pages and send interaction events to the app; events are logged, transformed into session and fixed-window features, scored by rules and models, and reviewed in the admin dashboard with coordination evidence. The graph follows documented workflow links and sampled imports/calls. Some dashboard, logging, and training details are unsampled, so those links rely on README documentation rather than claims about unseen implementation.

Main entry points: [`app.py`](https://github.com/kspeiris/bot-detection_01/blob/main/app.py) (Flask App), [`processing/feature_engine.py`](https://github.com/kspeiris/bot-detection_01/blob/main/processing/feature_engine.py) (Feature Engineering), [`data/features.csv`](https://github.com/kspeiris/bot-detection_01/blob/main/data/features.csv) (Session Features), [`data/window_features.csv`](https://github.com/kspeiris/bot-detection_01/blob/main/data/window_features.csv) (Window Features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture &amp; Demo"]
  node_bots["Bot Simulations"]
  node_browser["Browser Driver<br/>[browser.py]"]
  node_app["Flask App<br/>[app.py]"]
  node_logging["Event Logging<br/>[logger_api.py]"]
  node_validation["Event Validation<br/>[validators.py]"]
end

subgraph group_analytics["Feature Analytics"]
  node_extractor["Feature Extraction"]
  node_feature_engine["Feature Engineering<br/>[feature_engine.py]"]
  node_fingerprint["Behavior Fingerprints"]
  node_windows["Window Builder<br/>[window_builder.py]"]
  node_sessionizer["Sessionization<br/>[sessionizer.py]"]
end

subgraph group_detection["Detection"]
  node_rules["Rule Detection<br/>[rules.py]"]
  node_individual_model["Session Model"]
  node_window_model["Window Models"]
  node_coord_engine["Coordination Engine"]
  node_coord_analysis["Coordination Analysis"]
  node_fusion["Risk Fusion<br/>[risk_fusion.py]"]
end

subgraph group_review["Review UI"]
  node_dashboard["Admin Dashboard<br/>[dashboard.html]"]
  node_dashboard_js["Dashboard Controls<br/>[dashboard.js]"]
  node_page_ui["Demo Pages<br/>[page.html]"]
end

subgraph group_runtime["Runtime Artifacts"]
  node_events[("Raw Events<br/>[events.csv]")]
  node_session_features[("Session Features<br/>[features.csv]")]
  node_window_features[("Window Features")]
  node_artifact_store["Artifact Store<br/>[artifact_store.py]"]
end

node_human(("Human Visitor"))

node_human -->|"uses pages"| node_app
node_bots -->|"sends events"| node_app
node_bots -->|"drives browser"| node_browser
node_app -->|"accepts events"| node_logging
node_logging -->|"validates payload"| node_validation
node_logging -->|"writes events"| node_events
node_extractor -->|"reads events"| node_events
node_extractor -->|"calls extraction"| node_feature_engine
node_feature_engine -->|"builds fingerprints"| node_fingerprint
node_feature_engine -->|"builds windows"| node_windows
node_feature_engine -->|"writes features"| node_session_features
node_feature_engine -->|"writes features"| node_window_features
node_extractor -->|"resolves artifacts"| node_artifact_store
node_feature_engine -->|"writes artifacts"| node_artifact_store
node_sessionizer -.->|"supports grouping"| node_feature_engine
node_session_features -->|"scores sessions"| node_rules
node_session_features -->|"scores sessions"| node_individual_model
node_window_features -->|"scores windows"| node_window_model
node_window_features -->|"analyzes windows"| node_coord_analysis
node_coord_analysis -->|"calls analysis"| node_coord_engine
node_rules -->|"provides rule scores"| node_app
node_individual_model -.->|"provides model scores"| node_app
node_window_model -.->|"provides window scores"| node_app
node_coord_engine -.->|"provides group evidence"| node_app
node_app -->|"builds fused risk"| node_fusion
node_app -->|"reads features"| node_session_features
node_app -->|"reads features"| node_window_features
node_app -->|"serves results"| node_dashboard
node_dashboard -.->|"uses controls"| node_dashboard_js
node_human -->|"navigates demo"| node_page_ui
node_artifact_store -->|"stores artifacts"| node_session_features
node_artifact_store -->|"stores artifacts"| node_window_features

click node_bots "https://github.com/kspeiris/bot-detection_01/blob/main/bot_simulation/synthetic_runner.py"
click node_browser "https://github.com/kspeiris/bot-detection_01/blob/main/bot_simulation/browser.py"
click node_app "https://github.com/kspeiris/bot-detection_01/blob/main/app.py"
click node_logging "https://github.com/kspeiris/bot-detection_01/blob/main/ingestion/logger_api.py"
click node_validation "https://github.com/kspeiris/bot-detection_01/blob/main/ingestion/validators.py"
click node_events "https://github.com/kspeiris/bot-detection_01/blob/main/data/events.csv"
click node_extractor "https://github.com/kspeiris/bot-detection_01/blob/main/feature_extraction/extract_features.py"
click node_feature_engine "https://github.com/kspeiris/bot-detection_01/blob/main/processing/feature_engine.py"
click node_fingerprint "https://github.com/kspeiris/bot-detection_01/blob/main/processing/fingerprint_engine.py"
click node_windows "https://github.com/kspeiris/bot-detection_01/blob/main/processing/window_builder.py"
click node_sessionizer "https://github.com/kspeiris/bot-detection_01/blob/main/processing/sessionizer.py"
click node_session_features "https://github.com/kspeiris/bot-detection_01/blob/main/data/features.csv"
click node_window_features "https://github.com/kspeiris/bot-detection_01/blob/main/data/window_features.csv"
click node_rules "https://github.com/kspeiris/bot-detection_01/blob/main/detection/rules.py"
click node_individual_model "https://github.com/kspeiris/bot-detection_01/blob/main/detection/individual_model.py"
click node_window_model "https://github.com/kspeiris/bot-detection_01/tree/main/models"
click node_coord_engine "https://github.com/kspeiris/bot-detection_01/blob/main/detection/coordination_engine.py"
click node_coord_analysis "https://github.com/kspeiris/bot-detection_01/blob/main/coordination_analysis/detect_coordination.py"
click node_fusion "https://github.com/kspeiris/bot-detection_01/blob/main/detection/risk_fusion.py"
click node_artifact_store "https://github.com/kspeiris/bot-detection_01/blob/main/artifact_store.py"
click node_dashboard "https://github.com/kspeiris/bot-detection_01/blob/main/templates/dashboard.html"
click node_dashboard_js "https://github.com/kspeiris/bot-detection_01/blob/main/static/dashboard.js"
click node_page_ui "https://github.com/kspeiris/bot-detection_01/blob/main/templates/page.html"

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_bots,node_browser,node_app,node_logging,node_validation toneBlue
class node_extractor,node_feature_engine,node_fingerprint,node_windows,node_sessionizer toneAmber
class node_rules,node_individual_model,node_window_model,node_coord_engine,node_coord_analysis,node_fusion toneMint
class node_dashboard,node_dashboard_js,node_page_ui toneRose
class node_events,node_session_features,node_window_features,node_artifact_store,node_human toneIndigo
```

## Components

### Capture & Demo

- [Bot Simulations](https://github.com/kspeiris/bot-detection_01/blob/main/bot_simulation/synthetic_runner.py): `bot_simulation/synthetic_runner.py`
- [Browser Driver](https://github.com/kspeiris/bot-detection_01/blob/main/bot_simulation/browser.py): `bot_simulation/browser.py`
- [Flask App](https://github.com/kspeiris/bot-detection_01/blob/main/app.py): `app.py`
- [Event Logging](https://github.com/kspeiris/bot-detection_01/blob/main/ingestion/logger_api.py): `ingestion/logger_api.py`
- [Event Validation](https://github.com/kspeiris/bot-detection_01/blob/main/ingestion/validators.py): `ingestion/validators.py`

### Feature Analytics

- [Feature Extraction](https://github.com/kspeiris/bot-detection_01/blob/main/feature_extraction/extract_features.py): `feature_extraction/extract_features.py`
- [Feature Engineering](https://github.com/kspeiris/bot-detection_01/blob/main/processing/feature_engine.py): `processing/feature_engine.py`
- [Behavior Fingerprints](https://github.com/kspeiris/bot-detection_01/blob/main/processing/fingerprint_engine.py): `processing/fingerprint_engine.py`
- [Window Builder](https://github.com/kspeiris/bot-detection_01/blob/main/processing/window_builder.py): `processing/window_builder.py`
- [Sessionization](https://github.com/kspeiris/bot-detection_01/blob/main/processing/sessionizer.py): `processing/sessionizer.py`

### Detection

- [Rule Detection](https://github.com/kspeiris/bot-detection_01/blob/main/detection/rules.py): `detection/rules.py`
- [Session Model](https://github.com/kspeiris/bot-detection_01/blob/main/detection/individual_model.py): `detection/individual_model.py`
- [Window Models](https://github.com/kspeiris/bot-detection_01/tree/main/models): `models`
- [Coordination Engine](https://github.com/kspeiris/bot-detection_01/blob/main/detection/coordination_engine.py): `detection/coordination_engine.py`
- [Coordination Analysis](https://github.com/kspeiris/bot-detection_01/blob/main/coordination_analysis/detect_coordination.py): `coordination_analysis/detect_coordination.py`
- [Risk Fusion](https://github.com/kspeiris/bot-detection_01/blob/main/detection/risk_fusion.py): `detection/risk_fusion.py`

### Review UI

- [Admin Dashboard](https://github.com/kspeiris/bot-detection_01/blob/main/templates/dashboard.html): `templates/dashboard.html`
- [Dashboard Controls](https://github.com/kspeiris/bot-detection_01/blob/main/static/dashboard.js): `static/dashboard.js`
- [Demo Pages](https://github.com/kspeiris/bot-detection_01/blob/main/templates/page.html): `templates/page.html`

### Runtime Artifacts

- [Raw Events](https://github.com/kspeiris/bot-detection_01/blob/main/data/events.csv): `data/events.csv`
- [Session Features](https://github.com/kspeiris/bot-detection_01/blob/main/data/features.csv): `data/features.csv`
- [Window Features](https://github.com/kspeiris/bot-detection_01/blob/main/data/window_features.csv): `data/window_features.csv`
- [Artifact Store](https://github.com/kspeiris/bot-detection_01/blob/main/artifact_store.py): `artifact_store.py`

### Other components

- **Human Visitor**

## Connections

- Human Visitor → Flask App: uses pages (evidence: `README.md`)
- Bot Simulations → Flask App: sends events (evidence: `bot_simulation/synthetic_runner.py`)
- Bot Simulations → Browser Driver: drives browser (evidence: `bot_simulation/fast_bot.py`)
- Flask App → Event Logging: accepts events (evidence: `README.md`)
- Event Logging → Event Validation: validates payload (evidence: `ingestion/logger_api.py`)
- Event Logging → Raw Events: writes events (evidence: `README.md`)
- Feature Extraction → Raw Events: reads events (evidence: `feature_extraction/extract_features.py`)
- Feature Extraction → Feature Engineering: calls extraction (evidence: `feature_extraction/extract_features.py`)
- Feature Engineering → Behavior Fingerprints: builds fingerprints (evidence: `processing/feature_engine.py`)
- Feature Engineering → Window Builder: builds windows (evidence: `processing/feature_engine.py`)
- Feature Engineering → Session Features: writes features (evidence: `README.md`)
- Feature Engineering → Window Features: writes features (evidence: `README.md`)
- Feature Extraction → Artifact Store: resolves artifacts (evidence: `feature_extraction/extract_features.py`)
- Feature Engineering → Artifact Store: writes artifacts (evidence: `processing/feature_engine.py`)
- Sessionization → Feature Engineering: supports grouping
- Session Features → Rule Detection: scores sessions (evidence: `README.md`)
- Session Features → Session Model: scores sessions (evidence: `README.md`)
- Window Features → Window Models: scores windows (evidence: `README.md`)
- Window Features → Coordination Analysis: analyzes windows (evidence: `README.md`)
- Coordination Analysis → Coordination Engine: calls analysis (evidence: `coordination_analysis/detect_coordination.py`)
- Rule Detection → Flask App: provides rule scores (evidence: `app.py`)
- Session Model → Flask App: provides model scores
- Window Models → Flask App: provides window scores
- Coordination Engine → Flask App: provides group evidence (evidence: `app.py`)
- Flask App → Risk Fusion: builds fused risk (evidence: `app.py`)
- Flask App → Session Features: reads features (evidence: `README.md`)
- Flask App → Window Features: reads features (evidence: `README.md`)
- Flask App → Admin Dashboard: serves results (evidence: `README.md`)
- Admin Dashboard → Dashboard Controls: uses controls
- Human Visitor → Demo Pages: navigates demo (evidence: `README.md`)
- Artifact Store → Session Features: stores artifacts
- Artifact Store → Window Features: stores artifacts
