How jpmorillom1/kuntur-extorsiones works
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).