# robiul-hasan-jisan/cityguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/robiul-hasan-jisan/cityguard-ai
- Repository: https://github.com/robiul-hasan-jisan/cityguard-ai

## Overview

1. **What this repository is**
   - CityGuard is a **single-repo crime analytics dashboard** for San Francisco crime data.
   - The architecture is centered on **offline analysis + generated visual artifacts + a lightweight Python web UI**.

2. **Primary data source**
   - The only raw input tracked in the repo is **`data/train.csv`**, which is the historical crime incident dataset.
   - The README indicates this is sourced from **Kaggle / SFPD crime data**, so the app is fundamentally **file-backed**, not database-backed.

3. **Analysis pipeline boundary**
   - The **`notebooks/crime-analysis.ipynb`** notebook is the main analytical workspace.
   - It appears to perform the heavy lifting: cleaning, aggregation, anomaly detection, clustering, and chart/map generation.
   - This is the repo’s **offline compute layer**; it likely produces the CSV summaries and HTML outputs consumed by the dashboard.

4. **Generated analytics artifacts**
   - The `notebooks/` folder contains multiple derived outputs:
     - **`category_statistics.csv`**
     - **`cluster_statistics.csv`**
     - **`district_statistics.csv`**
     - **`weekly_crime_summary.csv`**
     - **`summary_report.txt`**
     - **`sf_crime_map.html`**
     - **`crime_insights_panel.html`**
   - These files indicate a **batch-processing workflow** where the notebook materializes results for later viewing, rather than computing everything live.

5. **Geospatial subsystem**
   - A major subsystem is **map-based crime visualization**.
   - The repo uses **Folium**-style outputs (per README and generated `.html` files) to render:
     - district overlays
     - heatmaps
     - hotspot/clustering views
   - This suggests a clean boundary between **spatial analytics** and the web UI that displays the resulting map pages.

6. **Statistical/ML subsystem**
   - The README describes **weekly trend analysis, anomaly detection, and K-Means clustering**.
   - Those capabilities are likely implemented in the notebook and summarized into the CSV artifacts.
   - In architectural terms, this is the **analytics engine**: it transforms raw incidents into features, clusters, alerts, and rankings.

7. **Web application layer**
   - The top-level Python files **`app.py`** and **`flask.py`** represent the application entry points.
   - The README describes both **Flask** and **Streamlit** variants, but the current tree only includes these top-level Python files, so the repo appears to be a **Python-first dashboard UI** with at least one Flask-oriented entry point.
   - The UI likely reads the generated analytics artifacts and presents them as tabs/charts/maps.

8. **Presentation/reporting outputs**
   - The repo includes **`demo.mp4`** plus HTML panels/maps in `notebooks/`, which are effectively **deliverables** rather than core logic.
   - These assets support sharing, demos, and static reporting outside the live app.
   - The architecture therefore includes both a **live dashboard** and **pre-rendered report artifacts**.

9. **Dependency stack that shapes the design**
   - `requirements.txt` (per README) points to a stack built on:
     - **pandas/numpy/scipy** for data processing
     - **scikit-learn** for clustering
     - **plotly/matplotlib/seaborn/folium** for visualization
     - **Flask** and **Streamlit** for the UI layer
   - This is a **local Python analytics app**, not a microservice system.

10. **Operational model**
   - There is no evidence of a separate database, message queue, or external API runtime.
   - The app likely runs as a **single-process local/server-side Python application** that loads CSVs and generated artifacts from disk.
   - That makes the main boundaries: **raw data in `data/` → analysis in notebooks → UI in top-level app files → rendered outputs in notebook-generated HTML/CSV**.

11. **Important repo note for diagram accuracy**
   - The README mentions files like `app_flask.py`, `app_streamlit.py`, `templates/index.html`, and `outputs/`, but those are **not present in the provided tree**.
   - For an architecture diagram based on the actual repository contents, treat the **notebooks and generated artifacts as the existing core**, and treat the README’s extra paths as either **planned structure or stale documentation**.

