# shivangis04/vigilant architecture

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

- Interactive diagram: https://gitdiagram.com/shivangis04/vigilant
- Repository: https://github.com/shivangis04/vigilant

## Overview

VIGILANT turns Ring activity into home-specific behavioral patterns, scores them with MOTIF, persists events and baselines, and presents flagged patterns and activity analytics in a polling dashboard. Flagged patterns can receive Bedrock explanations and optional Alexa announcements. The graph also preserves Ring account linking and security capabilities documented by the project. Edges reflect shown calls or README statements; unsampled implementation details are not inferred.

Main entry points: [`backend/api/routes.py`](https://github.com/shivangis04/vigilant/blob/main/backend/api/routes.py) (Dashboard API), [`backend/ring_integration/pipeline.py`](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/pipeline.py) (Event Pipeline), [`frontend/src/App.jsx`](https://github.com/shivangis04/vigilant/blob/main/frontend/src/App.jsx) (Dashboard), [`backend/database/repository.py`](https://github.com/shivangis04/vigilant/blob/main/backend/database/repository.py) (Data Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ring["Ring Integration"]
  node_ring_account["Account Linking<br/>[oauth.py]"]
  node_ring_client["Partner API<br/>[official_client.py]"]
  node_ring_security["Webhook Security<br/>[security.py]"]
  node_ring_normalize["Event Normalization<br/>[normalization.py]"]
  node_simulator["Event Simulator<br/>[api_client.py]"]
end

subgraph group_analysis["Pattern Analysis"]
  node_motif["MOTIF Scoring<br/>[motif_core.py]"]
  node_pipeline["Event Pipeline<br/>[pipeline.py]"]
  node_bedrock["Explanations"]
end

subgraph group_data["Persistence"]
  node_models["Domain Records<br/>[models.py]"]
  node_repository["Data Repository<br/>[repository.py]"]
  node_db_session["Database Sessions<br/>[session.py]"]
end

subgraph group_service["API and Alerts"]
  node_api["Dashboard API<br/>[routes.py]"]
  node_alexa_client["Alexa Notifier<br/>[client.py]"]
  node_alexa_lambda["Alexa Lambda Handler<br/>[lambda_handler.py]"]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard<br/>[App.jsx]"]
  node_hooks["Polling Hooks<br/>[useEvents.js]"]
  node_api_client["Frontend API Client<br/>[api.js]"]
  node_patterns["Pattern Views<br/>[PatternCard.jsx]"]
  node_pattern_detail["Pattern Detail<br/>[PatternDetail.jsx]"]
  node_timeline["Event Timeline<br/>[EventTimeline.jsx]"]
  node_baseline_view["Baseline Analytics"]
end

node_ring_service(("Ring Service"))
node_browser_user(("Homeowner"))
node_aws_bedrock{{"AWS Bedrock"}}
node_aws_lambda{{"AWS Lambda"}}
node_database[("SQL Database")]

node_ring_service -->|"sends webhooks"| node_api
node_api -->|"verifies requests"| node_ring_security
node_api -->|"normalizes events"| node_ring_normalize
node_api -->|"handles linking"| node_ring_account
node_ring_account -->|"exchanges tokens"| node_ring_client
node_ring_account -->|"stores credentials"| node_repository
node_simulator -->|"feeds events"| node_pipeline
node_api -->|"processes events"| node_pipeline
node_pipeline -->|"scores sequences"| node_motif
node_pipeline -->|"explains flagged"| node_bedrock
node_bedrock -->|"requests explanation"| node_aws_bedrock
node_pipeline -->|"saves patterns"| node_repository
node_pipeline -->|"updates baseline"| node_repository
node_pipeline -->|"learns baseline"| node_motif
node_pipeline -->|"sends flagged alerts"| node_alexa_client
node_alexa_client -->|"invokes function"| node_aws_lambda
node_aws_lambda -->|"runs handler"| node_alexa_lambda
node_api -->|"queries and writes"| node_repository
node_api -->|"opens sessions"| node_db_session
node_repository -->|"maps records"| node_models
node_db_session -->|"connects"| node_database
node_browser_user -->|"views activity"| node_dashboard
node_dashboard -->|"loads patterns"| node_hooks
node_dashboard -->|"renders list"| node_patterns
node_dashboard -->|"renders selection"| node_pattern_detail
node_dashboard -->|"renders events"| node_timeline
node_dashboard -->|"renders analytics"| node_baseline_view
node_hooks -->|"fetches data"| node_api_client
node_api_client -->|"requests dashboard data"| node_api
node_timeline -->|"reads events"| node_hooks
node_baseline_view -->|"loads comparison"| node_api_client

click node_ring_account "https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/oauth.py"
click node_ring_client "https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/official_client.py"
click node_ring_security "https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/security.py"
click node_ring_normalize "https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/normalization.py"
click node_simulator "https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/api_client.py"
click node_motif "https://github.com/shivangis04/vigilant/blob/main/backend/motif_engine/motif_core.py"
click node_pipeline "https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/pipeline.py"
click node_bedrock "https://github.com/shivangis04/vigilant/blob/main/backend/bedrock_integration/explanation_generator.py"
click node_models "https://github.com/shivangis04/vigilant/blob/main/backend/database/models.py"
click node_repository "https://github.com/shivangis04/vigilant/blob/main/backend/database/repository.py"
click node_db_session "https://github.com/shivangis04/vigilant/blob/main/backend/database/session.py"
click node_api "https://github.com/shivangis04/vigilant/blob/main/backend/api/routes.py"
click node_alexa_client "https://github.com/shivangis04/vigilant/blob/main/backend/alexa_integration/client.py"
click node_alexa_lambda "https://github.com/shivangis04/vigilant/blob/main/backend/alexa_integration/lambda_handler.py"
click node_dashboard "https://github.com/shivangis04/vigilant/blob/main/frontend/src/App.jsx"
click node_hooks "https://github.com/shivangis04/vigilant/blob/main/frontend/src/hooks/useEvents.js"
click node_api_client "https://github.com/shivangis04/vigilant/blob/main/frontend/src/utils/api.js"
click node_patterns "https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/PatternCard.jsx"
click node_pattern_detail "https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/PatternDetail.jsx"
click node_timeline "https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/EventTimeline.jsx"
click node_baseline_view "https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/BaselineComparison.jsx"

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_ring_account,node_ring_client,node_ring_security,node_ring_normalize,node_simulator toneBlue
class node_motif,node_pipeline,node_bedrock,node_database toneAmber
class node_models,node_repository,node_db_session toneMint
class node_api,node_alexa_client,node_alexa_lambda toneRose
class node_dashboard,node_hooks,node_api_client,node_patterns,node_pattern_detail,node_timeline,node_baseline_view,node_ring_service,node_browser_user,node_aws_bedrock,node_aws_lambda toneIndigo
```

## Components

### Ring Integration

- [Account Linking](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/oauth.py): `backend/ring_integration/oauth.py`
- [Partner API](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/official_client.py): `backend/ring_integration/official_client.py`
- [Webhook Security](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/security.py): `backend/ring_integration/security.py`
- [Event Normalization](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/normalization.py): `backend/ring_integration/normalization.py`
- [Event Simulator](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/api_client.py): `backend/ring_integration/api_client.py`

### Pattern Analysis

- [MOTIF Scoring](https://github.com/shivangis04/vigilant/blob/main/backend/motif_engine/motif_core.py): `backend/motif_engine/motif_core.py`
- [Event Pipeline](https://github.com/shivangis04/vigilant/blob/main/backend/ring_integration/pipeline.py): `backend/ring_integration/pipeline.py`
- [Explanations](https://github.com/shivangis04/vigilant/blob/main/backend/bedrock_integration/explanation_generator.py): `backend/bedrock_integration/explanation_generator.py`

### Persistence

- [Domain Records](https://github.com/shivangis04/vigilant/blob/main/backend/database/models.py): `backend/database/models.py`
- [Data Repository](https://github.com/shivangis04/vigilant/blob/main/backend/database/repository.py): `backend/database/repository.py`
- [Database Sessions](https://github.com/shivangis04/vigilant/blob/main/backend/database/session.py): `backend/database/session.py`

### API and Alerts

- [Dashboard API](https://github.com/shivangis04/vigilant/blob/main/backend/api/routes.py): `backend/api/routes.py`
- [Alexa Notifier](https://github.com/shivangis04/vigilant/blob/main/backend/alexa_integration/client.py): `backend/alexa_integration/client.py`
- [Alexa Lambda Handler](https://github.com/shivangis04/vigilant/blob/main/backend/alexa_integration/lambda_handler.py): `backend/alexa_integration/lambda_handler.py`

### Dashboard

- [Dashboard](https://github.com/shivangis04/vigilant/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Polling Hooks](https://github.com/shivangis04/vigilant/blob/main/frontend/src/hooks/useEvents.js): `frontend/src/hooks/useEvents.js`
- [Frontend API Client](https://github.com/shivangis04/vigilant/blob/main/frontend/src/utils/api.js): `frontend/src/utils/api.js`
- [Pattern Views](https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/PatternCard.jsx): `frontend/src/components/PatternCard.jsx`
- [Pattern Detail](https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/PatternDetail.jsx): `frontend/src/components/PatternDetail.jsx`
- [Event Timeline](https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/EventTimeline.jsx): `frontend/src/components/EventTimeline.jsx`
- [Baseline Analytics](https://github.com/shivangis04/vigilant/blob/main/frontend/src/components/BaselineComparison.jsx): `frontend/src/components/BaselineComparison.jsx`

### Other components

- **Ring Service**
- **Homeowner**
- **AWS Bedrock**
- **AWS Lambda**
- **SQL Database**

## Connections

- Ring Service → Dashboard API: sends webhooks (evidence: `backend/api/routes.py`)
- Dashboard API → Webhook Security: verifies requests (evidence: `backend/api/routes.py`)
- Dashboard API → Event Normalization: normalizes events (evidence: `backend/api/routes.py`)
- Dashboard API → Account Linking: handles linking (evidence: `backend/api/routes.py`)
- Account Linking → Partner API: exchanges tokens (evidence: `backend/ring_integration/oauth.py`)
- Account Linking → Data Repository: stores credentials (evidence: `backend/ring_integration/oauth.py`)
- Event Simulator → Event Pipeline: feeds events
- Dashboard API → Event Pipeline: processes events (evidence: `backend/api/routes.py`)
- Event Pipeline → MOTIF Scoring: scores sequences (evidence: `backend/ring_integration/pipeline.py`)
- Event Pipeline → Explanations: explains flagged (evidence: `backend/ring_integration/pipeline.py`)
- Explanations → AWS Bedrock: requests explanation (evidence: `README.md`)
- Event Pipeline → Data Repository: saves patterns (evidence: `backend/ring_integration/pipeline.py`)
- Event Pipeline → Data Repository: updates baseline (evidence: `backend/ring_integration/pipeline.py`)
- Event Pipeline → MOTIF Scoring: learns baseline (evidence: `backend/ring_integration/pipeline.py`)
- Event Pipeline → Alexa Notifier: sends flagged alerts (evidence: `backend/ring_integration/pipeline.py`)
- Alexa Notifier → AWS Lambda: invokes function (evidence: `backend/alexa_integration/client.py`)
- AWS Lambda → Alexa Lambda Handler: runs handler (evidence: `README.md`)
- Dashboard API → Data Repository: queries and writes (evidence: `backend/api/routes.py`)
- Dashboard API → Database Sessions: opens sessions (evidence: `backend/api/routes.py`)
- Data Repository → Domain Records: maps records (evidence: `backend/database/repository.py`)
- Database Sessions → SQL Database: connects (evidence: `backend/database/session.py`)
- Homeowner → Dashboard: views activity (evidence: `README.md`)
- Dashboard → Polling Hooks: loads patterns (evidence: `frontend/src/App.jsx`)
- Dashboard → Pattern Views: renders list (evidence: `frontend/src/App.jsx`)
- Dashboard → Pattern Detail: renders selection (evidence: `frontend/src/App.jsx`)
- Dashboard → Event Timeline: renders events (evidence: `frontend/src/App.jsx`)
- Dashboard → Baseline Analytics: renders analytics (evidence: `frontend/src/App.jsx`)
- Polling Hooks → Frontend API Client: fetches data (evidence: `frontend/src/hooks/useEvents.js`)
- Frontend API Client → Dashboard API: requests dashboard data (evidence: `README.md`)
- Event Timeline → Polling Hooks: reads events (evidence: `frontend/src/components/EventTimeline.jsx`)
- Baseline Analytics → Frontend API Client: loads comparison (evidence: `frontend/src/components/BaselineComparison.jsx`)
