# hemanthkbasali/qrshield architecture

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

- Interactive diagram: https://gitdiagram.com/hemanthkbasali/qrshield
- Repository: https://github.com/hemanthkbasali/qrshield

## Overview

1. **Overall shape**
   - QRShield is a **server-rendered Django monolith** with one main business app, `scanner`, plus Django project glue in `qrshield`.
   - The runtime is classic Django: HTTP requests hit `urls.py`, are handled by views, rendered with templates, and persisted through Django ORM models.

2. **Primary user-facing surfaces**
   - The app is organized around pages for **landing, login/register, dashboard, scanner, results, history, reports, settings, threat intel, and invalid QR/error states**.
   - These are mostly Django templates under `backend/templates`, with shared layout/components for a sidebar, app shell, and risk badges.

3. **Authentication and account boundary**
   - Authentication is built into the Django session layer, with explicit login/registration pages and user settings.
   - This boundary separates anonymous public pages from authenticated pages like scanning history, dashboards, and report actions.

4. **QR scanning ingestion flow**
   - The core flow starts at the scanner UI: users upload or drag-and-drop a QR image.
   - The backend validates the upload, stores media when needed, decodes the QR image, and turns the payload into a URL or text record for analysis.
   - `forms.py`, `validators.py`, `utils.py`, and `middleware.py` suggest a thin request-validation layer around the scan pipeline.

5. **Decoding and analysis pipeline**
   - QR decoding is handled by dedicated modules: `qr_reader.py` for extraction, `detector.py` for threat analysis, and `brand_detector.py` for brand/lure heuristics.
   - The readme indicates the pipeline uses **pyzbar + OpenCV fallback** for decoding and then applies phishing heuristics such as HTTPS checks, IP-based URLs, shorteners, suspicious keywords, redirect parameters, random-looking domains, and login/payment lure patterns.
   - The output is a **risk classification**: Safe, Warning, or Malicious, with a score and explanation data.

6. **Persistence and scan history**
   - The `models.py` and migrations indicate scan results are stored in the database, not just rendered transiently.
   - This persistence drives history views, searchable/filterable lists, timestamps, and later analytics; the dashboard is described as using **real scan records** rather than mock data.

7. **Reports and export boundary**
   - A separate `report_generator.py` module produces **PDF security reports** using ReportLab.
   - Reports include the QR image, extracted payload, risk score, threats, recommendations, and timestamp, and are saved under `backend/reports`.
   - This creates a clear boundary between interactive scanning and offline/shareable evidence artifacts.

8. **Analytics and dashboard subsystem**
   - Dashboard and threat-intel pages are built from stored scan records and aggregated findings.
   - This means the UI is fed by database-backed summaries rather than a live external threat feed, so the architecture is centered on internal scan telemetry.

9. **Presentation layer and static assets**
   - The user interface is mostly Django templates plus static assets in `backend/static/scanner`.
   - There is also a separate `frontend/` workspace with Tailwind configuration and input CSS, which appears to support styling/build-time asset generation rather than being a standalone SPA runtime.

10. **Data/storage layout**
   - `backend/media` stores uploaded QR images, while `backend/reports` stores generated PDFs.
   - This separation matters architecturally: input artifacts, persisted scan records, and export artifacts are kept in different storage areas.

11. **Deployment and runtime configuration**
   - The project supports both **MySQL and SQLite** via environment-driven settings in `backend/qrshield/settings.py` and `.env.example`.
   - Django is exposed through both `wsgi.py` and `asgi.py`, so the repo supports standard synchronous deployment and ASGI-capable servers.

12. **External dependencies that affect the architecture**
   - The important non-Django dependencies are **OpenCV**, **pyzbar/ZBar**, **Pillow**, and **ReportLab**.
   - These libraries define the main processing boundaries: image handling, QR decoding, and PDF generation.
   - The repo does not appear to depend on external SaaS services; its threat analysis is implemented locally through heuristics.

13. **How to draw the main flow**
   - The central architecture diagram should show: **browser → Django views/templates → validation/decoder/analyzer modules → ORM/database → history/dashboard/report generator → PDF/media storage**.
   - Everything else is supporting structure around that pipeline: auth, styling, settings, and page composition.

