How hemanthkbasali/qrshield works
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: views.py App views · models.py Scan models · detector.py Threat detector · templates Templates
Components 18
Backend
Django project and scanner app
- URL routing · Project and app URL dispatch
backend/qrshield/urls.py - App views · Page handlers and scan orchestration
backend/scanner/views.py - Upload forms · Scanner input handling and request shaping
backend/scanner/forms.py - Validators · QR and payload validation rules
backend/scanner/validators.py - Middleware · Thin request/session boundary helpers
backend/scanner/middleware.py - QR reader · Image extraction and fallback decoding
backend/scanner/qr_reader.py - Threat detector · Risk scoring and phishing checks
backend/scanner/detector.py - Brand detector · Brand and impersonation signals
backend/scanner/brand_detector.py - Scanner utils · Common scan pipeline helpers
backend/scanner/utils.py - Scan models · Persisted scan records and metadata
backend/scanner/models.py - Report generator · ReportLab-based security report creation
backend/scanner/report_generator.py - Django settings · Environment-driven database and deployment settings
backend/qrshield/settings.py
Presentation
Templates and static assets
- Templates · Landing, auth, scanner, dashboard and report pages
backend/templates - UI components · Sidebar, shell, and risk badge components
backend/templates/components - Static assets · Browser-side styling and interactions
backend/static/scanner
Storage
Runtime and generated artifacts
- Media uploads · Uploaded QR images
backend/media - Report files · Generated PDF reports
backend/reports
Frontend build
Styling and asset build workspace
- Tailwind build · Frontend styling configuration and input CSS
frontend
Connections 20
- 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