# mav01-code/dark-web-breach-monitor architecture

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

- Interactive diagram: https://gitdiagram.com/mav01-code/dark-web-breach-monitor
- Repository: https://github.com/mav01-code/dark-web-breach-monitor

## Overview

##### What this project is (type + purpose)
This is a **monolithic web application** that provides a **Dark Web / breach monitoring dashboard**:

- **Web UI**: server-rendered HTML templates (login/register/dashboard/etc.)
- **Backend/API**: **Flask** app serving routes like `/register`, `/login`, `/dashboard`, and breach-check logic
- **Data store**: a single relational DB (schema hinted by `DB.sql`)
- **External integration**: **Have I Been Pwned (HIBP)** API for credential breach checks (k-anonymity using first 5 SHA1 hex chars)
- **Real-time/recurring monitoring**: **Azure Functions** timer/cron that periodically scans stored credentials and writes monitoring logs, which are plotted as a line chart in the dashboard

##### What the file tree tells you to include (map files → architecture)
Top-level artifacts imply these components:

##### Flask application (core runtime)
- `app.py`
Likely the main Flask server: routes, session handling, DB access, rendering templates, calling HIBP.
- `templates/`
Server-rendered UI pages:
- `login.html`, `register.html` → auth UI
- `dashboard.html` → main view that includes credential check + monitoring plot + remediation
- `credential-storage.html`, `remediation.html` → sub-views or dedicated pages

##### Azure Functions (scheduled monitor)
- `function_app.py`
- `host.json`
- `AzuriteConfig`

##### Database
- `DB.sql`
- `register` (users)
- `credential` (hashed credentials)
- monitoring logs table (name unknown—derive from DB.sql; if absent, show “monitoring_logs (inferred)”)

##### Configuration / dependencies
- `requirements.txt` → Flask + DB driver + requests, etc.

Given the small repo, L2 + one L3 are usually the “most value.”

Use these as the canonical nodes:

##### Client / UI
- **User Browser**
- Renders HTML/CSS from Flask templates
- Sends HTTP requests for register/login/credential check

##### Backend (monolith)
- **Flask Web Server (app.py)**
- Auth: `/register`, `/login`
- Dashboard: `/dashboard`
- Credential check service (internal module/function)
- Remediation scoring service (internal module/function)
- DB access layer (inline in app or separate helpers—represent it anyway)

##### Data
- **Relational Database (“monitor DB”)**
- Tables: `register`, `credential`, `monitoring_logs` (confirm actual names from `DB.sql`)

##### External services
- **Have I Been Pwned API**
- Called by Flask during credential check
- Possibly also called by Azure Function during periodic checks

##### Scheduled monitoring
- **Azure Functions App (function_app.py)**
- Timer Trigger (every 5 minutes)
- Reads credential table
- Calls HIBP (or re-checks)
- Writes monitoring logs (DB and/or storage)

##### Optional but worth including (if supported by code/config)
- **Azure Storage (Blob/Table/Queue)**
- If `AzuriteConfig` is used for local emulation, show the production equivalent as the backing service.

##### Flask (Credential Check)
- SHA1 hash password
- Take first 5 hex chars
##### Flask
- compare remaining suffix
- decide breached/safe (+ breach count)
##### Flask → DB
- if email not in credential table: store hashed password
- store breach results / last_checked / etc. (whatever exists in schema)

##### Browser → Flask → DB: dashboard loads monitoring logs
6. **Flask → Browser**: line plot data (either embedded server-side or delivered to front-end JS)

##### Flask (Remediation Engine)
- Inputs: breach count, password age, MFA flag
- Outputs: risk score + risk level (low/medium/high)

##### Architectural patterns/design principles to highlight (explicit callouts)
- **Monolithic server**: Flask handles UI rendering + API endpoints + business logic.
- **Single DB**: central source of truth for users, credentials, and monitoring logs.
- **K-anonymity credential checking**: only first 5 SHA1 chars sent to HIBP (privacy-preserving).
- **Event/time-driven background processing**: Azure Function timer acts as a cron-like scheduler.
- **Separation of concerns inside monolith** (even if not separated into modules in code): show “Auth”, “Credential Check”, “Monitoring Log Retrieval”, “Remediation Scoring” as internal components.

