# jpmorillom1/kuntur-extorsiones architecture

> Architecture diagram of the GitHub repository jpmorillom1/kuntur-extorsiones, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jpmorillom1/kuntur-extorsiones
- Repository: https://github.com/jpmorillom1/kuntur-extorsiones

## Overview

##### Project type and purpose
- This is a full-stack web application (“Kuntur – Sistema AntiExtorsiones”) built on Flask.
- It ingests live audio/video from IP cameras, performs real-time speech-to-text, semantic threat analysis via LLMs, captures visual captions, stores evidence, and notifies authorities via JSON.
- The goal is to detect extortion threats in retail locations, record evidence, and instantly alert law enforcement (UPC).

##### File structure
- Top-level:
- app.py – Flask entry point
- routes/ – HTTP endpoints for auth, transcription, alerts, video streaming
- services/ – core business logic (AI providers, threat detection, DB, uploader, notifier, state)
- templates/ & static/ – front-end assets (HTML, JS, CSS, Bootstrap, Leaflet, SSE scripts)
- mock_services/ – stub implementations (for testing)
- Dockerfile, requirements.txt, .gitignore

- Architectural hints:
- Flask “routes” act as controllers (thin), calling into “services” (the domain layer).
- services/global_state.py + SSE scripts enable real-time push to browser.
- Video processing uses OpenCV/imageio wrapped in video_uploader.py.
- External integrations: Google Gemini, Faster-Whisper, BLIP, Backblaze B2, MongoDB, external UPC API.

##### README for additional insights
Frontend (HTML+Bootstrap) ↔ Flask (Registration/Login) ↔ Whisper → Gemini → BLIP
↔ Video capture/upload → MongoDB → Notificación JSON → UPC API
- Tech stack table confirms all integrations and frameworks.
- JSON schema for alert reports shows data flow to UPC.

a. Main components
- Client Browser (Frontend)
- Flask Application Server
- Authentication Module
- Transcription & Threat-Analysis Module
- Video Capture & Upload Module
- Manual Alert Module
- Global State & SSE Module
- Database (MongoDB)
- External AI Providers (Faster-Whisper, Gemini 2.5 via LangChain, BLIP)
- Cloud Storage (Backblaze B2)
- External Notification API (UPC)
- IP Camera (RTSP/HTTP Video Stream)

b. Relationships & interactions
1. Browser → Flask/Auth routes: login/registration → MongoDB
2. Browser → Flask/stream_routes: request live video → IP Camera → Flask → Browser (SSE/JS)
3. Flask/transcribe_routes:
- Pull audio from live stream → Faster-Whisper → text
- Send text → Gemini (via gemini_provider + gemini_analyzer + threat_detector) → threat verdict + summary
4. Flask/video_uploader:
- Video snippet → BLIP caption → upload to Backblaze B2 → return URL
5. Flask/notificador_upc:
- Compose JSON alert (description, location, camera IP, B2 URL) → HTTP POST → UPC API
6. Global State & SSE: push real-time alerts to all connected browsers → update alert panel.
7. All persistence (users, alerts) → MongoDB via services/db.py

