# harish2008-code/border-sentinel architecture

> Architecture diagram of the GitHub repository harish2008-code/border-sentinel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harish2008-code/border-sentinel
- Repository: https://github.com/harish2008-code/border-sentinel

## Overview

Border Sentinel screens travel-document images, optionally with a live photo, and returns an auditable risk assessment for analyst review. The principal flow is upload through the web interface or JSON API, pipeline orchestration of extraction, validation, forensics, biometrics and identity checks, risk scoring, persistence, and report rendering. The README also documents camera capture, watchlist administration, email confirmation, and synthetic demo-document generation. Edges follow documented pipeline wiring and indexed references; unshown internal details are omitted rather than inferred.

Main entry points: [`screening/pipeline.py`](https://github.com/harish2008-code/border-sentinel/blob/main/screening/pipeline.py) (Screening orchestrator), [`screening/views.py`](https://github.com/harish2008-code/border-sentinel/blob/main/screening/views.py) (Web views), [`screening/models.py`](https://github.com/harish2008-code/border-sentinel/blob/main/screening/models.py) (Screening records), [`screening/api.py`](https://github.com/harish2008-code/border-sentinel/blob/main/screening/api.py) (JSON API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Intake and review"]
  node_web["Web interface"]
  node_web_views["Web views<br/>[views.py]"]
  node_api["JSON API<br/>[api.py]"]
  node_camera["Camera capture<br/>[camera.py]"]
  node_synthetic["Demo document generator<br/>[synthetic.py]"]
end

subgraph group_screening["Screening pipeline"]
  node_pipeline["Screening orchestrator<br/>[pipeline.py]"]
  node_extraction["OCR extraction<br/>[ocr_engine.py]"]
  node_mrz["MRZ parsing<br/>[mrz.py]"]
  node_rules["Document validation<br/>[rules.py]"]
  node_tamper["Tamper forensics<br/>[tamper.py]"]
  node_scoring["Risk scoring<br/>[scoring.py]"]
  node_annotation["Analyst overlay<br/>[annotate.py]"]
end

subgraph group_verification["Identity verification"]
  node_faces["Face biometrics<br/>[faces.py]"]
  node_identity_db["Identity lookup<br/>[db_verify.py]"]
  node_email_verify["Email confirmation<br/>[email_verify.py]"]
end

subgraph group_records["Records and audit"]
  node_records[("Screening records<br/>[models.py]")]
end

subgraph group_integrations["External services"]
  node_mysql[("Identity MySQL")]
  node_smtp["SMTP service"]
end

node_traveller(("Traveller / analyst"))

node_traveller -->|"uploads document"| node_web
node_web -->|"submits screening"| node_web_views
node_traveller -->|"submits upload"| node_api
node_web_views -->|"runs screening"| node_pipeline
node_api -->|"runs screening"| node_pipeline
node_traveller -->|"captures photo"| node_camera
node_pipeline -->|"extracts fields"| node_extraction
node_extraction -->|"parses MRZ"| node_mrz
node_pipeline -->|"validates fields"| node_rules
node_pipeline -->|"checks tampering"| node_tamper
node_pipeline -->|"compares faces"| node_faces
node_pipeline -->|"looks up identity"| node_identity_db
node_identity_db -->|"queries records"| node_mysql
node_pipeline -->|"starts confirmation"| node_email_verify
node_email_verify -->|"sends email"| node_smtp
node_traveller -.->|"responds by link"| node_smtp
node_pipeline -->|"combines risk"| node_scoring
node_pipeline -->|"persists decision"| node_records
node_pipeline -->|"renders overlay"| node_annotation
node_web_views -->|"reads and updates"| node_records
node_api -->|"serves record data"| node_records
node_records -.->|"provides report data"| node_web_views
node_synthetic -->|"generates demo corpus"| node_traveller

click node_web "https://github.com/harish2008-code/border-sentinel/tree/main/screening/templates/screening"
click node_web_views "https://github.com/harish2008-code/border-sentinel/blob/main/screening/views.py"
click node_api "https://github.com/harish2008-code/border-sentinel/blob/main/screening/api.py"
click node_camera "https://github.com/harish2008-code/border-sentinel/blob/main/screening/camera.py"
click node_pipeline "https://github.com/harish2008-code/border-sentinel/blob/main/screening/pipeline.py"
click node_extraction "https://github.com/harish2008-code/border-sentinel/blob/main/screening/ocr_engine.py"
click node_mrz "https://github.com/harish2008-code/border-sentinel/blob/main/screening/mrz.py"
click node_rules "https://github.com/harish2008-code/border-sentinel/blob/main/screening/rules.py"
click node_tamper "https://github.com/harish2008-code/border-sentinel/blob/main/screening/tamper.py"
click node_faces "https://github.com/harish2008-code/border-sentinel/blob/main/screening/faces.py"
click node_identity_db "https://github.com/harish2008-code/border-sentinel/blob/main/screening/db_verify.py"
click node_email_verify "https://github.com/harish2008-code/border-sentinel/blob/main/screening/email_verify.py"
click node_scoring "https://github.com/harish2008-code/border-sentinel/blob/main/screening/scoring.py"
click node_annotation "https://github.com/harish2008-code/border-sentinel/blob/main/screening/annotate.py"
click node_records "https://github.com/harish2008-code/border-sentinel/blob/main/screening/models.py"
click node_synthetic "https://github.com/harish2008-code/border-sentinel/blob/main/screening/synthetic.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_web,node_web_views,node_api,node_camera,node_synthetic toneBlue
class node_pipeline,node_extraction,node_mrz,node_rules,node_tamper,node_scoring,node_annotation toneAmber
class node_faces,node_identity_db,node_email_verify toneMint
class node_records toneRose
class node_mysql,node_smtp,node_traveller toneIndigo
```

## Components

### Intake and review

- [Web interface](https://github.com/harish2008-code/border-sentinel/tree/main/screening/templates/screening): `screening/templates/screening`
- [Web views](https://github.com/harish2008-code/border-sentinel/blob/main/screening/views.py): `screening/views.py`
- [JSON API](https://github.com/harish2008-code/border-sentinel/blob/main/screening/api.py): `screening/api.py`
- [Camera capture](https://github.com/harish2008-code/border-sentinel/blob/main/screening/camera.py): `screening/camera.py`
- [Demo document generator](https://github.com/harish2008-code/border-sentinel/blob/main/screening/synthetic.py): `screening/synthetic.py`

### Screening pipeline

- [Screening orchestrator](https://github.com/harish2008-code/border-sentinel/blob/main/screening/pipeline.py): `screening/pipeline.py`
- [OCR extraction](https://github.com/harish2008-code/border-sentinel/blob/main/screening/ocr_engine.py): `screening/ocr_engine.py`
- [MRZ parsing](https://github.com/harish2008-code/border-sentinel/blob/main/screening/mrz.py): `screening/mrz.py`
- [Document validation](https://github.com/harish2008-code/border-sentinel/blob/main/screening/rules.py): `screening/rules.py`
- [Tamper forensics](https://github.com/harish2008-code/border-sentinel/blob/main/screening/tamper.py): `screening/tamper.py`
- [Risk scoring](https://github.com/harish2008-code/border-sentinel/blob/main/screening/scoring.py): `screening/scoring.py`
- [Analyst overlay](https://github.com/harish2008-code/border-sentinel/blob/main/screening/annotate.py): `screening/annotate.py`

### Identity verification

- [Face biometrics](https://github.com/harish2008-code/border-sentinel/blob/main/screening/faces.py): `screening/faces.py`
- [Identity lookup](https://github.com/harish2008-code/border-sentinel/blob/main/screening/db_verify.py): `screening/db_verify.py`
- [Email confirmation](https://github.com/harish2008-code/border-sentinel/blob/main/screening/email_verify.py): `screening/email_verify.py`

### Records and audit

- [Screening records](https://github.com/harish2008-code/border-sentinel/blob/main/screening/models.py): `screening/models.py`

### External services

- **Identity MySQL**
- **SMTP service**

### Other components

- **Traveller / analyst**

## Connections

- Traveller / analyst → Web interface: uploads document (evidence: `README.md`)
- Web interface → Web views: submits screening (evidence: `README.md`)
- Traveller / analyst → JSON API: submits upload (evidence: `README.md`)
- Web views → Screening orchestrator: runs screening (evidence: `screening/views.py`)
- JSON API → Screening orchestrator: runs screening (evidence: `screening/api.py`)
- Traveller / analyst → Camera capture: captures photo (evidence: `README.md`)
- Screening orchestrator → OCR extraction: extracts fields (evidence: `README.md`)
- OCR extraction → MRZ parsing: parses MRZ (evidence: `screening/ocr_engine.py`)
- Screening orchestrator → Document validation: validates fields (evidence: `screening/pipeline.py`)
- Screening orchestrator → Tamper forensics: checks tampering (evidence: `README.md`)
- Screening orchestrator → Face biometrics: compares faces (evidence: `README.md`)
- Screening orchestrator → Identity lookup: looks up identity (evidence: `screening/pipeline.py`)
- Identity lookup → Identity MySQL: queries records (evidence: `README.md`)
- Screening orchestrator → Email confirmation: starts confirmation (evidence: `README.md`)
- Email confirmation → SMTP service: sends email (evidence: `README.md`)
- Traveller / analyst → SMTP service: responds by link (evidence: `README.md`)
- Screening orchestrator → Risk scoring: combines risk (evidence: `README.md`)
- Screening orchestrator → Screening records: persists decision (evidence: `README.md`)
- Screening orchestrator → Analyst overlay: renders overlay (evidence: `README.md`)
- Web views → Screening records: reads and updates (evidence: `screening/views.py`)
- JSON API → Screening records: serves record data (evidence: `screening/api.py`)
- Screening records → Web views: provides report data (evidence: `screening/views.py`)
- Demo document generator → Traveller / analyst: generates demo corpus (evidence: `README.md`)