Main entry points: [`notebooks/crime-analysis.ipynb`](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/crime-analysis.ipynb) (Analysis notebook), [`app.py`](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/app.py) (App entry), [`requirements.txt`](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/requirements.txt) (Deps), [`README.md`](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/README.md) (README)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_data["Data"]
  node_data_train_csv[("Crime data<br/>csv source<br/>[train.csv]")]
end

subgraph group_g_analysis["Analysis"]
  node_crime_analysis_ipynb["Analysis notebook<br/>offline pipeline"]
end

subgraph group_g_ui["UI"]
  node_app_py["App entry<br/>python ui<br/>[app.py]"]
  node_flask_py["Flask entry<br/>python web<br/>[flask.py]"]
  node_requirements_txt["Deps<br/>[requirements.txt]"]
  node_readme_md["README<br/>project guide<br/>[README.md]"]
  node_gitattributes["Git attrs<br/>repo config<br/>[.gitattributes]"]
  node_gitignore["Git ignore<br/>repo config<br/>[.gitignore]"]
end

subgraph group_g_outputs["Outputs"]
  node_category_statistics_csv["Category stats<br/>derived csv"]
  node_cluster_statistics_csv["Cluster stats<br/>derived csv"]
  node_district_statistics_csv["District stats<br/>derived csv"]
  node_weekly_crime_summary_csv["Weekly trends<br/>derived csv"]
  node_summary_report_txt["Summary report<br/>text report<br/>[summary_report.txt]"]
  node_sf_crime_map_html["Crime map<br/>html map<br/>[sf_crime_map.html]"]
  node_crime_insights_panel_html["Insights panel<br/>html report"]
  node_demo_mp4(("Demo video<br/>media demo<br/>[demo.mp4]"))
end

node_data_train_csv -->|"input"| node_crime_analysis_ipynb
node_crime_analysis_ipynb -->|"derive"| node_category_statistics_csv
node_crime_analysis_ipynb -->|"derive"| node_cluster_statistics_csv
node_crime_analysis_ipynb -->|"derive"| node_district_statistics_csv
node_crime_analysis_ipynb -->|"derive"| node_weekly_crime_summary_csv
node_crime_analysis_ipynb -->|"report"| node_summary_report_txt
node_crime_analysis_ipynb -->|"render"| node_sf_crime_map_html
node_crime_analysis_ipynb -->|"render"| node_crime_insights_panel_html
node_app_py -->|"read"| node_category_statistics_csv
node_app_py -->|"read"| node_cluster_statistics_csv
node_app_py -->|"read"| node_district_statistics_csv
node_app_py -->|"read"| node_weekly_crime_summary_csv
node_app_py -->|"embed"| node_sf_crime_map_html
node_flask_py -->|"serve"| node_crime_insights_panel_html
node_requirements_txt -.->|"supports"| node_crime_analysis_ipynb
node_requirements_txt -.->|"supports"| node_app_py
node_readme_md -.->|"documents"| node_app_py
node_readme_md -.->|"documents"| node_crime_analysis_ipynb

