# preethamacharya86/counterpulse architecture

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

- Interactive diagram: https://gitdiagram.com/preethamacharya86/counterpulse
- Repository: https://github.com/preethamacharya86/counterpulse

## Overview

CounterPulse is an evidence-first cyber-fraud incident intake and case-management application. A user creates or selects an incident case, submits files, text, chats, or suspicious URLs, and the backend validates and stores evidence before normalizing it for review. The visible interface exposes case selection and evidence intake; the domain models and output schemas also represent incident reconstruction, indicators, compromise assessments, timelines, and response packages. Those latter capabilities are represented as data structures, not as an asserted processing pipeline: the supplied excerpts do not show their runtime orchestration.

Main entry points: [`backend/app/services/evidence_service.py`](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence_service.py) (Evidence Service), [`backend/app/models/case.py`](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/case.py) (Case Record), [`backend/app/api/v1/evidence.py`](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/v1/evidence.py) (Evidence Endpoints), [`frontend/src/App.tsx`](https://github.com/preethamacharya86/counterpulse/blob/main/frontend/src/App.tsx) (Case Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Casework UI"]
  node_app["Case Dashboard<br/>[App.tsx]"]
  node_uploader["Evidence Uploader"]
end

subgraph group_api["HTTP API"]
  node_cases_api["Case Endpoints<br/>[cases.py]"]
  node_evidence_api["Evidence Endpoints<br/>[evidence.py]"]
  node_router["API Router<br/>[router.py]"]
end

subgraph group_intake["Evidence Intake"]
  node_service["Evidence Service"]
  node_security["Upload Safety<br/>[security.py]"]
end

subgraph group_processing["Normalization"]
  node_factory["Processor Factory<br/>[factory.py]"]
  node_base["Normalized Evidence<br/>[base.py]"]
  node_chat["Chat Processor<br/>[chat_processor.py]"]
  node_modality_processors["Other Processors"]
  node_live["Live Chat Processor<br/>[live_processor.py]"]
end

subgraph group_records["Incident Records"]
  node_case_model["Case Record<br/>[case.py]"]
  node_evidence_model["Evidence Record<br/>[evidence.py]"]
  node_analysis_models["Analysis Records<br/>[indicator.py]"]
  node_timeline_model["Timeline Record<br/>[timeline.py]"]
  node_compromise_model["Compromise Record<br/>[compromise.py]"]
  node_report_model["Report Record<br/>[report.py]"]
  node_output_schemas["Analysis Schemas<br/>[ai_output.py]"]
  node_db[("SQL Database<br/>[database.py]")]
  node_files[("Evidence Files")]
end

node_user(("Investigator"))

node_user -->|"uses"| node_app
node_app -->|"requests cases"| node_cases_api
node_app -->|"selects evidence"| node_uploader
node_uploader -->|"submits evidence"| node_evidence_api
node_router -->|"dispatches"| node_cases_api
node_router -->|"dispatches"| node_evidence_api
node_evidence_api -->|"ingests and processes"| node_service
node_cases_api -->|"queries cases"| node_db
node_evidence_api -->|"queries records"| node_db
node_service -->|"validates uploads"| node_security
node_service -->|"selects processor"| node_factory
node_service -->|"processes live chunks"| node_live
node_service -->|"reads and writes"| node_db
node_service -->|"stores uploads"| node_files
node_factory -->|"creates processor"| node_chat
node_factory -->|"creates processor"| node_modality_processors
node_chat -->|"returns normalized data"| node_base
node_modality_processors -->|"returns normalized data"| node_base
node_live -->|"returns normalized data"| node_base
node_case_model -->|"associates evidence"| node_evidence_model
node_case_model -->|"relates indicators"| node_analysis_models
node_case_model -->|"relates events"| node_timeline_model
node_case_model -->|"relates assessments"| node_compromise_model
node_case_model -->|"relates reports"| node_report_model

click node_app "https://github.com/preethamacharya86/counterpulse/blob/main/frontend/src/App.tsx"
click node_uploader "https://github.com/preethamacharya86/counterpulse/blob/main/frontend/src/components/EvidenceUploader.tsx"
click node_cases_api "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/v1/cases.py"
click node_evidence_api "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/v1/evidence.py"
click node_router "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/router.py"
click node_service "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence_service.py"
click node_security "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/core/security.py"
click node_factory "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/factory.py"
click node_base "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/base.py"
click node_chat "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/chat_processor.py"
click node_modality_processors "https://github.com/preethamacharya86/counterpulse/tree/main/backend/app/services/evidence"
click node_live "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/live_processor.py"
click node_case_model "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/case.py"
click node_evidence_model "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/evidence.py"
click node_analysis_models "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/indicator.py"
click node_timeline_model "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/timeline.py"
click node_compromise_model "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/compromise.py"
click node_report_model "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/report.py"
click node_output_schemas "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/schemas/ai_output.py"
click node_db "https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/core/database.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_app,node_uploader toneBlue
class node_cases_api,node_evidence_api,node_router toneAmber
class node_service,node_security toneMint
class node_factory,node_base,node_chat,node_modality_processors,node_live toneRose
class node_case_model,node_evidence_model,node_analysis_models,node_timeline_model,node_compromise_model,node_report_model,node_output_schemas,node_db,node_files,node_user toneIndigo
```

## Components

### Casework UI

- [Case Dashboard](https://github.com/preethamacharya86/counterpulse/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Evidence Uploader](https://github.com/preethamacharya86/counterpulse/blob/main/frontend/src/components/EvidenceUploader.tsx): `frontend/src/components/EvidenceUploader.tsx`

### HTTP API

- [Case Endpoints](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/v1/cases.py): `backend/app/api/v1/cases.py`
- [Evidence Endpoints](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/v1/evidence.py): `backend/app/api/v1/evidence.py`
- [API Router](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/api/router.py): `backend/app/api/router.py`

### Evidence Intake

- [Evidence Service](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence_service.py): `backend/app/services/evidence_service.py`
- [Upload Safety](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Normalization

- [Processor Factory](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/factory.py): `backend/app/services/evidence/factory.py`
- [Normalized Evidence](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/base.py): `backend/app/services/evidence/base.py`
- [Chat Processor](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/chat_processor.py): `backend/app/services/evidence/chat_processor.py`
- [Other Processors](https://github.com/preethamacharya86/counterpulse/tree/main/backend/app/services/evidence): `backend/app/services/evidence`
- [Live Chat Processor](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/services/evidence/live_processor.py): `backend/app/services/evidence/live_processor.py`

### Incident Records

- [Case Record](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/case.py): `backend/app/models/case.py`
- [Evidence Record](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/evidence.py): `backend/app/models/evidence.py`
- [Analysis Records](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/indicator.py): `backend/app/models/indicator.py`
- [Timeline Record](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/timeline.py): `backend/app/models/timeline.py`
- [Compromise Record](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/compromise.py): `backend/app/models/compromise.py`
- [Report Record](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/models/report.py): `backend/app/models/report.py`
- [Analysis Schemas](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/schemas/ai_output.py): `backend/app/schemas/ai_output.py`
- [SQL Database](https://github.com/preethamacharya86/counterpulse/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- **Evidence Files**

### Other components

- **Investigator**

## Connections

- Investigator → Case Dashboard: uses
- Case Dashboard → Case Endpoints: requests cases
- Case Dashboard → Evidence Uploader: selects evidence
- Evidence Uploader → Evidence Endpoints: submits evidence
- API Router → Case Endpoints: dispatches
- API Router → Evidence Endpoints: dispatches
- Evidence Endpoints → Evidence Service: ingests and processes
- Case Endpoints → SQL Database: queries cases
- Evidence Endpoints → SQL Database: queries records
- Evidence Service → Upload Safety: validates uploads
- Evidence Service → Processor Factory: selects processor
- Evidence Service → Live Chat Processor: processes live chunks
- Evidence Service → SQL Database: reads and writes
- Evidence Service → Evidence Files: stores uploads
- Processor Factory → Chat Processor: creates processor
- Processor Factory → Other Processors: creates processor
- Chat Processor → Normalized Evidence: returns normalized data
- Other Processors → Normalized Evidence: returns normalized data
- Live Chat Processor → Normalized Evidence: returns normalized data
- Case Record → Evidence Record: associates evidence
- Case Record → Analysis Records: relates indicators
- Case Record → Timeline Record: relates events
- Case Record → Compromise Record: relates assessments
- Case Record → Report Record: relates reports