# mrvarunkumar/numbershield architecture

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

- Interactive diagram: https://gitdiagram.com/mrvarunkumar/numbershield
- Repository: https://github.com/mrvarunkumar/numbershield

## Overview

NumberShield is a privacy command center for tracking services, consent, exposure risk, and draft privacy requests, with optional exposure discovery integrations. The principal workflow is a user viewing and managing the dashboard: the browser loads data from the FastAPI backend, which reads or updates the database layer. Discovery is a separate opt-in branch, including Gmail registration evidence and breach checks. The README contains no architectural detail, so capabilities and connections here rely on the shown source excerpts; public-web implementation details are not sampled.

Main entry points: [`main.py`](https://github.com/mrvarunkumar/numbershield/blob/main/main.py) (API Routes), [`main/frontend/app.js`](https://github.com/mrvarunkumar/numbershield/blob/main/main/frontend/app.js) (Dashboard UI), [`db.py`](https://github.com/mrvarunkumar/numbershield/blob/main/db.py) (Database Layer), [`main`](https://github.com/mrvarunkumar/numbershield/tree/main/main) (Public Web Search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Dashboard"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
end

subgraph group_api["Backend API"]
  node_api_routes["API Routes<br/>[main.py]"]
end

subgraph group_privacy["Privacy Management"]
  node_services["Service Inventory<br/>[main.py]"]
  node_consents["Consent Tracking<br/>[main.py]"]
  node_exposure_risk["Exposure Risk<br/>[main.py]"]
  node_privacy_requests["Privacy Requests<br/>[main.py]"]
  node_audit["Audit Trail<br/>[main.py]"]
end

subgraph group_discovery["Exposure Discovery"]
  node_discovery["Discovery Runner<br/>[main.py]"]
  node_gmail["Gmail Evidence<br/>[main.py]"]
  node_public_web["Public Web Search"]
  node_breach_check["Breach Checks<br/>[main.py]"]
end

subgraph group_storage["Persistence"]
  node_db_layer["Database Layer<br/>[db.py]"]
  node_database[("Application Data<br/>[db.py]")]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_dashboard -->|"requests data"| node_api_routes
node_api_routes -->|"routes service APIs"| node_services
node_api_routes -->|"routes consent APIs"| node_consents
node_api_routes -->|"routes exposure APIs"| node_exposure_risk
node_api_routes -->|"routes request APIs"| node_privacy_requests
node_api_routes -->|"routes audit APIs"| node_audit
node_api_routes -->|"routes discovery APIs"| node_discovery
node_api_routes -->|"calls"| node_db_layer
node_discovery -->|"queries"| node_gmail
node_discovery -->|"checks"| node_breach_check
node_discovery -.->|"searches"| node_public_web
node_db_layer -->|"reads and writes"| node_database

click node_dashboard "https://github.com/mrvarunkumar/numbershield/blob/main/main/frontend/app.js"
click node_api_routes "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_services "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_consents "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_exposure_risk "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_privacy_requests "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_audit "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_discovery "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_gmail "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_public_web "https://github.com/mrvarunkumar/numbershield/tree/main/main"
click node_breach_check "https://github.com/mrvarunkumar/numbershield/blob/main/main.py"
click node_db_layer "https://github.com/mrvarunkumar/numbershield/blob/main/db.py"
click node_database "https://github.com/mrvarunkumar/numbershield/blob/main/db.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_dashboard,node_user toneBlue
class node_api_routes toneAmber
class node_services,node_consents,node_exposure_risk,node_privacy_requests,node_audit toneMint
class node_discovery,node_gmail,node_public_web,node_breach_check toneRose
class node_db_layer,node_database toneIndigo
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/mrvarunkumar/numbershield/blob/main/main/frontend/app.js): `main/frontend/app.js`

### Backend API

- [API Routes](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`

### Privacy Management

- [Service Inventory](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`
- [Consent Tracking](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`
- [Exposure Risk](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`
- [Privacy Requests](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`
- [Audit Trail](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`

### Exposure Discovery

- [Discovery Runner](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`
- [Gmail Evidence](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`
- [Public Web Search](https://github.com/mrvarunkumar/numbershield/tree/main/main): `main`
- [Breach Checks](https://github.com/mrvarunkumar/numbershield/blob/main/main.py): `main.py`

### Persistence

- [Database Layer](https://github.com/mrvarunkumar/numbershield/blob/main/db.py): `db.py`
- [Application Data](https://github.com/mrvarunkumar/numbershield/blob/main/db.py): `db.py`

### Other components

- **User**

## Connections

- User → Dashboard UI: uses (evidence: `main/frontend/app.js`)
- Dashboard UI → API Routes: requests data (evidence: `main/frontend/app.js`)
- API Routes → Service Inventory: routes service APIs (evidence: `main.py`)
- API Routes → Consent Tracking: routes consent APIs (evidence: `main.py`)
- API Routes → Exposure Risk: routes exposure APIs (evidence: `main.py`)
- API Routes → Privacy Requests: routes request APIs (evidence: `main.py`)
- API Routes → Audit Trail: routes audit APIs (evidence: `main.py`)
- API Routes → Discovery Runner: routes discovery APIs (evidence: `main.py`)
- API Routes → Database Layer: calls (evidence: `main.py`)
- Discovery Runner → Gmail Evidence: queries (evidence: `main.py`)
- Discovery Runner → Breach Checks: checks (evidence: `main.py`)
- Discovery Runner → Public Web Search: searches
- Database Layer → Application Data: reads and writes (evidence: `db.py`)