Main entry points: [`backend/scanner/views.py`](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/views.py) (App views), [`backend/scanner/models.py`](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/models.py) (Scan models), [`backend/scanner/detector.py`](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/detector.py) (Threat detector), [`backend/templates`](https://github.com/hemanthkbasali/qrshield/tree/main/backend/templates) (Templates)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_backend["Backend"]
  node_node_urls["URL routing<br/>Django routes<br/>[urls.py]"]
  node_node_views["App views<br/>Django views<br/>[views.py]"]
  node_node_forms["Upload forms<br/>validation form<br/>[forms.py]"]
  node_node_validators["Validators<br/>input checks<br/>[validators.py]"]
  node_node_middleware["Middleware<br/>[middleware.py]"]
  node_node_reader["QR reader<br/>decode service<br/>[qr_reader.py]"]
  node_node_detector["Threat detector<br/>heuristic analysis<br/>[detector.py]"]
  node_node_brand["Brand detector<br/>lure heuristics<br/>[brand_detector.py]"]
  node_node_utils["Scanner utils<br/>shared helpers<br/>[utils.py]"]
  node_node_models[("Scan models<br/>ORM models<br/>[models.py]")]
  node_node_reportgen["Report generator<br/>PDF export"]
  node_node_settings["Django settings<br/>runtime config<br/>[settings.py]"]
end

subgraph group_group_ui["Presentation"]
  node_node_templates["Templates"]
  node_node_components["UI components<br/>template partials"]
  node_node_static["Static assets<br/>css/js assets"]
end

subgraph group_group_storage["Storage"]
  node_node_media[("Media uploads<br/>file storage")]
  node_node_reports[("Report files<br/>pdf storage")]
end

subgraph group_group_frontend["Frontend build"]
  node_node_frontend["Tailwind build<br/>asset workspace"]
end

node_node_urls -->|"dispatches"| node_node_views
node_node_views -->|"renders"| node_node_templates
node_node_views -->|"accepts"| node_node_forms
node_node_views -->|"checks"| node_node_validators
node_node_views -.->|"passes through"| node_node_middleware
node_node_forms -.->|"uses"| node_node_utils
node_node_validators -.->|"uses"| node_node_utils
node_node_utils -->|"decodes"| node_node_reader
node_node_reader -->|"analyzes"| node_node_detector
node_node_detector -->|"consults"| node_node_brand
node_node_detector -->|"stores"| node_node_models
node_node_views -->|"queries"| node_node_models
node_node_reportgen -->|"reads"| node_node_models
node_node_reportgen -->|"writes"| node_node_reports
node_node_views -->|"exports"| node_node_reportgen
node_node_views -->|"uploads"| node_node_media
node_node_templates -->|"composes"| node_node_components
node_node_templates -.->|"styles"| node_node_static
node_node_frontend -.->|"builds"| node_node_static
node_node_settings -->|"configures"| node_node_models

click node_node_urls "https://github.com/hemanthkbasali/qrshield/blob/main/backend/qrshield/urls.py"
click node_node_views "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/views.py"
click node_node_forms "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/forms.py"
click node_node_validators "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/validators.py"
click node_node_middleware "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/middleware.py"
click node_node_reader "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/qr_reader.py"
click node_node_detector "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/detector.py"
click node_node_brand "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/brand_detector.py"
click node_node_utils "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/utils.py"
click node_node_models "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/models.py"
click node_node_reportgen "https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/report_generator.py"
click node_node_templates "https://github.com/hemanthkbasali/qrshield/tree/main/backend/templates"
click node_node_components "https://github.com/hemanthkbasali/qrshield/tree/main/backend/templates/components"
click node_node_static "https://github.com/hemanthkbasali/qrshield/tree/main/backend/static/scanner"
click node_node_media "https://github.com/hemanthkbasali/qrshield/tree/main/backend/media"
click node_node_reports "https://github.com/hemanthkbasali/qrshield/tree/main/backend/reports"
click node_node_settings "https://github.com/hemanthkbasali/qrshield/blob/main/backend/qrshield/settings.py"
click node_node_frontend "https://github.com/hemanthkbasali/qrshield/tree/main/frontend"

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_node_urls,node_node_views,node_node_forms,node_node_validators,node_node_middleware,node_node_reader,node_node_detector,node_node_brand,node_node_utils,node_node_models,node_node_reportgen,node_node_settings toneBlue
class node_node_templates,node_node_components,node_node_static toneAmber
class node_node_media,node_node_reports toneMint
class node_node_frontend toneRose
```

## Components

### Backend

Django project and scanner app

- [URL routing](https://github.com/hemanthkbasali/qrshield/blob/main/backend/qrshield/urls.py): Django routes · Project and app URL dispatch · `backend/qrshield/urls.py`
- [App views](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/views.py): Django views · Page handlers and scan orchestration · `backend/scanner/views.py`
- [Upload forms](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/forms.py): validation form · Scanner input handling and request shaping · `backend/scanner/forms.py`
- [Validators](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/validators.py): input checks · QR and payload validation rules · `backend/scanner/validators.py`
- [Middleware](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/middleware.py): request middleware · Thin request/session boundary helpers · `backend/scanner/middleware.py`
- [QR reader](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/qr_reader.py): decode service · Image extraction and fallback decoding · `backend/scanner/qr_reader.py`
- [Threat detector](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/detector.py): heuristic analysis · Risk scoring and phishing checks · `backend/scanner/detector.py`
- [Brand detector](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/brand_detector.py): lure heuristics · Brand and impersonation signals · `backend/scanner/brand_detector.py`
- [Scanner utils](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/utils.py): shared helpers · Common scan pipeline helpers · `backend/scanner/utils.py`
- [Scan models](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/models.py): ORM models · Persisted scan records and metadata · `backend/scanner/models.py`
- [Report generator](https://github.com/hemanthkbasali/qrshield/blob/main/backend/scanner/report_generator.py): PDF export · ReportLab-based security report creation · `backend/scanner/report_generator.py`
- [Django settings](https://github.com/hemanthkbasali/qrshield/blob/main/backend/qrshield/settings.py): runtime config · Environment-driven database and deployment settings · `backend/qrshield/settings.py`

### Presentation

Templates and static assets

- [Templates](https://github.com/hemanthkbasali/qrshield/tree/main/backend/templates): Django templates · Landing, auth, scanner, dashboard and report pages · `backend/templates`
- [UI components](https://github.com/hemanthkbasali/qrshield/tree/main/backend/templates/components): template partials · Sidebar, shell, and risk badge components · `backend/templates/components`
- [Static assets](https://github.com/hemanthkbasali/qrshield/tree/main/backend/static/scanner): css/js assets · Browser-side styling and interactions · `backend/static/scanner`

### Storage

Runtime and generated artifacts

- [Media uploads](https://github.com/hemanthkbasali/qrshield/tree/main/backend/media): file storage · Uploaded QR images · `backend/media`
- [Report files](https://github.com/hemanthkbasali/qrshield/tree/main/backend/reports): pdf storage · Generated PDF reports · `backend/reports`

### Frontend build

Styling and asset build workspace

- [Tailwind build](https://github.com/hemanthkbasali/qrshield/tree/main/frontend): asset workspace · Frontend styling configuration and input CSS · `frontend`

## Connections

- URL routing → App views: dispatches · Routes map HTTP requests to page and scan handlers
- App views → Templates: renders · Views return server-rendered pages
- App views → Upload forms: accepts · Scan submissions are shaped by forms
- App views → Validators: checks · Inputs are validated before decoding
- App views → Middleware: passes through · Request/session boundary helpers sit in front of views
- Upload forms → Scanner utils: uses · Form handling shares pipeline helpers
- Validators → Scanner utils: uses · Validation logic shares utility helpers
- Scanner utils → QR reader: decodes · Pipeline moves from upload to QR extraction
- QR reader → Threat detector: analyzes · Decoded payloads are scored for risk
- Threat detector → Brand detector: consults · Heuristic threat analysis includes brand/lure signals
- Threat detector → Scan models: stores · Scan results are persisted for history and analytics
- App views → Scan models: queries · Dashboard, history, and report pages read stored scans
- Report generator → Scan models: reads · Report generation uses persisted scan data
- Report generator → Report files: writes · PDF reports are saved to disk
- App views → Report generator: exports · Users can generate security reports from scan results
- App views → Media uploads: uploads · Uploaded QR images are stored separately from records
- Templates → UI components: composes · Pages reuse shared layout and badges
- Templates → Static assets: styles · Templates are backed by local CSS and JS
- Tailwind build → Static assets: builds · Tailwind workspace supports asset generation
- Django settings → Scan models: configures · Settings define database and runtime behavior
