SentryAI: Sistema de Seguridad Marca Blanca con IA
Plataforma de inteligencia operativa para empresas de seguridad privada. Reportes por voz, detección de patrones con IA, chat RAG, alertas por proximidad GPS, tracking de desplazamientos y coordinación multi-guardia en tiempo real — todo en una PWA que funciona con guantes, bajo la lluvia, en una ronda de madrugada.
62
API Endpoints
14
Routers Backend
10
Páginas PWA
9
Cosmos DB Containers
1 El problema: seguridad privada en 2026 sigue usando papel
Más de 100.000 guardias de seguridad en España siguen rellenando partes en papel o PDFs que nadie lee. La información se fragmenta entre turnos, los patrones pasan desapercibidos y las alertas llegan tarde. Cada turno empieza de cero.
Cuando una empresa de seguridad privada nos pidió digitalizar sus operaciones, no quisimos hacer "otro formulario digital". Quisimos construir un sistema que piensa, conecta y anticipa.
| Problema actual | Solución SentryAI |
|---|---|
| Partes en papel que nadie lee | Reportes por voz indexados y buscables por IA |
| Info fragmentada entre turnos | Chat RAG: "¿Qué pasó anoche?" → resumen en 10 segundos |
| Detección de patrones imposible | Búsqueda semántica automática que correlaciona incidencias |
| Guardias con guantes o lluvia | Entrada 100% por voz, manos libres |
| No sabes dónde están los guardias | Mapa real-time con posiciones GPS + trails |
| Alertas llegan tarde | Broadcast por proximidad (15 km) en <2 segundos |
| Sin coordinación en emergencias | Pánico → chat de zona + respuesta del guardia más cercano |
| Sin control de activos | K9 GPS + Vehículos — flota completa en el mapa |
2 Marca blanca: una plataforma, múltiples empresas
SentryAI no es un producto cerrado para un solo cliente. Es un sistema marca blanca diseñado para que cualquier empresa de seguridad privada pueda tener su propia plataforma de inteligencia operativa.
🏢 Modelo multi-tenant
Cada empresa de seguridad obtiene su propio espacio aislado (Company → Site → Zone → Guard). Los datos nunca se mezclan. Cosmos DB particiona por siteId y companyId, garantizando aislamiento total a nivel de base de datos.
🎨 Personalizable
Cada empresa puede adaptar zonas, roles, polígonos de cobertura y configuración de alertas. No es "talla única".
🔒 Datos aislados
Particionado en Cosmos DB por empresa. Los guardias de VallSecurity nunca ven datos de otra compañía.
📈 Escalable
Cosmos DB Serverless + App Service escalable. De 5 guardias a 5.000 sin cambiar arquitectura.
💰 Coste por uso
Azure free tiers para MVP. Modelo de pricing por guardia/mes para producción.
3 Arquitectura: PWA + FastAPI + Azure AI
Frontend (PWA) REST + SSE Backend (FastAPI) ┌──────────────┐ ┌───────────────────┐ │ 🎙️ Recorder │── POST /api/report ──────→│ 8-step pipeline │ │ 💬 Chat RAG │── POST /api/chat ────────→│ RAG pipeline │ │ 🚨 Alerts │←─ GET /alerts/stream ─────│ SSE broadcast │ │ 📍 Map │←─ GET /positions/stream ──│ GPS real-time │ │ 💭 TeamChat │←─ GET /messages/stream ──│ Messaging SSE │ │ 📊 Dashboard │── GET /api/stats ────────→│ Cosmos aggregate │ └──────────────┘ └────────┬──────────┘ │ ┌────────────────────┼─────────────────────┐ ↓ ↓ ↓ Cosmos DB Azure OpenAI AI Search Blob Storage Speech STT Azure Maps
| Capa | Tecnología |
|---|---|
| Frontend | TypeScript + Vite — PWA zero-dependencies, ~37 módulos |
| Backend | Python 3.11 + FastAPI — 14 routers, 62 endpoints |
| IA — Voz | Azure Speech (STT, es-ES) — transcripción batch |
| IA — Cerebro | Azure OpenAI — GPT-4o (entidades, síntesis, triage) + text-embedding-3-small |
| IA — Búsqueda | Azure AI Search — hybrid (vector + keyword + semantic), HyDE enrichment |
| Data | Cosmos DB Serverless (9 containers) + Blob Storage (audios) |
| Real-time | 3 SSE streams concurrentes (alertas, posiciones, mensajes) |
| Mapas | Azure Maps — GPS tracking, polígonos editables, route navigation |
| Auth | Google Sign-In + Local-first (UUID + localStorage) |
💡 Zero-dependency frontend
Sin React, sin Vue, sin Angular. TypeScript puro con Vite. El bundle completo pesa menos de 100 KB. Cada componente es una función que devuelve un HTMLElement. El router usa hash-based navigation con page-cache — las páginas se ocultan/muestran en vez de destruirse y recrearse, eliminando re-fetches innecesarios.
4 Pipeline de ingesta: del audio al patrón en 8 pasos
El guardia pulsa un botón y habla. Lo que ocurre después es un pipeline de 8 pasos que transforma audio en inteligencia accionable:
Audio → Blob Storage
El audio WebM/Opus se sube a Azure Blob con SAS token. URL persistida para reproducción posterior.
Speech-to-Text (Azure Speech)
Transcripción en español (es-ES) con confidence score. Funciona con acento, ruido ambiente, lluvia.
Entity Extraction (GPT-4o)
Structured output: severidad, sujetos (descripción, actitud), vehículos (color, matrícula), ubicación, acción tomada, tags. Con response_format: json_object + JSON repair multi-capa.
HyDE Enrichment
GPT-4o genera: resumen denso, keywords, 3 preguntas hipotéticas que el reporte respondería y pattern hints. Esto mejora el retrieval posterior ~30%.
Embedding (text-embedding-3-small)
Vector de 1536 dimensiones del texto enriquecido (transcripción + summary + keywords + questions). Base para búsqueda semántica.
Indexación dual (paralelo)
Cosmos DB: documento completo con metadatos. AI Search: vector + keyword + filtros para hybrid search.
AlertTriage Engine
Motor autónomo de decisión: risk scoring + confidence + escalation. Pondera factores (sujetos, vehículos, hora nocturna, reincidencia) y decide si notificar, escalar o archivar.
Pattern Detection + Alert Broadcast
Busca reportes similares en las últimas 24h en la misma zona. Si hay match con score >0.80, genera alerta de patrón y la envía vía SSE.
⚡ Graceful Degradation
Si STT falla → error 502 (necesitamos la transcripción). Si GPT-4o falla → se guarda sin entidades. Si AI Search falla → se guarda en Cosmos (se reindexará). Si el broadcast falla → se loguea pero el reporte se persiste. El dato nunca se pierde.
5 Chat RAG: "¿Qué pasó anoche?" → respuesta con fuentes en 10 segundos
El guardia que empieza turno puede preguntar en lenguaje natural. El sistema busca en todos los reportes indexados, filtra por zona y turno, y sintetiza una respuesta citando fuentes:
"¿Se reportó algo sospechoso en la zona norte esta semana?"
// Pipeline RAG:
1. Embed query → vector 1536 dims
2. Hybrid Search (vector + keyword + semantic) → top 4 con score > 0.35
3. GPT-4o sintetiza con system prompt estático (cacheable)
4. Dedup fuentes por reportId
// Respuesta:
"Sí. Según el reporte RPT-2026-04-01-003 del Guardia López,
se detectó un individuo con chaqueta roja merodeando cerca
de la valla norte a las 03:40. El Guardia Martínez también
reportó un vehículo blanco sin matrícula visible (RPT-...-007).
⚠️ Patrón: 2 incidencias en la misma zona en 48h."
El chat tiene dual-mode: tab "SentryAI" para consultas RAG con la IA, y tab "Equipo" para mensajería directa entre guardias — estilo WhatsApp con grupos por zona y DMs.
6 Alertas por proximidad: el guardia más cercano responde
Cuando un guardia pulsa el botón de pánico, el sistema no envía la alerta a todos. Calcula la distancia haversine entre la posición del guardia en peligro y todos los demás guardias conectados, y solo notifica a los que están a ≤15 km.
🚨 Guardia García pulsa PÁNICO (lat: 41.12, lng: 1.25)
→ push_alert_to_nearby(
origin_lat=41.12, origin_lng=1.25,
radius_km=15.0,
exclude_guard="garcia"
)
// Resultado:
✅ Guardia López (3.2 km) → RECIBE ALERTA
✅ Guardia Martínez (8.7 km) → RECIBE ALERTA
❌ Guardia Pérez (22.1 km) → no notificado
// Automáticamente:
💬 Se postea en el chat de zona: "🚨 ALERTA PÁNICO — García"
📋 Se guarda en Cosmos con lista de nearby_guards
Cuando un guardia responde (POST /alerts/respond), el sistema:
- Registra quién respondió y cuándo
- Postea automáticamente en el chat de zona: "Guardia López responde: voy para allá"
- Broadcast vía SSE a todos los conectados de ese site
7 Tracking GPS: el concepto "km0" y detección de zona
Cada guardia tiene una zona base (su asignación). El sistema registra todos los desplazamientos GPS y calcula la distancia geodésica (haversine) desde esa zona base — lo que llamamos "km0".
📍 Waypoints por evento
Cada reporte, mensaje, alerta o acción manual marca un waypoint GPS. Periodic capture cada 5 min (10s foreground / 60s background).
🗺️ Detección inter-zona
Si un guardia cruza a otra zona, el backend auto-registra un evento zone_transfer comparando zona actual vs última conocida.
📊 Timeline expandible
Cada punto muestra zone badge (in-zone/out-of-zone), tipo de evento, detalles expandibles y botón "Ver en mapa" que centra el mapa en esa ubicación.
🔋 Throttling inteligente
La app detecta visibilitychange: foreground=10s, background=60s. Al volver, burst inmediato. Ahorra batería sin perder datos.
El mapa interactivo (Azure Maps) muestra en tiempo real las posiciones de todos los guardias, trails GPS, polígonos de zonas editables, K9 con GPS de collar y vehículos de patrulla. Soporta deep-linking: desde la página de tracking, el botón "Ver en mapa" navega a /map?lat=X&lng=Y&zoom=17.
8 Activos operativos: K9 GPS + Vehículos de flota
Los K9 y vehículos son activos rastreables con la misma infraestructura GPS que los guardias. Comparten el concepto de "Asset" — recurso con posición, estado y trail:
| Aspecto | 🐕 K9 | 🚗 Vehículo |
|---|---|---|
| GPS | Collar GPS (Tractive, Fi, PetFon) | OBD GPS / tracker vehicular |
| Responsable | Guía canino (handler) | Conductor asignado (driver) |
| Estados | active / resting / off_duty | in_service / parked / maintenance |
| Endpoints | 7 (CRUD + GPS + status) | 8 (CRUD + GPS + status + park) |
| Mapa | 🐕 marcador con trail | 🚗 / 🅿️ / 🔧 según estado |
Funcionalidad "Aparcar vehículo": el guardia marca dónde deja el coche con un toque. Al iniciar patrulla a pie, otros guardias ven los vehículos estacionados en el mapa. Navegación de vuelta disponible (Azure Maps directions).
9 PWA offline-first: funciona en una ronda sin cobertura
Los guardias patrullan en sótanos, perímetros rurales, zonas industriales — sitios donde el 4G es intermitente. SentryAI es una PWA instalable con Service Worker v2 que maneja la realidad de la desconexión:
💾 Offline Queue
POSTs fallidos (reportes, mensajes, waypoints) se guardan en IndexedDB. Al reconectar → flush automático con Background Sync API.
⚡ Cache inteligente
Cache-first para assets hasheados de Vite, stale-while-revalidate para datos. SSE streams bypasean el SW.
📄 Page Cache Router
Las páginas se ocultan/muestran (display:none) en vez de destruirse. SSE se pausa al salir y reconecta al entrar (page-enter/page-leave).
🔄 TTL Data Cache
Módulo cache.ts con TTL configurable por endpoint: tracking 30s, dashboard 60s, shift summary 2min.
10 Las 10 páginas: todo lo que necesita un guardia
| Página | Función |
|---|---|
| 🎙️ Patrol | Grabación de reportes por voz + alertas activas + resumen de turno |
| 💬 Chat | Dual-mode: SentryAI (RAG) + Equipo (mensajes zona/DMs). Badge no leídos en navbar |
| 🗺️ Map | Azure Maps con guardias, K9, vehículos, trails, zonas editables. Deep-link desde tracking |
| 📋 History | Historial de reportes con filtros, estados y reproducción de audio |
| 📊 Dashboard | Estadísticas: reportes por severidad, zonas activas, alertas, tiempos |
| 📍 Tracking | Desplazamientos GPS: timeline, zone badges, expandable cards, zone trips |
| 👤 Profile | Compartir perfil (token 6-char), cambiar zona, reubicar GPS, cerrar sesión |
| ⚙️ Admin | Super admin: control de usuarios, zonas, roles, solicitudes pendientes |
| 👋 Onboarding | Registro local-first: nombre + GPS + zona. Persiste en localStorage |
| 🔗 Transfer | Landing de transferencia: restaurar perfil en otro dispositivo via token |
11 De Cadences a SentryAI: patrones que viajan
SentryAI no se construyó desde cero. Años de producción con Cadences nos dieron patrones validados que portamos directamente:
| Patrón | En Cadences | En SentryAI |
|---|---|---|
| RAG + HyDE | 3700+ chunks, enrichment DeepSeek | Reportes → HyDE → AI Search hybrid |
| Autonomous Engine | 493 líneas, risk/confidence/escalation | AlertTriage: triaje autónomo de incidencias |
| JSON Repair | 4 capas de fallback para LLM output | Mismas 4 capas portadas directamente |
| 2-phase Sync | Primero counts, luego data | Offline-first para guardias sin cobertura |
| Standardized Responses | { success, data/error } | Consistencia total en 62 endpoints |
| Multi-tenant | Organization → filtering | Company → Site → Zone → Guard |
🔑 La lección
Los patrones de arquitectura son independientes del cloud. JSON repair, ID generators, respuestas estandarizadas, RAG con HyDE, autonomous decision engine — todo viajó en un git init de Cloudflare Workers a Azure App Service.
12
Diferenciadores vs la competencia
Feature SentryAI Competencia típica Entrada por voz ✅ Streaming STT ❌ Formularios manuales RAG sobre reportes ✅ Semántica + HyDE ❌ Sin IA Alertas proactivas IA ✅ Pattern detection + risk scoring ⚠️ Reglas fijas Alertas por proximidad ✅ 15 km haversine + respuesta ❌ Broadcast masivo Resumen de turno IA ✅ Generado automáticamente ❌ Manual Triaje autónomo ✅ Confidence-based ❌ Offline capable ✅ PWA + IndexedDB + BG Sync ⚠️ Apps nativas (pobre offline) Búsqueda cross-turno ✅ Semántica + temporal ❌ Manual o SQL básico K9 + Vehículos GPS ✅ 15 endpoints unificados ❌ Sistemas separados Coste MVP $0 (Azure free tiers) €€€/mes
13
Roadmap: qué viene después
🔥 Heatmaps de actividad
Zonas calientes por densidad de reportes/alertas. El LLM sugiere reubicación de guardias basada en clusters de incidentes.
⚡ Emergency routing
En alerta crítica, calcular qué guardia llega más rápido por posición actual + velocidad estimada.
🤖 Auto-dispatch LLM
El LLM decide si mover un guardia a otra zona basándose en patrón de riesgo detectado. Autonomous actions.
🎯 Predictive staffing
"Los martes a las 22h la zona norte necesita refuerzo" — basado en datos históricos reales.
👼 Guardian Angel Mode
Al activar pánico, TODOS los dispositivos cercanos vibran y muestran dirección + distancia al compañero.
🗣️ Voice situational awareness
"SentryAI, ¿hay algún incidente activo cerca de mí?" → Respuesta natural con contexto espacial.
14
Conclusión: la seguridad privada necesitaba esto ayer
SentryAI no es un "formulario digital". Es un sistema nervioso para operaciones de seguridad — que escucha, entiende, conecta patrones y coordina equipos en tiempo real.
El modelo marca blanca permite que cualquier empresa de seguridad privada tenga acceso a tecnología que hasta ahora solo podían permitirse las grandes corporaciones. Con Azure free tiers, el MVP corre sin coste — y la arquitectura multi-tenant escala sin cambiar una línea de código.
🛡️ SentryAI — Inteligencia Compartida de Seguridad
62 endpoints · 14 routers · 10 páginas PWA · 9 contenedores Cosmos DB · 3 SSE streams · Pipeline IA de 8 pasos · Alertas 15 km · K9 GPS + Vehículos · Chat RAG + Equipo · Offline-first con Background Sync.
Stack: Python FastAPI · Azure OpenAI · AI Search · Cosmos DB · Speech SDK · Azure Maps · Vite PWA (TypeScript, zero-dependencies)
Si gestionas una empresa de seguridad privada y quieres saber más, SentryAI ya está en producción y listo para desplegar como marca blanca.
C Cadences Engineering
Documentación técnica del equipo de ingeniería