# shafinnigamana/cyberkawach_hackathon_unoffical architecture

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

- Interactive diagram: https://gitdiagram.com/shafinnigamana/cyberkawach_hackathon_unoffical
- Repository: https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical

## Overview

Cyber Fraud Guardian is a citizen-facing cyber-fraud triage and recovery platform. A citizen submits a message, URL, or other suspicious content through the dashboard or browser extension; the backend ingests it, gathers rule, statistical, OSINT, and threat-feed evidence, fuses risk, explains findings, advises according to the citizen’s interaction state, and can persist incidents for later review. The README documents these stages and capabilities; the sampled pipeline excerpt is partial, so some internal wiring is shown only where documented.

Main entry points: [`backend/services/pipeline_service.py`](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/pipeline_service.py) (Analysis pipeline), [`backend/main.py`](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/main.py) (FastAPI application), [`backend/routes/analysis.py`](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/analysis.py) (Analysis endpoint), [`backend/modules/response.py`](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/response.py) (Adaptive response)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Citizen entry points"]
  node_dashboard["Trust dashboard<br/>[App.jsx]"]
  node_voice["Voice input<br/>[useVoiceInput.js]"]
  node_extension["Browser extension<br/>[background.js]"]
end

subgraph group_api["API and accounts"]
  node_app["FastAPI application<br/>[main.py]"]
  node_analysis["Analysis endpoint<br/>[analysis.py]"]
  node_auth["Citizen accounts<br/>[auth.py]"]
  node_incidents["Incident review<br/>[incidents.py]"]
end

subgraph group_triage["Triage and evidence"]
  node_contract["Evidence contract<br/>[evidence.py]"]
  node_pipeline["Analysis pipeline"]
  node_ingestion["Ingestion and IOC extraction<br/>[ingestion.py]"]
  node_rules["Typed and rule triage<br/>[laya.py]"]
  node_classifier["ML classification<br/>[ml_classifier.py]"]
  node_osint["Domain and website OSINT<br/>[domain_intel.py]"]
  node_sender["Sender analysis<br/>[sender_analyzer.py]"]
  node_threatintel["Threat intelligence"]
  node_fusion["Risk fusion<br/>[fusion.py]"]
end

subgraph group_advisory["Advisory and persistence"]
  node_explanation["Grounded explanation"]
  node_response["Adaptive response<br/>[response.py]"]
  node_store[("Incident graph store")]
  node_translation["Translation"]
end

node_citizen(("Citizen"))
node_externalfeeds["Threat-feed services"]
node_gemini["Gemini service"]

node_citizen -->|"submits content"| node_dashboard
node_citizen -->|"speaks to"| node_voice
node_citizen -.->|"checks content"| node_extension
node_dashboard -->|"sends requests"| node_app
node_extension -.->|"submits analysis"| node_app
node_app -->|"routes requests"| node_analysis
node_app -->|"registers router"| node_auth
node_app -->|"registers router"| node_incidents
node_analysis -->|"runs analysis"| node_pipeline
node_pipeline -->|"builds evidence"| node_contract
node_pipeline -->|"invokes ingestion"| node_ingestion
node_ingestion -->|"populates evidence"| node_contract
node_pipeline -->|"runs triage"| node_rules
node_pipeline -->|"scores message"| node_classifier
node_pipeline -->|"enriches indicators"| node_osint
node_pipeline -->|"analyzes sender"| node_sender
node_pipeline -->|"queries feeds"| node_threatintel
node_threatintel -->|"checks indicators"| node_externalfeeds
node_pipeline -->|"fuses signals"| node_fusion
node_fusion -->|"grounds findings"| node_explanation
node_explanation -.->|"requests explanation"| node_gemini
node_explanation -->|"provides findings"| node_response
node_response -->|"persists incident"| node_store
node_analysis -->|"returns advisory"| node_response
node_analysis -->|"translates content"| node_translation
node_auth -->|"persists accounts"| node_store
node_incidents -->|"retrieves history"| node_store
node_response -->|"shows guidance"| node_dashboard

