# pavankumarreddy999/cyberpitch-fifa architecture

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

- Interactive diagram: https://gitdiagram.com/pavankumarreddy999/cyberpitch-fifa
- Repository: https://github.com/pavankumarreddy999/cyberpitch-fifa

## Overview

CyberPitch FIFA detects and monitors domains impersonating FIFA and World Cup brands. Users submit a domain through the dashboard; the backend validates and scans it, gathers threat-intelligence signals, scores and explains risk, and persists the result for history and dashboard views. Separate capabilities cover authentication, alerts, campaign analytics, recommendations, and scheduled domain discovery. README documentation describes concurrent OSINT collection, visual similarity, two-stage ML, and seven-day caching; unsampled implementation details are represented only where documented, so some links are dashed.

Main entry points: [`backend/app/services/aggregator_service.py`](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/aggregator_service.py) (Scan Aggregator), [`backend/app/api/scan.py`](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/api/scan.py) (Scan API), [`backend/app/api/auth.py`](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/api/auth.py) (Authentication API), [`src/services/api/dashboard.ts`](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/services/api/dashboard.ts) (Dashboard API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_dashboard["Threat Dashboard<br/>[page.tsx]"]
  node_scan_ui["Domain Scan UI<br/>[page.tsx]"]
  node_web_analyze["Analyze Proxy<br/>[route.ts]"]
  node_web_views["Threat Views<br/>[page.tsx]"]
  node_web_api["Dashboard API<br/>[dashboard.ts]"]
end

subgraph group_api["API and Accounts"]
  node_scan_api["Scan API<br/>[scan.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_auth_crypto["Password and JWT<br/>[auth.py]"]
end

subgraph group_intel["Intelligence and Scoring"]
  node_aggregator["Scan Aggregator"]
  node_whois["WHOIS and RDAP<br/>[whois_service.py]"]
  node_dns["DNS Intelligence<br/>[dns_service.py]"]
  node_ssl["Certificate Inspection<br/>[ssl_service.py]"]
  node_html["Page Analysis<br/>[html_service.py]"]
  node_threat["Blacklist Check<br/>[threat_service.py]"]
  node_asn["ASN Lookup<br/>[asn_service.py]"]
  node_visual["Visual Similarity<br/>[visual_service.py]"]
  node_ml["Risk Models<br/>[ml_service.py]"]
end

subgraph group_data["Persistence"]
  node_cache["Smart Cache<br/>[cache_service.py]"]
  node_history[("Scan History<br/>[scan_history.py]")]
  node_users[("User Records<br/>[user.py]")]
  node_db[("SQLite Access<br/>[database.py]")]
end

subgraph group_discovery["Domain Discovery"]
  node_scheduler["12-hour Scheduler<br/>[main.py]"]
  node_discovery_job["Domain Discovery"]
end

node_analyst(("Analyst"))

node_analyst -->|"submits domain"| node_scan_ui
node_scan_ui -.->|"requests analysis"| node_web_analyze
node_web_analyze -->|"forwards request"| node_scan_api
node_scan_api -->|"collects signals"| node_aggregator
node_aggregator -->|"queries"| node_whois
node_aggregator -->|"queries"| node_dns
node_aggregator -->|"queries"| node_ssl
node_aggregator -->|"analyzes pages"| node_html
node_aggregator -->|"checks blacklist"| node_threat
node_aggregator -->|"looks up ASN"| node_asn
node_aggregator -->|"checks similarity"| node_visual
node_scan_api -->|"scores features"| node_ml
node_scan_api -->|"stores scans"| node_history
node_scan_api -->|"uses sessions"| node_db
node_aggregator -->|"reads and writes"| node_cache
node_cache -.->|"persists cache"| node_db
node_dashboard -.->|"loads metrics"| node_web_api
node_web_views -.->|"loads threat data"| node_web_api
node_web_api -.->|"requests dashboard data"| node_scan_api
node_analyst -->|"signs in"| node_auth_api
node_auth_api -->|"hashes and tokens"| node_auth_crypto
node_auth_api -->|"reads and writes"| node_users
node_auth_api -->|"uses sessions"| node_db
node_scheduler -->|"schedules"| node_discovery_job

click node_dashboard "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/dashboard/page.tsx"
click node_scan_ui "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/dashboard/scan/page.tsx"
click node_web_analyze "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/api/analyze/route.ts"
click node_web_views "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/dashboard/alerts/page.tsx"
click node_web_api "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/services/api/dashboard.ts"
click node_scan_api "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/api/scan.py"
click node_auth_api "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/api/auth.py"
click node_auth_crypto "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/utils/auth.py"
click node_aggregator "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/aggregator_service.py"
click node_whois "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/whois_service.py"
click node_dns "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/dns_service.py"
click node_ssl "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/ssl_service.py"
click node_html "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/html_service.py"
click node_threat "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/threat_service.py"
click node_asn "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/asn_service.py"
click node_visual "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/visual_service.py"
click node_ml "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/ml_service.py"
click node_cache "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/cache_service.py"
click node_history "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/models/scan_history.py"
click node_users "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/models/user.py"
click node_db "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/database/database.py"
click node_scheduler "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/main.py"
click node_discovery_job "https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/scripts/domain_discovery.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_scan_ui,node_web_analyze,node_web_views,node_web_api toneBlue
class node_scan_api,node_auth_api,node_auth_crypto toneAmber
class node_aggregator,node_whois,node_dns,node_ssl,node_html,node_threat,node_asn,node_visual,node_ml toneMint
class node_cache,node_history,node_users,node_db toneRose
class node_scheduler,node_discovery_job,node_analyst toneIndigo
```

## Components

### Dashboard

- [Threat Dashboard](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Domain Scan UI](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/dashboard/scan/page.tsx): `src/app/dashboard/scan/page.tsx`
- [Analyze Proxy](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/api/analyze/route.ts): `src/app/api/analyze/route.ts`
- [Threat Views](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/app/dashboard/alerts/page.tsx): `src/app/dashboard/alerts/page.tsx`
- [Dashboard API](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/src/services/api/dashboard.ts): `src/services/api/dashboard.ts`

### API and Accounts

- [Scan API](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/api/scan.py): `backend/app/api/scan.py`
- [Authentication API](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Password and JWT](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/utils/auth.py): `backend/app/utils/auth.py`

### Intelligence and Scoring

- [Scan Aggregator](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/aggregator_service.py): `backend/app/services/aggregator_service.py`
- [WHOIS and RDAP](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/whois_service.py): `backend/app/services/whois_service.py`
- [DNS Intelligence](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/dns_service.py): `backend/app/services/dns_service.py`
- [Certificate Inspection](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/ssl_service.py): `backend/app/services/ssl_service.py`
- [Page Analysis](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/html_service.py): `backend/app/services/html_service.py`
- [Blacklist Check](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/threat_service.py): `backend/app/services/threat_service.py`
- [ASN Lookup](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/asn_service.py): `backend/app/services/asn_service.py`
- [Visual Similarity](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/visual_service.py): `backend/app/services/visual_service.py`
- [Risk Models](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/ml_service.py): `backend/app/services/ml_service.py`

### Persistence

- [Smart Cache](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/services/cache_service.py): `backend/app/services/cache_service.py`
- [Scan History](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/models/scan_history.py): `backend/app/models/scan_history.py`
- [User Records](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/models/user.py): `backend/app/models/user.py`
- [SQLite Access](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/database/database.py): `backend/app/database/database.py`

### Domain Discovery

- [12-hour Scheduler](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/app/main.py): `backend/app/main.py`
- [Domain Discovery](https://github.com/pavankumarreddy999/cyberpitch-fifa/blob/main/backend/scripts/domain_discovery.py): `backend/scripts/domain_discovery.py`

### Other components

- **Analyst**

## Connections

- Analyst → Domain Scan UI: submits domain
- Domain Scan UI → Analyze Proxy: requests analysis
- Analyze Proxy → Scan API: forwards request
- Scan API → Scan Aggregator: collects signals (evidence: `backend/app/api/scan.py`)
- Scan Aggregator → WHOIS and RDAP: queries (evidence: `backend/app/services/aggregator_service.py`)
- Scan Aggregator → DNS Intelligence: queries (evidence: `backend/app/services/aggregator_service.py`)
- Scan Aggregator → Certificate Inspection: queries (evidence: `backend/app/services/aggregator_service.py`)
- Scan Aggregator → Page Analysis: analyzes pages (evidence: `backend/app/services/aggregator_service.py`)
- Scan Aggregator → Blacklist Check: checks blacklist (evidence: `backend/app/services/aggregator_service.py`)
- Scan Aggregator → ASN Lookup: looks up ASN (evidence: `backend/app/services/aggregator_service.py`)
- Scan Aggregator → Visual Similarity: checks similarity (evidence: `backend/app/services/aggregator_service.py`)
- Scan API → Risk Models: scores features (evidence: `backend/app/api/scan.py`)
- Scan API → Scan History: stores scans (evidence: `backend/app/api/scan.py`)
- Scan API → SQLite Access: uses sessions (evidence: `backend/app/api/scan.py`)
- Scan Aggregator → Smart Cache: reads and writes (evidence: `backend/app/services/aggregator_service.py`)
- Smart Cache → SQLite Access: persists cache
- Threat Dashboard → Dashboard API: loads metrics
- Threat Views → Dashboard API: loads threat data
- Dashboard API → Scan API: requests dashboard data
- Analyst → Authentication API: signs in
- Authentication API → Password and JWT: hashes and tokens (evidence: `backend/app/api/auth.py`)
- Authentication API → User Records: reads and writes (evidence: `backend/app/api/auth.py`)
- Authentication API → SQLite Access: uses sessions (evidence: `backend/app/api/auth.py`)
- 12-hour Scheduler → Domain Discovery: schedules (evidence: `backend/app/main.py`)
