# codestartai-009/capstone architecture

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

- Interactive diagram: https://gitdiagram.com/codestartai-009/capstone
- Repository: https://github.com/codestartai-009/capstone

## Overview

This repository provides phishing-URL risk assessment through a Flask API and web scanner, scan history, and a Chrome extension, alongside a reproducible ML pipeline. In the live workflow, a user or extension submits a URL; Flask routes it to prediction services, which invoke the model pipeline and return a risk signal. The service can add optional threat-intelligence results, and scans can be saved for history and dashboard use. The graph also shows model training and evaluation. Some frontend and route internals were not excerpted, so those links rely on README statements or are omitted.

Main entry points: [`backend/routes`](https://github.com/codestartai-009/capstone/tree/main/backend/routes) (API Routes), [`ml/dataset.py`](https://github.com/codestartai-009/capstone/blob/main/ml/dataset.py) (Dataset Preparation), [`services/prediction_service.py`](https://github.com/codestartai-009/capstone/blob/main/services/prediction_service.py) (Prediction Service), [`ml/feature_extractor.py`](https://github.com/codestartai-009/capstone/blob/main/ml/feature_extractor.py) (Feature Extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_flask["Flask App<br/>[__init__.py]"]
  node_api_routes["API Routes"]
end

subgraph group_experience["Scanner Clients"]
  node_web_scanner["Web Scanner<br/>[scanner.js]"]
  node_web_dashboard["History Dashboard<br/>[dashboard.js]"]
  node_chrome_extension["Chrome Extension<br/>[popup.js]"]
end

subgraph group_prediction["Risk Assessment"]
  node_prediction_service["Prediction Service"]
  node_threat_intel["Threat Intelligence"]
  node_predictor["Model Predictor<br/>[predictor.py]"]
  node_url_utils["URL Handling<br/>[url_utils.py]"]
  node_feature_extractor["Feature Extraction"]
  node_explanations["Risk Explanations"]
end

subgraph group_history["Scan History"]
  node_history_service["History Service<br/>[history_service.py]"]
  node_repository["Scan Repository<br/>[repository.py]"]
  node_sqlite[("SQLite History<br/>[database.py]")]
end

subgraph group_ml["ML Pipeline"]
  node_schema["Feature Schema<br/>[feature_schema.py]"]
  node_dataset["Dataset Preparation<br/>[dataset.py]"]
  node_training["Model Training<br/>[train_model.py]"]
  node_model_utils["Model Utilities<br/>[model_utils.py]"]
  node_evaluation["Model Evaluation<br/>[evaluate_model.py]"]
  node_error_analysis["Error Analysis<br/>[error_analysis.py]"]
end

node_user(("User"))
node_extension_user(("Extension User"))

node_user -->|"scans URL"| node_web_scanner
node_extension_user -->|"checks current tab"| node_chrome_extension
node_web_scanner -->|"submits scan"| node_api_routes
node_chrome_extension -->|"requests scan"| node_api_routes
node_api_routes -->|"served by"| node_flask
node_flask -->|"registers routes"| node_api_routes
node_api_routes -->|"requests prediction"| node_prediction_service
node_api_routes -->|"requests history"| node_history_service
node_prediction_service -->|"scores URL"| node_predictor
node_prediction_service -.->|"optional lookup"| node_threat_intel
node_predictor -->|"extracts features"| node_feature_extractor
node_predictor -->|"builds explanations"| node_explanations
node_feature_extractor -->|"normalizes URL"| node_url_utils
node_feature_extractor -->|"uses feature definitions"| node_schema
node_history_service -->|"reads and writes scans"| node_repository
node_repository -.->|"persists scans"| node_sqlite
node_sqlite -->|"defines migrations"| node_schema
node_dataset -->|"recomputes features"| node_feature_extractor
node_dataset -->|"uses feature definitions"| node_schema
node_training -->|"prepares data"| node_dataset
node_training -->|"uses model utilities"| node_model_utils
node_evaluation -->|"evaluates splits"| node_dataset
node_evaluation -->|"uses metrics"| node_model_utils
node_error_analysis -->|"analyzes data"| node_dataset
node_error_analysis -->|"uses model utilities"| node_model_utils
node_web_dashboard -->|"loads scan history"| node_api_routes
node_api_routes -->|"serves model details"| node_prediction_service

click node_flask "https://github.com/codestartai-009/capstone/blob/main/backend/__init__.py"
click node_api_routes "https://github.com/codestartai-009/capstone/tree/main/backend/routes"
click node_web_scanner "https://github.com/codestartai-009/capstone/blob/main/static/js/scanner.js"
click node_web_dashboard "https://github.com/codestartai-009/capstone/blob/main/static/js/dashboard.js"
click node_chrome_extension "https://github.com/codestartai-009/capstone/blob/main/extension/popup.js"
click node_prediction_service "https://github.com/codestartai-009/capstone/blob/main/services/prediction_service.py"
click node_threat_intel "https://github.com/codestartai-009/capstone/blob/main/services/threat_intelligence.py"
click node_predictor "https://github.com/codestartai-009/capstone/blob/main/ml/predictor.py"
click node_url_utils "https://github.com/codestartai-009/capstone/blob/main/ml/url_utils.py"
click node_feature_extractor "https://github.com/codestartai-009/capstone/blob/main/ml/feature_extractor.py"
click node_explanations "https://github.com/codestartai-009/capstone/blob/main/services/explanation_engine.py"
click node_history_service "https://github.com/codestartai-009/capstone/blob/main/services/history_service.py"
click node_repository "https://github.com/codestartai-009/capstone/blob/main/database/repository.py"
click node_sqlite "https://github.com/codestartai-009/capstone/blob/main/database/database.py"
click node_schema "https://github.com/codestartai-009/capstone/blob/main/ml/feature_schema.py"
click node_dataset "https://github.com/codestartai-009/capstone/blob/main/ml/dataset.py"
click node_training "https://github.com/codestartai-009/capstone/blob/main/ml/train_model.py"
click node_model_utils "https://github.com/codestartai-009/capstone/blob/main/ml/model_utils.py"
click node_evaluation "https://github.com/codestartai-009/capstone/blob/main/ml/evaluate_model.py"
click node_error_analysis "https://github.com/codestartai-009/capstone/blob/main/ml/error_analysis.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_flask,node_api_routes,node_user,node_extension_user toneBlue
class node_web_scanner,node_web_dashboard,node_chrome_extension toneAmber
class node_prediction_service,node_threat_intel,node_predictor,node_url_utils,node_feature_extractor,node_explanations toneMint
class node_history_service,node_repository,node_sqlite toneRose
class node_schema,node_dataset,node_training,node_model_utils,node_evaluation,node_error_analysis toneIndigo
```

## Components

### Application

- [Flask App](https://github.com/codestartai-009/capstone/blob/main/backend/__init__.py): `backend/__init__.py`
- [API Routes](https://github.com/codestartai-009/capstone/tree/main/backend/routes): `backend/routes`

### Scanner Clients

- [Web Scanner](https://github.com/codestartai-009/capstone/blob/main/static/js/scanner.js): `static/js/scanner.js`
- [History Dashboard](https://github.com/codestartai-009/capstone/blob/main/static/js/dashboard.js): `static/js/dashboard.js`
- [Chrome Extension](https://github.com/codestartai-009/capstone/blob/main/extension/popup.js): `extension/popup.js`

### Risk Assessment

- [Prediction Service](https://github.com/codestartai-009/capstone/blob/main/services/prediction_service.py): `services/prediction_service.py`
- [Threat Intelligence](https://github.com/codestartai-009/capstone/blob/main/services/threat_intelligence.py): `services/threat_intelligence.py`
- [Model Predictor](https://github.com/codestartai-009/capstone/blob/main/ml/predictor.py): `ml/predictor.py`
- [URL Handling](https://github.com/codestartai-009/capstone/blob/main/ml/url_utils.py): `ml/url_utils.py`
- [Feature Extraction](https://github.com/codestartai-009/capstone/blob/main/ml/feature_extractor.py): `ml/feature_extractor.py`
- [Risk Explanations](https://github.com/codestartai-009/capstone/blob/main/services/explanation_engine.py): `services/explanation_engine.py`

### Scan History

- [History Service](https://github.com/codestartai-009/capstone/blob/main/services/history_service.py): `services/history_service.py`
- [Scan Repository](https://github.com/codestartai-009/capstone/blob/main/database/repository.py): `database/repository.py`
- [SQLite History](https://github.com/codestartai-009/capstone/blob/main/database/database.py): `database/database.py`

### ML Pipeline

- [Feature Schema](https://github.com/codestartai-009/capstone/blob/main/ml/feature_schema.py): `ml/feature_schema.py`
- [Dataset Preparation](https://github.com/codestartai-009/capstone/blob/main/ml/dataset.py): `ml/dataset.py`
- [Model Training](https://github.com/codestartai-009/capstone/blob/main/ml/train_model.py): `ml/train_model.py`
- [Model Utilities](https://github.com/codestartai-009/capstone/blob/main/ml/model_utils.py): `ml/model_utils.py`
- [Model Evaluation](https://github.com/codestartai-009/capstone/blob/main/ml/evaluate_model.py): `ml/evaluate_model.py`
- [Error Analysis](https://github.com/codestartai-009/capstone/blob/main/ml/error_analysis.py): `ml/error_analysis.py`

### Other components

- **User**
- **Extension User**

## Connections

- User → Web Scanner: scans URL (evidence: `README.md`)
- Extension User → Chrome Extension: checks current tab (evidence: `README.md`)
- Web Scanner → API Routes: submits scan (evidence: `README.md`)
- Chrome Extension → API Routes: requests scan (evidence: `README.md`)
- API Routes → Flask App: served by (evidence: `backend/__init__.py`)
- Flask App → API Routes: registers routes (evidence: `backend/__init__.py`)
- API Routes → Prediction Service: requests prediction (evidence: `backend/routes/prediction.py`)
- API Routes → History Service: requests history (evidence: `backend/routes/history.py`)
- Prediction Service → Model Predictor: scores URL (evidence: `services/prediction_service.py`)
- Prediction Service → Threat Intelligence: optional lookup (evidence: `services/prediction_service.py`)
- Model Predictor → Feature Extraction: extracts features (evidence: `ml/predictor.py`)
- Model Predictor → Risk Explanations: builds explanations (evidence: `ml/predictor.py`)
- Feature Extraction → URL Handling: normalizes URL (evidence: `ml/feature_extractor.py`)
- Feature Extraction → Feature Schema: uses feature definitions (evidence: `ml/feature_extractor.py`)
- History Service → Scan Repository: reads and writes scans (evidence: `services/history_service.py`)
- Scan Repository → SQLite History: persists scans
- SQLite History → Feature Schema: defines migrations (evidence: `database/database.py`)
- Dataset Preparation → Feature Extraction: recomputes features (evidence: `ml/dataset.py`)
- Dataset Preparation → Feature Schema: uses feature definitions (evidence: `ml/dataset.py`)
- Model Training → Dataset Preparation: prepares data (evidence: `ml/train_model.py`)
- Model Training → Model Utilities: uses model utilities (evidence: `ml/train_model.py`)
- Model Evaluation → Dataset Preparation: evaluates splits (evidence: `ml/evaluate_model.py`)
- Model Evaluation → Model Utilities: uses metrics (evidence: `ml/evaluate_model.py`)
- Error Analysis → Dataset Preparation: analyzes data (evidence: `ml/error_analysis.py`)
- Error Analysis → Model Utilities: uses model utilities (evidence: `ml/error_analysis.py`)
- History Dashboard → API Routes: loads scan history (evidence: `README.md`)
- API Routes → Prediction Service: serves model details (evidence: `backend/routes/model.py`)