click node_dashboard "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/frontend/src/App.jsx"
click node_voice "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/frontend/src/hooks/useVoiceInput.js"
click node_extension "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/browser_extension/background.js"
click node_app "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/main.py"
click node_analysis "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/analysis.py"
click node_auth "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/auth.py"
click node_incidents "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/incidents.py"
click node_contract "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/models/evidence.py"
click node_pipeline "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/pipeline_service.py"
click node_ingestion "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/ingestion.py"
click node_rules "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/laya.py"
click node_classifier "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/ml_classifier.py"
click node_osint "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/domain_intel.py"
click node_sender "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/sender_analyzer.py"
click node_threatintel "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/threat_intel_providers.py"
click node_fusion "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/fusion.py"
click node_explanation "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/fallback_explanation.py"
click node_response "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/response.py"
click node_store "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/neo4j_repository.py"
click node_translation "https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/google_translator.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_voice,node_extension toneBlue
class node_app,node_analysis,node_auth,node_incidents toneAmber
class node_contract,node_pipeline,node_ingestion,node_rules,node_classifier,node_osint,node_sender,node_threatintel,node_fusion toneMint
class node_explanation,node_response,node_store,node_translation toneRose
class node_citizen,node_externalfeeds,node_gemini toneIndigo
```

## Components

### Citizen entry points

- [Trust dashboard](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Voice input](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/frontend/src/hooks/useVoiceInput.js): `frontend/src/hooks/useVoiceInput.js`
- [Browser extension](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/browser_extension/background.js): `browser_extension/background.js`

### API and accounts

- [FastAPI application](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/main.py): `backend/main.py`
- [Analysis endpoint](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/analysis.py): `backend/routes/analysis.py`
- [Citizen accounts](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Incident review](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/routes/incidents.py): `backend/routes/incidents.py`

### Triage and evidence

- [Evidence contract](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/models/evidence.py): `backend/models/evidence.py`
- [Analysis pipeline](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/pipeline_service.py): `backend/services/pipeline_service.py`
- [Ingestion and IOC extraction](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/ingestion.py): `backend/modules/ingestion.py`
- [Typed and rule triage](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/laya.py): `backend/modules/laya.py`
- [ML classification](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/ml_classifier.py): `backend/modules/ml_classifier.py`
- [Domain and website OSINT](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/domain_intel.py): `backend/services/domain_intel.py`
- [Sender analysis](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/sender_analyzer.py): `backend/services/sender_analyzer.py`
- [Threat intelligence](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/threat_intel_providers.py): `backend/services/threat_intel_providers.py`
- [Risk fusion](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/fusion.py): `backend/modules/fusion.py`

### Advisory and persistence

- [Grounded explanation](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/fallback_explanation.py): `backend/modules/fallback_explanation.py`
- [Adaptive response](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/modules/response.py): `backend/modules/response.py`
- [Incident graph store](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/neo4j_repository.py): `backend/services/neo4j_repository.py`
- [Translation](https://github.com/shafinnigamana/cyberkawach_hackathon_unoffical/blob/main/backend/services/google_translator.py): `backend/services/google_translator.py`

### Other components

- **Citizen**
- **Threat-feed services**
- **Gemini service**

## Connections

- Citizen → Trust dashboard: submits content
- Citizen → Voice input: speaks to
- Citizen → Browser extension: checks content
- Trust dashboard → FastAPI application: sends requests
- Browser extension → FastAPI application: submits analysis
- FastAPI application → Analysis endpoint: routes requests (evidence: `backend/main.py`)
- FastAPI application → Citizen accounts: registers router (evidence: `backend/main.py`)
- FastAPI application → Incident review: registers router (evidence: `backend/main.py`)
- Analysis endpoint → Analysis pipeline: runs analysis
- Analysis pipeline → Evidence contract: builds evidence (evidence: `backend/services/pipeline_service.py`)
- Analysis pipeline → Ingestion and IOC extraction: invokes ingestion (evidence: `backend/services/pipeline_service.py`)
- Ingestion and IOC extraction → Evidence contract: populates evidence (evidence: `backend/modules/ingestion.py`)
- Analysis pipeline → Typed and rule triage: runs triage (evidence: `backend/services/pipeline_service.py`)
- Analysis pipeline → ML classification: scores message (evidence: `backend/services/pipeline_service.py`)
- Analysis pipeline → Domain and website OSINT: enriches indicators (evidence: `backend/services/pipeline_service.py`)
- Analysis pipeline → Sender analysis: analyzes sender (evidence: `backend/services/pipeline_service.py`)
- Analysis pipeline → Threat intelligence: queries feeds (evidence: `backend/services/pipeline_service.py`)
- Threat intelligence → Threat-feed services: checks indicators
- Analysis pipeline → Risk fusion: fuses signals (evidence: `backend/services/pipeline_service.py`)
- Risk fusion → Grounded explanation: grounds findings
- Grounded explanation → Gemini service: requests explanation
- Grounded explanation → Adaptive response: provides findings
- Adaptive response → Incident graph store: persists incident
- Analysis endpoint → Adaptive response: returns advisory
- Analysis endpoint → Translation: translates content
- Citizen accounts → Incident graph store: persists accounts (evidence: `backend/routes/auth.py`)
- Incident review → Incident graph store: retrieves history (evidence: `backend/routes/incidents.py`)
- Adaptive response → Trust dashboard: shows guidance