click node_data_train_csv "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/data/train.csv"
click node_crime_analysis_ipynb "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/crime-analysis.ipynb"
click node_app_py "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/app.py"
click node_flask_py "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/flask.py"
click node_category_statistics_csv "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/category_statistics.csv"
click node_cluster_statistics_csv "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/cluster_statistics.csv"
click node_district_statistics_csv "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/district_statistics.csv"
click node_weekly_crime_summary_csv "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/weekly_crime_summary.csv"
click node_summary_report_txt "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/summary_report.txt"
click node_sf_crime_map_html "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/sf_crime_map.html"
click node_crime_insights_panel_html "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/crime_insights_panel.html"
click node_demo_mp4 "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/demo.mp4"
click node_requirements_txt "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/requirements.txt"
click node_readme_md "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/README.md"
click node_gitattributes "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/.gitattributes"
click node_gitignore "https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/.gitignore"

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_data_train_csv toneBlue
class node_crime_analysis_ipynb toneAmber
class node_app_py,node_flask_py,node_requirements_txt,node_readme_md,node_gitattributes,node_gitignore toneMint
class node_category_statistics_csv,node_cluster_statistics_csv,node_district_statistics_csv,node_weekly_crime_summary_csv,node_summary_report_txt,node_sf_crime_map_html,node_crime_insights_panel_html,node_demo_mp4 toneRose
```

## Components

### Data

Raw crime data source

- [Crime data](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/data/train.csv): csv source · Historical San Francisco crime incidents used as the raw input dataset · `data/train.csv`

### Analysis

Offline analytics pipeline

- [Analysis notebook](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/crime-analysis.ipynb): offline pipeline · Main notebook that cleans, aggregates, models, and produces derived artifacts · `notebooks/crime-analysis.ipynb`

### UI

Python dashboard entry points

- [App entry](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/app.py): python ui · Primary Python application entry point for the dashboard · `app.py`
- [Flask entry](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/flask.py): python web · Additional Flask-oriented application entry point · `flask.py`
- [Deps](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/requirements.txt): python deps · Dependency specification shaping the analytics, visualization, and web stack · `requirements.txt`
- [README](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/README.md): project guide · Repository overview and usage notes, including the intended app structure · `README.md`
- [Git attrs](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/.gitattributes): repo config · Version-control configuration for line ending and file handling · `.gitattributes`
- [Git ignore](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/.gitignore): repo config · Ignored files and local environment exclusions · `.gitignore`

### Outputs

Generated artifacts and reports

- [Category stats](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/category_statistics.csv): derived csv · Category-level aggregation output from the analysis pipeline · `notebooks/category_statistics.csv`
- [Cluster stats](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/cluster_statistics.csv): derived csv · Clustering summary output from the analysis pipeline · `notebooks/cluster_statistics.csv`
- [District stats](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/district_statistics.csv): derived csv · District-level aggregation output from the analysis pipeline · `notebooks/district_statistics.csv`
- [Weekly trends](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/weekly_crime_summary.csv): derived csv · Weekly crime summary used for trend reporting and dashboard views · `notebooks/weekly_crime_summary.csv`
- [Summary report](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/summary_report.txt): text report · Narrative summary generated by the analysis notebook · `notebooks/summary_report.txt`
- [Crime map](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/sf_crime_map.html): html map · Rendered geospatial visualization of crime patterns and hotspots · `notebooks/sf_crime_map.html`
- [Insights panel](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/notebooks/crime_insights_panel.html): html report · Pre-rendered insights panel for sharing or embedding in the dashboard · `notebooks/crime_insights_panel.html`
- [Demo video](https://github.com/robiul-hasan-jisan/cityguard-ai/blob/main/demo.mp4): media demo · Recorded demonstration of the dashboard and visual outputs · `demo.mp4`

## Connections

- Crime data → Analysis notebook: input · Raw incidents are loaded into the offline analysis notebook
- Analysis notebook → Category stats: derive · Notebook produces category-level summary data
- Analysis notebook → Cluster stats: derive · Notebook produces clustering statistics
- Analysis notebook → District stats: derive · Notebook produces district summaries
- Analysis notebook → Weekly trends: derive · Notebook produces weekly trend summaries
- Analysis notebook → Summary report: report · Notebook emits a narrative summary report
- Analysis notebook → Crime map: render · Notebook generates the interactive crime map artifact
- Analysis notebook → Insights panel: render · Notebook generates the insights panel artifact
- App entry → Category stats: read · Dashboard consumes generated analytics artifacts
- App entry → Cluster stats: read · Dashboard consumes generated analytics artifacts
- App entry → District stats: read · Dashboard consumes generated analytics artifacts
- App entry → Weekly trends: read · Dashboard consumes generated analytics artifacts
- App entry → Crime map: embed · Dashboard presents the generated map artifact
- Flask entry → Insights panel: serve · Flask entry point can serve the pre-rendered insights panel
- Deps → Analysis notebook: supports · Dependencies enable data processing, ML, and visualization
- Deps → App entry: supports · Dependencies enable the Python web UI
- README → App entry: documents · README describes the dashboard application entry points and workflow
- README → Analysis notebook: documents · README explains the notebook-driven analytics pipeline