# vaishnavsreekumar/sentinelfinops architecture

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

- Interactive diagram: https://gitdiagram.com/vaishnavsreekumar/sentinelfinops
- Repository: https://github.com/vaishnavsreekumar/sentinelfinops

## Overview

SentinelFinOps scans AWS accounts for idle EC2 instances and unattached EBS volumes, estimates savings, and routes findings through optional AI reasoning and deterministic policy checks before Slack alerting. Engineers can acknowledge, snooze, or trigger backed-up remediation through Slack actions. The graph also captures documented reporting and governance capabilities. The README describes orchestration not fully present in sampled source, so those documented links are shown; uncertain implementation details are omitted.

Main entry points: [`scanner/run_scan.py`](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/run_scan.py) (Scan Orchestrator), [`server.py`](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/server.py) (Action Endpoint), [`ai/runtime.py`](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/runtime.py) (AI Runtime), [`storage/remediation_manager.py`](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/remediation_manager.py) (EC2 Remediation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Scanning"]
  node_scanner["Scan Orchestrator<br/>[run_scan.py]"]
  node_discovery_accounts["Account Discovery"]
  node_sessions["Account Sessions<br/>[account_session.py]"]
  node_ec2["EC2 Scanner<br/>[ec2_scanner.py]"]
  node_ebs["EBS Scanner<br/>[ebs_scanner.py]"]
  node_idle["Idle Analysis<br/>[idle_engine.py]"]
end

subgraph group_governance["AI Governance"]
  node_runtime["AI Runtime<br/>[runtime.py]"]
  node_context["Context Builder<br/>[context_builder.py]"]
  node_gateway["AI Gateway<br/>[gateway.py]"]
  node_providers["Model Providers<br/>[factory.py]"]
  node_policy["Policy Engine<br/>[engine.py]"]
  node_rules["Policy Rules"]
end

subgraph group_response["Alerts and Remediation"]
  node_notifier["Slack Notifier<br/>[notifier.py]"]
  node_actions["Action Endpoint<br/>[server.py]"]
  node_ec2_remediation["EC2 Remediation"]
  node_ebs_remediation["EBS Remediation"]
end

subgraph group_state["State and Telemetry"]
  node_locks[("Remediation Locks")]
  node_state_store[("Alert and Snooze State")]
  node_ledger[("Audit and Remediation Ledger<br/>[audit_logger.py]")]
end

subgraph group_operations["Operations"]
  node_cli["CLI Runner<br/>[main.py]"]
  node_reports["Savings Reports<br/>[savings_report.py]"]
  node_bootstrap["Account Bootstrap"]
end

node_schedule(("Scheduled Trigger"))
node_slack(("Slack"))
node_dynamodb[("DynamoDB")]
node_aws(("AWS Accounts"))

node_schedule -->|"triggers scan"| node_scanner
node_cli -->|"runs scan"| node_scanner
node_scanner -->|"discovers accounts"| node_discovery_accounts
node_scanner -->|"assumes roles"| node_sessions
node_scanner -->|"scans instances"| node_ec2
node_scanner -->|"scans volumes"| node_ebs
node_scanner -->|"checks utilization"| node_idle
node_discovery_accounts -->|"queries Organizations"| node_aws
node_sessions -->|"assumes member roles"| node_aws
node_ec2 -->|"reads EC2 metrics"| node_aws
node_ebs -->|"reads EBS resources"| node_aws
node_scanner -->|"checks alert state"| node_state_store
node_scanner -->|"sends ScanContext"| node_runtime
node_runtime -->|"builds context"| node_context
node_runtime -->|"requests suggestions"| node_gateway
node_gateway -->|"dispatches prompts"| node_providers
node_runtime -->|"validates recommendations"| node_policy
node_policy -->|"evaluates rules"| node_rules
node_scanner -->|"dispatches findings"| node_notifier
node_notifier -->|"sends alerts"| node_slack
node_slack -->|"posts actions"| node_actions
node_actions -->|"updates state"| node_state_store
node_actions -->|"requests stop"| node_ec2_remediation
node_actions -->|"requests deletion"| node_ebs_remediation
node_ec2_remediation -->|"acquires lock"| node_locks
node_ebs_remediation -->|"acquires lock"| node_locks
node_ec2_remediation -->|"backs up and stops"| node_aws
node_ebs_remediation -->|"snapshots and deletes"| node_aws
node_ec2_remediation -->|"records remediation"| node_ledger
node_ebs_remediation -->|"records remediation"| node_ledger
node_actions -->|"logs actions"| node_ledger
node_state_store -->|"reads and writes"| node_dynamodb
node_locks -->|"coordinates locks"| node_dynamodb
node_ledger -->|"persists records"| node_dynamodb
node_cli -->|"runs reports"| node_reports
node_reports -->|"reads savings history"| node_dynamodb
node_cli -->|"bootstraps accounts"| node_bootstrap
node_bootstrap -->|"configures member roles"| node_aws

click node_cli "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/main.py"
click node_scanner "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/run_scan.py"
click node_discovery_accounts "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/account_discovery.py"
click node_sessions "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/account_session.py"
click node_ec2 "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/ec2_scanner.py"
click node_ebs "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/ebs_scanner.py"
click node_idle "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/engine/idle_engine.py"
click node_runtime "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/runtime.py"
click node_context "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/context_builder.py"
click node_gateway "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/gateway.py"
click node_providers "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/providers/factory.py"
click node_policy "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/policy/engine.py"
click node_rules "https://github.com/vaishnavsreekumar/sentinelfinops/tree/main/policy/rules"
click node_notifier "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/notifications/notifier.py"
click node_actions "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/server.py"
click node_ec2_remediation "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/remediation_manager.py"
click node_ebs_remediation "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/ebs_remediation_manager.py"
click node_locks "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/remediation_lock.py"
click node_state_store "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/alert_state_manager.py"
click node_ledger "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/audit_logger.py"
click node_reports "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/reporting/savings_report.py"
click node_bootstrap "https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/bootstrap/bootstrap_accounts.py"

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_scanner,node_discovery_accounts,node_sessions,node_ec2,node_ebs,node_idle toneBlue
class node_runtime,node_context,node_gateway,node_providers,node_policy,node_rules,node_dynamodb toneAmber
class node_notifier,node_actions,node_ec2_remediation,node_ebs_remediation toneMint
class node_locks,node_state_store,node_ledger toneRose
class node_cli,node_reports,node_bootstrap,node_schedule,node_slack,node_aws toneIndigo
```

## Components

### Scanning

- [Scan Orchestrator](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/run_scan.py): `scanner/run_scan.py`
- [Account Discovery](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/account_discovery.py): `scanner/account_discovery.py`
- [Account Sessions](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/account_session.py): `scanner/account_session.py`
- [EC2 Scanner](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/ec2_scanner.py): `scanner/ec2_scanner.py`
- [EBS Scanner](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/scanner/ebs_scanner.py): `scanner/ebs_scanner.py`
- [Idle Analysis](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/engine/idle_engine.py): `engine/idle_engine.py`

### AI Governance

- [AI Runtime](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/runtime.py): `ai/runtime.py`
- [Context Builder](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/context_builder.py): `ai/context_builder.py`
- [AI Gateway](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/gateway.py): `ai/gateway.py`
- [Model Providers](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/ai/providers/factory.py): `ai/providers/factory.py`
- [Policy Engine](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/policy/engine.py): `policy/engine.py`
- [Policy Rules](https://github.com/vaishnavsreekumar/sentinelfinops/tree/main/policy/rules): `policy/rules`

### Alerts and Remediation

- [Slack Notifier](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/notifications/notifier.py): `notifications/notifier.py`
- [Action Endpoint](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/server.py): `server.py`
- [EC2 Remediation](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/remediation_manager.py): `storage/remediation_manager.py`
- [EBS Remediation](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/ebs_remediation_manager.py): `storage/ebs_remediation_manager.py`

### State and Telemetry

- [Remediation Locks](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/remediation_lock.py): `storage/remediation_lock.py`
- [Alert and Snooze State](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/alert_state_manager.py): `storage/alert_state_manager.py`
- [Audit and Remediation Ledger](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/storage/audit_logger.py): `storage/audit_logger.py`

### Operations

- [CLI Runner](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/main.py): `main.py`
- [Savings Reports](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/reporting/savings_report.py): `reporting/savings_report.py`
- [Account Bootstrap](https://github.com/vaishnavsreekumar/sentinelfinops/blob/main/bootstrap/bootstrap_accounts.py): `bootstrap/bootstrap_accounts.py`

### Other components

- **Scheduled Trigger**
- **Slack**
- **DynamoDB**
- **AWS Accounts**

## Connections

- Scheduled Trigger → Scan Orchestrator: triggers scan
- CLI Runner → Scan Orchestrator: runs scan
- Scan Orchestrator → Account Discovery: discovers accounts
- Scan Orchestrator → Account Sessions: assumes roles
- Scan Orchestrator → EC2 Scanner: scans instances
- Scan Orchestrator → EBS Scanner: scans volumes
- Scan Orchestrator → Idle Analysis: checks utilization
- Account Discovery → AWS Accounts: queries Organizations
- Account Sessions → AWS Accounts: assumes member roles
- EC2 Scanner → AWS Accounts: reads EC2 metrics
- EBS Scanner → AWS Accounts: reads EBS resources
- Scan Orchestrator → Alert and Snooze State: checks alert state
- Scan Orchestrator → AI Runtime: sends ScanContext
- AI Runtime → Context Builder: builds context
- AI Runtime → AI Gateway: requests suggestions
- AI Gateway → Model Providers: dispatches prompts
- AI Runtime → Policy Engine: validates recommendations
- Policy Engine → Policy Rules: evaluates rules
- Scan Orchestrator → Slack Notifier: dispatches findings
- Slack Notifier → Slack: sends alerts
- Slack → Action Endpoint: posts actions
- Action Endpoint → Alert and Snooze State: updates state
- Action Endpoint → EC2 Remediation: requests stop
- Action Endpoint → EBS Remediation: requests deletion
- EC2 Remediation → Remediation Locks: acquires lock
- EBS Remediation → Remediation Locks: acquires lock
- EC2 Remediation → AWS Accounts: backs up and stops
- EBS Remediation → AWS Accounts: snapshots and deletes
- EC2 Remediation → Audit and Remediation Ledger: records remediation
- EBS Remediation → Audit and Remediation Ledger: records remediation
- Action Endpoint → Audit and Remediation Ledger: logs actions
- Alert and Snooze State → DynamoDB: reads and writes
- Remediation Locks → DynamoDB: coordinates locks
- Audit and Remediation Ledger → DynamoDB: persists records
- CLI Runner → Savings Reports: runs reports
- Savings Reports → DynamoDB: reads savings history
- CLI Runner → Account Bootstrap: bootstraps accounts
- Account Bootstrap → AWS Accounts: configures member roles