# seyric/vigilens architecture

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

- Interactive diagram: https://gitdiagram.com/seyric/vigilens
- Repository: https://github.com/seyric/vigilens

## Overview

Vigilens is a desktop investigation and crime-intelligence platform. An operator enters through the routed React workspace; the Electron shell can start the local FastAPI service. Backend routes expose investigation, analytics, AI, crime-pattern, and OSINT capabilities. One evidenced case-analysis path accepts an uploaded report, extracts and parses it, optionally enriches it with Gemini, then searches for matching records. The README documents broader graph, GIS, threat-intelligence, and forensic capabilities; their detailed wiring is not established by the sampled source.

Main entry points: [`backend/main.py`](https://github.com/seyric/vigilens/blob/main/backend/main.py) (FastAPI gateway), [`src/routes/AppRoutes.tsx`](https://github.com/seyric/vigilens/blob/main/src/routes/AppRoutes.tsx) (Workspace routes), [`backend/crime_pattern/controllers/upload_controller.py`](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/controllers/upload_controller.py) (Upload controller), [`backend/osint/router.py`](https://github.com/seyric/vigilens/blob/main/backend/osint/router.py) (OSINT API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop workspace"]
  node_electron["Electron shell<br/>[main.cjs]"]
  node_routes["Workspace routes<br/>[AppRoutes.tsx]"]
  node_caseui["Investigation workspace"]
  node_patternui["Pattern analysis UI"]
  node_gisui["GIS workspace<br/>[GISPage.tsx]"]
  node_osintui["OSINT workspace"]
end

subgraph group_api["API and access"]
  node_gateway["FastAPI gateway<br/>[main.py]"]
  node_auth["Authentication<br/>[router.py]"]
  node_coreapi["Core investigation API<br/>[router.py]"]
end

subgraph group_case["Case intelligence"]
  node_crimeapi["Crime-pattern API<br/>[router.py]"]
  node_upload["Upload controller"]
  node_extract["Document extraction<br/>[extractor.py]"]
  node_parser["Entity parsing<br/>[entity_parser.py]"]
  node_enrichment["AI enrichment<br/>[enrichment.py]"]
  node_search["Record matching<br/>[search.py]"]
end

subgraph group_intel["Threat intelligence"]
  node_osintapi["OSINT API<br/>[router.py]"]
  node_collectors["Multi-INT collectors"]
  node_live_store[("Live feed store<br/>[live_store.py]")]
end

subgraph group_data["Analytics and storage"]
  node_analytics["Analytics API<br/>[router.py]"]
  node_analyticsservice["Crime analytics"]
  node_gis["Geospatial analysis"]
  node_graph[("Criminal graph")]
  node_relational[("Relational database")]
end

node_operator(("Investigator"))

node_operator -->|"uses"| node_routes
node_routes -->|"routes to"| node_caseui
node_routes -->|"routes to"| node_patternui
node_routes -->|"routes to"| node_gisui
node_routes -->|"routes to"| node_osintui
node_electron -->|"starts service"| node_gateway
node_gateway -->|"mounts"| node_auth
node_gateway -->|"mounts"| node_coreapi
node_gateway -->|"mounts"| node_crimeapi
node_gateway -->|"mounts"| node_analytics
node_gateway -->|"mounts"| node_osintapi
node_crimeapi -->|"dispatches"| node_upload
node_upload -->|"extracts text"| node_extract
node_upload -->|"parses text"| node_parser
node_upload -.->|"enriches data"| node_enrichment
node_upload -->|"searches matches"| node_search
node_analytics -->|"serves analytics"| node_analyticsservice
node_gisui -.->|"geospatial capability"| node_gis
node_osintapi -.->|"collects feeds"| node_collectors
node_osintapi -.->|"uses feed store"| node_live_store
node_search -->|"queries records"| node_relational
node_coreapi -.->|"network analysis"| node_graph

click node_electron "https://github.com/seyric/vigilens/blob/main/electron/main.cjs"
click node_routes "https://github.com/seyric/vigilens/blob/main/src/routes/AppRoutes.tsx"
click node_caseui "https://github.com/seyric/vigilens/blob/main/src/pages/Investigation/InvestigationPage.tsx"
click node_patternui "https://github.com/seyric/vigilens/blob/main/src/pages/CrimePatternSimilarity/AICrimePatternSimilarityPageFull.tsx"
click node_gisui "https://github.com/seyric/vigilens/blob/main/src/pages/GIS/GISPage.tsx"
click node_osintui "https://github.com/seyric/vigilens/blob/main/src/pages/OSINT/OSINTTacticalMapPage.tsx"
click node_gateway "https://github.com/seyric/vigilens/blob/main/backend/main.py"
click node_auth "https://github.com/seyric/vigilens/blob/main/backend/auth/router.py"
click node_coreapi "https://github.com/seyric/vigilens/blob/main/backend/core/router.py"
click node_crimeapi "https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/routes/router.py"
click node_upload "https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/controllers/upload_controller.py"
click node_extract "https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/ocr/extractor.py"
click node_parser "https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/parsers/entity_parser.py"
click node_enrichment "https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/services/enrichment.py"
click node_search "https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/services/search.py"
click node_analytics "https://github.com/seyric/vigilens/blob/main/backend/analytics/router.py"
click node_analyticsservice "https://github.com/seyric/vigilens/tree/main/analytics"
click node_gis "https://github.com/seyric/vigilens/tree/main/gis"
click node_osintapi "https://github.com/seyric/vigilens/blob/main/backend/osint/router.py"
click node_collectors "https://github.com/seyric/vigilens/tree/main/backend/osint/collectors"
click node_live_store "https://github.com/seyric/vigilens/blob/main/backend/osint/services/live_store.py"
click node_graph "https://github.com/seyric/vigilens/tree/main/neo4j"
click node_relational "https://github.com/seyric/vigilens/tree/main/database"

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_electron,node_routes,node_caseui,node_patternui,node_gisui,node_osintui toneBlue
class node_gateway,node_auth,node_coreapi toneAmber
class node_crimeapi,node_upload,node_extract,node_parser,node_enrichment,node_search toneMint
class node_osintapi,node_collectors,node_live_store toneRose
class node_analytics,node_analyticsservice,node_gis,node_graph,node_relational,node_operator toneIndigo
```

## Components

### Desktop workspace

- [Electron shell](https://github.com/seyric/vigilens/blob/main/electron/main.cjs): `electron/main.cjs`
- [Workspace routes](https://github.com/seyric/vigilens/blob/main/src/routes/AppRoutes.tsx): `src/routes/AppRoutes.tsx`
- [Investigation workspace](https://github.com/seyric/vigilens/blob/main/src/pages/Investigation/InvestigationPage.tsx): `src/pages/Investigation/InvestigationPage.tsx`
- [Pattern analysis UI](https://github.com/seyric/vigilens/blob/main/src/pages/CrimePatternSimilarity/AICrimePatternSimilarityPageFull.tsx): `src/pages/CrimePatternSimilarity/AICrimePatternSimilarityPageFull.tsx`
- [GIS workspace](https://github.com/seyric/vigilens/blob/main/src/pages/GIS/GISPage.tsx): `src/pages/GIS/GISPage.tsx`
- [OSINT workspace](https://github.com/seyric/vigilens/blob/main/src/pages/OSINT/OSINTTacticalMapPage.tsx): `src/pages/OSINT/OSINTTacticalMapPage.tsx`

### API and access

- [FastAPI gateway](https://github.com/seyric/vigilens/blob/main/backend/main.py): `backend/main.py`
- [Authentication](https://github.com/seyric/vigilens/blob/main/backend/auth/router.py): `backend/auth/router.py`
- [Core investigation API](https://github.com/seyric/vigilens/blob/main/backend/core/router.py): `backend/core/router.py`

### Case intelligence

- [Crime-pattern API](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/routes/router.py): `backend/crime_pattern/routes/router.py`
- [Upload controller](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/controllers/upload_controller.py): `backend/crime_pattern/controllers/upload_controller.py`
- [Document extraction](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/ocr/extractor.py): `backend/crime_pattern/ocr/extractor.py`
- [Entity parsing](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/parsers/entity_parser.py): `backend/crime_pattern/parsers/entity_parser.py`
- [AI enrichment](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/services/enrichment.py): `backend/crime_pattern/services/enrichment.py`
- [Record matching](https://github.com/seyric/vigilens/blob/main/backend/crime_pattern/services/search.py): `backend/crime_pattern/services/search.py`

### Threat intelligence

- [OSINT API](https://github.com/seyric/vigilens/blob/main/backend/osint/router.py): `backend/osint/router.py`
- [Multi-INT collectors](https://github.com/seyric/vigilens/tree/main/backend/osint/collectors): `backend/osint/collectors`
- [Live feed store](https://github.com/seyric/vigilens/blob/main/backend/osint/services/live_store.py): `backend/osint/services/live_store.py`

### Analytics and storage

- [Analytics API](https://github.com/seyric/vigilens/blob/main/backend/analytics/router.py): `backend/analytics/router.py`
- [Crime analytics](https://github.com/seyric/vigilens/tree/main/analytics): `analytics`
- [Geospatial analysis](https://github.com/seyric/vigilens/tree/main/gis): `gis`
- [Criminal graph](https://github.com/seyric/vigilens/tree/main/neo4j): `neo4j`
- [Relational database](https://github.com/seyric/vigilens/tree/main/database): `database`

### Other components

- **Investigator**

## Connections

- Investigator → Workspace routes: uses
- Workspace routes → Investigation workspace: routes to
- Workspace routes → Pattern analysis UI: routes to
- Workspace routes → GIS workspace: routes to
- Workspace routes → OSINT workspace: routes to
- Electron shell → FastAPI gateway: starts service
- FastAPI gateway → Authentication: mounts
- FastAPI gateway → Core investigation API: mounts
- FastAPI gateway → Crime-pattern API: mounts
- FastAPI gateway → Analytics API: mounts
- FastAPI gateway → OSINT API: mounts
- Crime-pattern API → Upload controller: dispatches
- Upload controller → Document extraction: extracts text
- Upload controller → Entity parsing: parses text
- Upload controller → AI enrichment: enriches data
- Upload controller → Record matching: searches matches
- Analytics API → Crime analytics: serves analytics
- GIS workspace → Geospatial analysis: geospatial capability
- OSINT API → Multi-INT collectors: collects feeds
- OSINT API → Live feed store: uses feed store
- Record matching → Relational database: queries records
- Core investigation API → Criminal graph: network analysis