robiul-hasan-jisan/cityguard-ai

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.