# mizcausevic-dev/rag-sentinel architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/rag-sentinel
- Repository: https://github.com/mizcausevic-dev/rag-sentinel

## Overview

RAG Sentinel is an API-based governance and observability layer for enterprise retrieval collections. Operators inspect collection posture, fleet summaries, and incidents, while validation capabilities cover chunk quality, freshness, retrieval drift, answer grounding, and sensitive-content scanning. A separate vault workflow uses Decision Card permissions to replace authorized PII with tokens before indexing and preview role-gated detokenization. The route, posture, collection, and vault wiring shown is supported by sampled source; validation details are primarily documented in the README and route/schema paths, whose internal calls were not sampled.

Main entry points: [`src/routes/vault.ts`](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/vault.ts) (Vault preview API), [`src/index.ts`](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/index.ts) (HTTP application), [`src/routes/index.ts`](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/index.ts) (Operations APIs), [`src/governance/vault-chunk.ts`](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/vault-chunk.ts) (Tokenize chunks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and operations"]
  node_app["HTTP application<br/>[index.ts]"]
  node_validation["Validation API<br/>[validate.ts]"]
  node_operations["Operations APIs<br/>[index.ts]"]
  node_schemas["Input schemas"]
end

subgraph group_governance["Governance checks"]
  node_chunk["Chunk quality<br/>[chunk-quality.ts]"]
  node_freshness["Source freshness<br/>[freshness.ts]"]
  node_drift["Retrieval drift<br/>[retrieval-drift.ts]"]
  node_grounding["Hallucination signals<br/>[hallucination.ts]"]
  node_pii["PII scanning<br/>[pii-scanner.ts]"]
  node_posture["Composite posture<br/>[posture.ts]"]
end

subgraph group_vault["Vault integration"]
  node_vaultapi["Vault preview API<br/>[vault.ts]"]
  node_decision["Decision Card parser<br/>[decision-card.ts]"]
  node_vaultchunk["Tokenize chunks<br/>[vault-chunk.ts]"]
  node_vaulttypes["Vault contract<br/>[types.ts]"]
  node_mockvault["Mock vault<br/>[mock-vault.ts]"]
  node_realvault["HTTP vault adapter<br/>[real-vault.ts]"]
end

subgraph group_state["Collection state"]
  node_collections["RAG collections<br/>[collections.ts]"]
  node_incidents["Incident records<br/>[incidents.ts]"]
end

node_operator(("Operator"))
node_skyyflow["Skyyflow vault"]

node_operator -->|"sends requests"| node_app
node_app -->|"dispatches validation"| node_validation
node_app -->|"dispatches operations"| node_operations
node_app -->|"dispatches vault"| node_vaultapi
node_operations -->|"reads collections"| node_collections
node_operations -->|"reads incidents"| node_incidents
node_operations -->|"evaluates posture"| node_posture
node_posture -->|"reads metrics"| node_collections
node_validation -->|"validates inputs"| node_schemas
node_vaultapi -->|"parses card"| node_decision
node_vaultapi -->|"vaults chunks"| node_vaultchunk
node_vaultchunk -->|"scans chunks"| node_pii
node_vaultchunk -->|"uses contract"| node_vaulttypes
node_vaultapi -->|"selects fallback"| node_mockvault
node_vaultapi -.->|"selects if configured"| node_realvault
node_mockvault -->|"implements contract"| node_vaulttypes
node_realvault -->|"implements contract"| node_vaulttypes
node_realvault -.->|"sends vault requests"| node_skyyflow

click node_app "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/index.ts"
click node_validation "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/validate.ts"
click node_operations "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/index.ts"
click node_schemas "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/schemas/validation-schemas.ts"
click node_collections "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/data/collections.ts"
click node_incidents "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/data/incidents.ts"
click node_chunk "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/chunk-quality.ts"
click node_freshness "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/freshness.ts"
click node_drift "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/retrieval-drift.ts"
click node_grounding "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/hallucination.ts"
click node_pii "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/pii-scanner.ts"
click node_posture "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/posture.ts"
click node_vaultapi "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/vault.ts"
click node_decision "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/decision-card.ts"
click node_vaultchunk "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/vault-chunk.ts"
click node_vaulttypes "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/types.ts"
click node_mockvault "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/mock-vault.ts"
click node_realvault "https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/real-vault.ts"

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_app,node_validation,node_operations,node_schemas toneBlue
class node_chunk,node_freshness,node_drift,node_grounding,node_pii,node_posture toneAmber
class node_vaultapi,node_decision,node_vaultchunk,node_vaulttypes,node_mockvault,node_realvault toneMint
class node_collections,node_incidents toneRose
class node_operator,node_skyyflow toneIndigo
```

## Components

### API and operations

- [HTTP application](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/index.ts): `src/index.ts`
- [Validation API](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/validate.ts): `src/routes/validate.ts`
- [Operations APIs](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Input schemas](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/schemas/validation-schemas.ts): `src/schemas/validation-schemas.ts`

### Governance checks

- [Chunk quality](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/chunk-quality.ts): `src/governance/chunk-quality.ts`
- [Source freshness](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/freshness.ts): `src/governance/freshness.ts`
- [Retrieval drift](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/retrieval-drift.ts): `src/governance/retrieval-drift.ts`
- [Hallucination signals](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/hallucination.ts): `src/governance/hallucination.ts`
- [PII scanning](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/pii-scanner.ts): `src/governance/pii-scanner.ts`
- [Composite posture](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/posture.ts): `src/governance/posture.ts`

### Vault integration

- [Vault preview API](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/routes/vault.ts): `src/routes/vault.ts`
- [Decision Card parser](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/decision-card.ts): `src/vault/decision-card.ts`
- [Tokenize chunks](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/governance/vault-chunk.ts): `src/governance/vault-chunk.ts`
- [Vault contract](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/types.ts): `src/vault/types.ts`
- [Mock vault](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/mock-vault.ts): `src/vault/mock-vault.ts`
- [HTTP vault adapter](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/vault/real-vault.ts): `src/vault/real-vault.ts`

### Collection state

- [RAG collections](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/data/collections.ts): `src/data/collections.ts`
- [Incident records](https://github.com/mizcausevic-dev/rag-sentinel/blob/main/src/data/incidents.ts): `src/data/incidents.ts`

### Other components

- **Operator**
- **Skyyflow vault**

## Connections

- Operator → HTTP application: sends requests
- HTTP application → Validation API: dispatches validation
- HTTP application → Operations APIs: dispatches operations
- HTTP application → Vault preview API: dispatches vault
- Operations APIs → RAG collections: reads collections
- Operations APIs → Incident records: reads incidents
- Operations APIs → Composite posture: evaluates posture
- Composite posture → RAG collections: reads metrics
- Validation API → Input schemas: validates inputs
- Vault preview API → Decision Card parser: parses card
- Vault preview API → Tokenize chunks: vaults chunks
- Tokenize chunks → PII scanning: scans chunks
- Tokenize chunks → Vault contract: uses contract
- Vault preview API → Mock vault: selects fallback
- Vault preview API → HTTP vault adapter: selects if configured
- Mock vault → Vault contract: implements contract
- HTTP vault adapter → Vault contract: implements contract
- HTTP vault adapter → Skyyflow vault: sends vault requests