c. Architectural patterns & design principles
- Layered Architecture: Presentation (routes/templates/static), Application (Flask controllers), Domain (services/*), Infrastructure (MongoDB, B2, external APIs)
- Single-process monolith with modular internal services
- Event-driven updates via Server-Sent Events (SSE)
- Separation of concerns: each “service” has a single responsibility (AI inference, storage, notification)
- Dependency injection/config via .env

d. Key technologies & frameworks
- Flask (web framework)
- Server-Sent Events (real-time updates)
- Faster-Whisper (speech-to-text)
- Gemini Pro + LangChain (semantic analysis)
- BLIP Image Captioning (visual description)
- OpenCV + imageio (video capture)
- Backblaze B2 (cloud evidence storage)
- MongoDB (NoSQL persistence)
- Leaflet.js + Nominatim (geolocation mapping)
- Bootstrap (UI styling)

##### Elements
- Labels: name every component (e.g., “transcribe_routes”, “threat_detector service”).
- Blue for frontend components
- Green for backend (Flask + service modules)
- Orange for external/infra (MongoDB, B2, Gemini APIs, UPC API)
- Rectangles for processes (services, routes)
- Clouds for external APIs/storage

##### Final advice
- Both synchronous HTTP calls and asynchronous streams (SSE, video).

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend Layer
  subgraph "Frontend (Browser)" 
    direction TB
    FB1["index.html"]:::frontend
    FB2["login.html"]:::frontend
    FB3["registro.html"]:::frontend
    FB4["alerta.html"]:::frontend
    FB5["mis_alertas.html"]:::frontend
    JS1["app.js"]:::frontend
    JS2["sse.js"]:::frontend
    JS3["alerta_manual.js"]:::frontend
    JS4["alerta_sse.js"]:::frontend
    JS5["mapa_alerta.js"]:::frontend
    JS6["register_map.js"]:::frontend
    JS7["sensores.js"]:::frontend
    CSS["styles*.css"]:::frontend
  end

  %% Backend Layer
  subgraph "Backend (Flask Application)" 
    direction TB
    AP["app.py"]:::backend

    subgraph "Authentication Module"
      direction TB
      AR["auth_routes.py"]:::backend
      SAuth["auth.py"]:::backend
      SDB["db.py"]:::backend
    end

    subgraph "Transcription & Threat Analysis"
      direction TB
      TR["transcribe_routes.py"]:::backend
      CG["caption_generator.py"]:::backend
      GP["gemini_provider.py"]:::backend
      GA["gemini_analyzer.py"]:::backend
      TD["threat_detector.py"]:::backend
    end

    subgraph "Video Capture & Upload"
      direction TB
      SR["stream_routes.py"]:::backend
      VU["video_uploader.py"]:::backend
    end

    subgraph "Manual Alert Module"
      direction TB
      ARL["alerta_routes.py"]:::backend
      NU["notificador_upc.py"]:::backend
    end

    subgraph "Global State & SSE"
      direction TB
      GS["global_state.py"]:::backend
    end

    MS["mock_services.py"]:::backend
    CFG1["Dockerfile"]:::backend
    CFG2["requirements.txt"]:::backend
    CFG3[".gitignore"]:::backend
    CFG4["README.md"]:::backend
  end

  %% External/Infrastructure Layer
  subgraph "Infrastructure & External APIs"
    direction TB
    DB[(MongoDB)]:::external
    B2[(Backblaze B2)]:::external
    GEM["Gemini API"]:::external
    UPC[(UPC API)]:::external
    CAM["IP Camera\n(RTSP/HTTP)"]:::external
    ALERT_JSON["Alert JSON"]:::external
  end

  %% Relationships - Frontend to Backend
  FB1 -->|"HTTP" | AP
  FB2 -->|"HTTP" | AP
  FB3 -->|"HTTP" | AP
  FB4 -->|"HTTP" | AP
  FB5 -->|"HTTP" | AP
  JS2 -->|"SSE" | GS
  JS4 -->|"SSE" | GS
  JS3 -->|"HTTP" | ARL
  JS5 -->|"HTTP" | SR

  %% Authentication flow
  AP --> AR
  AR -->|"uses"| SAuth
  SAuth --> SDB
  SDB --> DB

  %% Video streaming flow
  AP --> SR
  SR --> CAM
  CAM --> SR
  SR --> JS2
  SR --> JS4

  %% Transcription & Analysis flow
  AP --> TR
  TR -->|"uses audio"| SR
  TR --- CG
  TR --- GP
  GP --> GA
  GA --> TD

  %% Video upload & caption
  AP --> VU
  VU --- CG
  VU --> B2

  %% Manual alert
  ARL --> NU
  NU --> ALERT_JSON
  ALERT_JSON --> UPC

  %% Global state updates
  TD --> GS
  VU --> GS
  ARL --> GS
  GS --> JS2
  GS --> JS4

  %% Persistence
  TD --> SDB
  VU --> SDB
  NU --> SDB
  MS --> AP

  %% External calls
  GP --> GEM
  GA --> GEM

  %% Click Events
  click FB1 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/templates/index.html"
  click FB2 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/templates/login.html"
  click FB3 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/templates/registro.html"
  click FB4 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/templates/alerta.html"
  click FB5 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/templates/mis_alertas.html"
  click JS1 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/app.js"
  click JS2 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/sse.js"
  click JS3 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/alerta_manual.js"
  click JS4 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/alerta_sse.js"
  click JS5 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/mapa_alerta.js"
  click JS6 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/register_map.js"
  click JS7 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/sensores.js"
  click CSS "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/static/styles.css"
  click AP "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/app.py"
  click AR "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/routes/auth_routes.py"
  click SAuth "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/auth.py"
  click SDB "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/db.py"
  click TR "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/routes/transcribe_routes.py"
  click CG "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/caption_generator.py"
  click GP "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/gemini_provider.py"
  click GA "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/gemini_analyzer.py"
  click TD "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/threat_detector.py"
  click SR "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/routes/stream_routes.py"
  click VU "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/video_uploader.py"
  click ARL "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/routes/alerta_routes.py"
  click NU "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/notificador_upc.py"
  click GS "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/services/global_state.py"
  click MS "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/mock_services/mock_services.py"
  click CFG1 "https://github.com/jpmorillom1/kuntur-extorsiones/tree/master/Dockerfile"
  click CFG2 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/requirements.txt"
  click CFG3 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/.gitignore"
  click CFG4 "https://github.com/jpmorillom1/kuntur-extorsiones/blob/master/README.md"

  %% Styles
  classDef frontend fill:#ADD8E6,stroke:#000
  classDef backend fill:#90EE90,stroke:#000
  classDef external fill:#FFA500,stroke:#000
  class FB1,FB2,FB3,FB4,FB5,JS1,JS2,JS3,JS4,JS5,JS6,JS7,CSS frontend
  class AP,AR,SAuth,SDB,TR,CG,GP,GA,TD,SR,VU,ARL,NU,GS,MS,CFG1,CFG2,CFG3,CFG4 backend
  class DB,B2,GEM,UPC,CAM,ALERT_JSON external
```