##### External: HIBP API

- Browser ↔ Flask (HTTP)
- Flask ↔ DB (SQL)
- Flask → HIBP (HTTPS)
- Azure Function ↔ DB (SQL)
- Azure Function → HIBP (HTTPS)

- “/register”, “/login”, “/dashboard”
- “SHA1 prefix query (first 5 hex chars)”
- “Timer: every 5 min”

- **Auth Controller**: register/login/session
- **Dashboard Controller**: renders `dashboard.html`
- **Credential Check Service**: hashing + HIBP parsing + store credential
- **Remediation Scoring Service**: rule-based scoring
- **DB Access Layer**: queries/inserts (even if direct)
- **Template Renderer**: templates/*.html

Connect:
- Controllers call services
- Services use DB layer
- Credential check uses HIBP client

Inside “Azure Functions”:
- **Timer Trigger**
- **Credential Scanner** (reads credential table)
- **HIBP Client**
- **Monitoring Log Writer** (writes DB logs)

Consistently:

- **Clear labels**: use file-based references where possible: “Flask (app.py)”, “Azure Function (function_app.py)”
- HTTP/HTTPS
- SQL
- Rectangles: compute (Flask, Azure Function)
- Cloud: external services (HIBP)
- **Trust boundaries**:
- Public Internet boundary between Browser and backend
- External service boundary around HIBP
- **Data classification notes**:
- “Store hashed password (SHA1)” in DB
- “Never send full hash/password to HIBP; only 5-char prefix”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Trust boundaries & context
  %% =========================
  subgraph TB1["Public Internet / Client"]
    U["User"]:::external
    B["User Browser<br/>(HTML/CSS + cookies)"]:::client
    U -->|"uses"| B
  end

  subgraph TB2["Application Server (Monolith)"]
    F["Flask Web Server<br/>(server-rendered UI + routes)"]:::compute

    subgraph TB2A["Flask Components (in app.py)"]
      AC["Auth Controller<br/>/register, /login"]:::component
      DC["Dashboard Controller<br/>/dashboard"]:::component
      CCS["Credential Check Service<br/>(SHA1 + k-anonymity)"]:::component
      RSS["Remediation Scoring Service<br/>(risk level)"]:::component
      DAL["DB Access Layer<br/>(SQL queries/inserts)"]:::component
      TR["Template Renderer<br/>(Jinja2 templates)"]:::component
      HCL["HIBP Client<br/>(prefix query + suffix match)"]:::component
    end

    F -->|"dispatches"| AC
    F -->|"dispatches"| DC
    AC -->|"uses"| DAL
    DC -->|"uses"| CCS
    DC -->|"uses"| RSS
    DC -->|"uses"| DAL
    DC -->|"renders"| TR
    CCS -->|"uses"| HCL
    CCS -->|"uses"| DAL
  end

  subgraph TB3["Data Layer"]
    DB[("Relational Database<br/>(users + credentials + monitoring logs)")]:::database
  end

  subgraph TB4["Azure Cloud Boundary"]
    AF["Azure Functions App<br/>(timer-triggered monitoring)"]:::compute

    subgraph TB4A["Azure Function Components (in function_app.py)"]
      TT["Timer Trigger<br/>(every 5 min)"]:::component
      CS["Credential Scanner<br/>(read credential table)"]:::component
      HCL2["HIBP Client<br/>(re-check by prefix)"]:::component
      MLW["Monitoring Log Writer<br/>(timestamped metrics)"]:::component
    end

    TT -->|"invokes"| CS
    CS -->|"calls"| HCL2
    CS -->|"writes via"| MLW

    AS[("Azure Storage (optional / inferred)<br/>(Azurite in local dev)")]:::database
  end

  subgraph TB5["External Services"]
    HIBP["Have I Been Pwned API<br/>(k-anonymity range endpoint)"]:::external
  end

  %% =========================
  %% Main interactions (L2)
  %% =========================
  B <-->|"HTTP(S): /register,/login,/dashboard"| F
  DAL <-->|"SQL"| DB

  HCL -->|"HTTPS: SHA1_prefix_query (first 5 hex chars)"| HIBP
  HCL2 -->|"HTTPS: SHA1_prefix_query (first 5 hex chars)"| HIBP

  AF <-->|"SQL: read credentials / write monitoring logs"| DB

  %% Optional storage bindings for Functions runtime
  AF -.->|"bindings (optional/inferred)"| AS

  %% =========================
  %% Key data-handling notes
  %% =========================
  N1["Privacy note:<br/>Only 5-char SHA1 prefix sent to HIBP; never full password/hash"]:::note
  N2["Data note:<br/>Store hashed credentials; monitoring logs plotted on dashboard"]:::note
  CCS -.->|"enforces"| N1
  DC -.->|"uses logs for plot"| N2
  MLW -.->|"writes logs"| N2

  %% =========================
  %% Template pages (repo artifacts)
  %% =========================
  subgraph TB6["Server-rendered Templates (templates/)"]
    TLogin["login.html"]:::template
    TRegister["register.html"]:::template
    TDash["dashboard.html"]:::template
    TCred["credential-storage.html"]:::template
    TRem["remediation.html"]:::template
  end

  TR -->|"renders"| TLogin
  TR -->|"renders"| TRegister
  TR -->|"renders"| TDash
  TR -->|"renders"| TCred
  TR -->|"renders"| TRem

  %% =========================
  %% Repo configuration artifacts
  %% =========================
  subgraph TB7["Configuration / Dependencies"]
    REQ["Python Dependencies<br/>(Flask, DB driver, HTTP client)"]:::config
    HOST["Azure Functions Host Config"]:::config
    DBS["DB Schema Definition"]:::config
    AZC["Azurite Config<br/>(local emulator)"]:::config
  end

  REQ -.->|"used by"| F
  REQ -.->|"used by"| AF
  HOST -.->|"configures"| AF
  DBS -.->|"defines schema for"| DB
  AZC -.->|"emulates"| AS

  %% =========================
  %% Click events (component_mapping)
  %% =========================
  click F "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/app.py"
  click TR "https://github.com/mav01-code/dark-web-breach-monitor/tree/main/templates/"
  click TLogin "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/templates/login.html"
  click TRegister "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/templates/register.html"
  click TDash "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/templates/dashboard.html"
  click TCred "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/templates/credential-storage.html"
  click TRem "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/templates/remediation.html"
  click DBS "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/DB.sql"
  click AF "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/function_app.py"
  click HOST "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/host.json"
  click AZC "https://github.com/mav01-code/dark-web-breach-monitor/tree/main/AzuriteConfig"
  click REQ "https://github.com/mav01-code/dark-web-breach-monitor/blob/main/requirements.txt"

  %% =========================
  %% Styles (color required)
  %% =========================
  classDef client fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1b3a;
  classDef compute fill:#dcfce7,stroke:#166534,stroke-width:1.5px,color:#052e16;
  classDef component fill:#ecfdf5,stroke:#16a34a,stroke-width:1px,color:#052e16;
  classDef database fill:#fff7ed,stroke:#9a3412,stroke-width:1.5px,color:#431407;
  classDef external fill:#f3f4f6,stroke:#374151,stroke-width:1.5px,color:#111827;
  classDef template fill:#fdf2f8,stroke:#9d174d,stroke-width:1px,color:#500724;
  classDef config fill:#fefce8,stroke:#a16207,stroke-width:1px,color:#3f2a05;
  classDef note fill:#ffffff,stroke:#6b7280,stroke-dasharray:4 3,color:#111827;
```
