graph LR
subgraph 1["Ingestion & Worker Pipeline"]
1__1_1["Webhook Ingestion Gateway"]
1__1_2["Event Triage & Dispatcher"]
1__1_3["Deep Analysis Engine"]
1__1_4["Pipeline Messaging Protocol"]
1__1_1 -->|"Enqueues validated webhook payloads into the webhook queue for initial processing."| 1__1_2
1__1_2 -->|"Dispatches specific analysis tasks to the analysis queue after identifying relevant PR or code chan…"| 1__1_3
1__1_2 -->|"Utilizes standardized job data interfaces to structure payloads for downstream workers."| 1__1_4
1__1_3 -->|"Implements the AnalysisJobData contract to ensure consistent processing of code metadata and risk s…"| 1__1_4
end
subgraph 2["AI Analysis Engine"]
2__2_1["AI Detection Engine"]
2__2_2["Risk Assessment Engine"]
2__2_3["Safety Alerting & Policy Evaluator"]
2__2_1 -->|"provides raw AI confidence scores and heuristic signals to"| 2__2_2
2__2_2 -->|"passes categorized risk tiers and impact scores to"| 2__2_3
2__2_1 -->|"calls"| 2__2_3
end
subgraph 3["Metrics & Background Jobs"]
3__3_1["Metrics Aggregation Engine"]
3__3_2["Asynchronous Worker Pipeline"]
3__3_2 -->|"Processes and persists the granular event data that serves as the primary raw input for scheduled m…"| 3__3_1
end
subgraph 4["Alerting & Notification System"]
4__4_1["Alert Evaluation Engine"]
4__4_2["Heuristic Rules Engine"]
4__4_3["Notification Dispatcher"]
4__4_4["Integration Adapters"]
4__4_5["Alert Management Interface"]
4__4_1 -->|"passes repository metrics to the rules engine to determine if any risk thresholds have been breached"| 4__4_2
4__4_1 -->|"enqueues a task in the notificationQueue for asynchronous processing upon creating a new, non-dupli…"| 4__4_3
4__4_3 -->|"invokes specific adapters based on the alert's target channels to perform the final delivery to ext…"| 4__4_4
4__4_5 -->|"queries the alert records generated by the engine and provides the interface for users to update al…"| 4__4_1
4__4_1 -->|"calls"| 4__4_4
4__4_2 -->|"calls"| 4__4_1
4__4_2 -->|"calls"| 4__4_3
4__4_2 -->|"calls"| 4__4_4
4__4_3 -->|"calls"| 4__4_2
4__4_5 -->|"calls"| 4__4_4
end
subgraph 5["API Gateway"]
5__5_1["Gateway Core"]
5__5_2["Risk Analytics API"]
5__5_3["Issue Management API"]
5__5_4["Activity Stream API"]
5__5_1 -->|"Provides the base procedure factories and Drizzle database context required for metrics queries."| 5__5_2
5__5_1 -->|"Provides the base procedure factories and Drizzle database context required for alert and incident …"| 5__5_3
5__5_1 -->|"Provides the base procedure factories and Drizzle database context required for event feed retrieva…"| 5__5_4
5__5_3 -->|"Correlates security incidents with AI-risk metrics and code attribution data to provide context for…"| 5__5_2
5__5_3 -->|"Links specific alerts to the underlying code events in the activity timeline that triggered the ale…"| 5__5_4
end
subgraph 6["Dashboard UI"]
6__6_1["Application Shell & Navigation"]
6__6_2["Page Controllers & Data Orchestration"]
6__6_3["Visual Design System & Data Presentation"]
6__6_1 -->|"Provides layout context and global providers"| 6__6_2
6__6_2 -->|"Passes fetched data into UI components for visualization"| 6__6_3
end
subgraph 7["Data Persistence Layer"]
7__7_1["Relational Schema & Connection Management"]
7__7_2["Data Integrity & Pre-Persistence Processing"]
7__7_2 -->|"Provides sanitized and standardized data strings to be stored within the schema-defined tables, ens…"| 7__7_1
end
1 -->|"Triggers asynchronous code analysis jobs upon receiving new PR events."| 2
1 -->|"Persists raw webhook payloads and initial event records."| 7
2 -->|"Updates event records with AI detection scores and risk classifications."| 7
2 -->|"Triggers immediate alerts for high-risk code changes."| 4
3 -->|"Reads historical events to compute and store aggregated repo_metrics."| 7
3 -->|"Evaluates threshold-based rules and dispatches alerts."| 4
5 -->|"Executes queries to fetch pre-computed metrics and alert history."| 7
6 -->|"Consumes tRPC procedures to populate charts and tables with real-time data."| 5
4 -->|"Logs dispatched notifications and tracks alert acknowledgment status."| 7
6 -->|"calls"| 1
Sentinel's architecture is designed as a linear processing pipeline that transforms raw code events into actionable engineering insights. The flow begins with the Ingestion & Worker Pipeline, which captures GitHub webhooks and orchestrates asynchronous tasks. These tasks are routed to the AI Analysis Engine for risk assessment and the Metrics & Background Jobs component for long-term trend aggregation. Both processing components feed into the Alerting & Notification System to trigger external integrations like Slack. The entire state is managed by the Data Persistence Layer, which serves as the source of truth for the API Gateway and the Dashboard UI, enabling real-time visibility into AI-generated code risks and reviewer saturation.
The entry point for the system, responsible for receiving external webhooks, verifying signatures, and managing the BullMQ-based job queue for downstream processing.
- Webhook Ingestion Gateway — Acts as the secure entry point for the system, receiving raw HTTP POST requests from GitHub.
- Event Triage & Dispatcher — The first worker stage in the pipeline.
- Deep Analysis Engine — Executes the core logic of the pipeline by performing detailed code analysis.
- Pipeline Messaging Protocol — Defines the standardized data structures and job interfaces used across the BullMQ pipeline.
The core intelligence layer that applies heuristic signals and risk classification logic to code changes to detect AI involvement and assess potential safety impacts.
- AI Detection Engine — Orchestrates a suite of heuristic detectors to identify AI involvement in code changes.
- Risk Assessment Engine — Evaluates the potential safety impact of detected AI code by mapping changes to specific risk tiers (T1 to T4).
- Safety Alerting & Policy Evaluator — Translates analysis results into actionable organizational responses.
Handles scheduled aggregation of raw event data into high-level repository metrics, such as reviewer saturation and survival rates, optimized for dashboard performance.
- Metrics Aggregation Engine — Orchestrates the periodic transformation of raw event data into high-level repository health metrics.
- Asynchronous Worker Pipeline — Manages the execution environment and operational lifecycle for event-driven background tasks.
Evaluates business rules against processed data and dispatches notifications to external platforms like Slack, PagerDuty, and Email.
- Alert Evaluation Engine — The central orchestrator of the alerting lifecycle.
- Heuristic Rules Engine — A functional logic layer containing the business rules for risk detection.
- Notification Dispatcher — An asynchronous delivery system built on BullMQ.
- Integration Adapters — The translation layer between Sentinel's internal alert model and external platform APIs.
- Alert Management Interface — The user-facing dashboard and API layer.
A tRPC-based communication layer that provides secure, type-safe access to alerts, metrics, and incident data for the frontend.
- Gateway Core — Provides the foundational tRPC infrastructure, including server initialization, middleware for authentication/authorization, and the root appRouter that aggregates all domain-specific procedures into a single type-safe API.
- Risk Analytics API — Delivers pre-computed metrics and risk assessments, surfacing repository health snapshots and identifying high-risk files based on AI attribution and "verification tax" heuristics.
- Issue Management API — Manages the lifecycle of alerts and security incidents, providing filtered views of system anomalies and allowing users to perform mutations such as acknowledging alerts or investigating incident root causes.
- Activity Stream API — Provides a paginated, cursor-based feed of raw code events (commits, pull requests, deployments), serving as the historical timeline for all repository activity and the basis for risk analysis.
The Next.js presentation layer that visualizes risk metrics, trends, and alert tables for engineering managers.
- Application Shell & Navigation — Defines the structural framework and global state of the dashboard, managing the root layout, authentication/tRPC providers, and persistent sidebar navigation.
- Page Controllers & Data Orchestration — Acts as the controller layer within the Next.js App Router, responsible for route-level logic, fetching data from the backend via tRPC, and orchestrating the layout of metrics and alerts.
- Visual Design System & Data Presentation — A modular library of reusable UI components and complex organisms designed for data visualization, including risk badges, alerts tables, and trend charts.
Manages the PostgreSQL database schema via Drizzle ORM, providing the foundational storage for events, metrics, and system configuration.
- Relational Schema & Connection Management — Manages the database schema definitions, relational constraints, and the operational lifecycle of the PostgreSQL connection pool.
- Data Integrity & Pre-Persistence Processing — Acts as a gatekeeper for data quality by providing string manipulation and security utilities.