# ajay-1011-git/kaaval architecture

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

- Interactive diagram: https://gitdiagram.com/ajay-1011-git/kaaval
- Repository: https://github.com/ajay-1011-git/kaaval

## Overview

KAAVAL protects browser sessions against stolen-cookie replay with per-request PulseLock proofs, and also provides deterministic security assessment and policy services plus an incident dashboard. The principal workflow is passkey login and session-key binding, followed by nonce-backed signing and gateway verification; resulting security events feed the live dashboard and Chronicle. The graph includes README-documented Radar, Guardian, and attacker demonstrations. Some subsystem wiring is represented only where explicit in the README or sampled routes; unsampled implementation details are omitted.

Main entry points: [`backend/main.py`](https://github.com/ajay-1011-git/kaaval/blob/main/backend/main.py) (Gateway app), [`backend/db.py`](https://github.com/ajay-1011-git/kaaval/blob/main/backend/db.py) (SQLite state), [`frontend/app/page.tsx`](https://github.com/ajay-1011-git/kaaval/blob/main/frontend/app/page.tsx) (Dashboard), [`sdk/src/client.ts`](https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/client.ts) (Signed fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["PulseLock SDK"]
  node_sdk_keys["Session keys<br/>[keys.ts]"]
  node_sdk_webauthn["Passkey ceremonies<br/>[webauthn.ts]"]
  node_sdk_client["Signed fetch<br/>[client.ts]"]
  node_sdk_canonical["Request canonicalization<br/>[canonical.ts]"]
end

subgraph group_gateway["Gateway security"]
  node_gateway_app["Gateway app<br/>[main.py]"]
  node_webauthn["WebAuthn routes<br/>[webauthn_routes.py]"]
  node_nonce["Nonce issuance<br/>[nonce.py]"]
  node_demo_routes["Protected demo app<br/>[demo_app_routes.py]"]
  node_verification["Proof verification<br/>[verify.py]"]
  node_event_bus["Event writing<br/>[events.py]"]
  node_event_store[("SQLite state<br/>[db.py]")]
  node_event_stream["SSE stream<br/>[events_stream.py]"]
end

subgraph group_services["Security services"]
  node_radar_routes["Radar reports<br/>[routes.py]"]
  node_radar_scoring["Exposure scoring<br/>[scoring.py]"]
  node_guardian_routes["Guardian evaluation<br/>[routes.py]"]
  node_guardian_oauth["OAuth policy<br/>[oauth_policy.py]"]
  node_guardian_device["Device-code policy"]
  node_chronicle_routes["Incident narration<br/>[routes.py]"]
  node_chronicle_fallback["Deterministic fallback<br/>[fallback.py]"]
end

subgraph group_dashboard["Dashboard and narration"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_event_client["Live event client<br/>[eventsClient.ts]"]
  node_chronicle_client["Chronicle client<br/>[chronicleClient.ts]"]
end

subgraph group_demo["Attack demonstration"]
  node_attacker_tools["Attacker consoles"]
end

node_browser_user(("Browser user"))
node_groq["Groq API"]

node_browser_user -->|"starts passkey login"| node_sdk_webauthn
node_sdk_webauthn -->|"binds session key"| node_sdk_keys
node_sdk_webauthn -->|"registers or logs in"| node_webauthn
node_webauthn -->|"stores credentials and sessions"| node_event_store
node_sdk_client -->|"gets active session"| node_sdk_webauthn
node_sdk_client -->|"requests nonce"| node_nonce
node_sdk_client -->|"builds signed envelope"| node_sdk_canonical
node_sdk_client -->|"sends proof-bearing request"| node_demo_routes
node_browser_user -->|"makes protected request"| node_sdk_client
node_gateway_app -->|"mounts routes"| node_webauthn
node_gateway_app -->|"mounts routes"| node_nonce
node_gateway_app -->|"mounts routes"| node_demo_routes
node_gateway_app -->|"mounts routes"| node_radar_routes
node_gateway_app -->|"mounts routes"| node_guardian_routes
node_gateway_app -->|"mounts routes"| node_chronicle_routes
node_demo_routes -->|"verifies protected request"| node_verification
node_verification -->|"writes decision event"| node_event_bus
node_demo_routes -->|"records transfer"| node_event_store
node_event_bus -->|"persists events"| node_event_store
node_nonce -->|"stores nonce state"| node_event_store
node_radar_routes -->|"generates report"| node_radar_scoring
node_guardian_routes -->|"evaluates consent"| node_guardian_oauth
node_guardian_routes -->|"evaluates device code"| node_guardian_device
node_guardian_routes -->|"records decisions"| node_event_bus
node_chronicle_routes -->|"loads selected events"| node_event_store
node_chronicle_routes -->|"uses on failure or fallback mode"| node_chronicle_fallback
node_chronicle_routes -.->|"requests live narrative"| node_groq
node_browser_user -->|"views security status"| node_dashboard
node_dashboard -->|"requests report"| node_radar_routes
node_dashboard -->|"submits policy checks"| node_guardian_routes
node_dashboard -->|"subscribes to events"| node_event_client
node_event_client -->|"opens SSE connection"| node_event_stream
node_event_stream -->|"polls event history"| node_event_store
node_dashboard -->|"requests explanation"| node_chronicle_client
node_chronicle_client -->|"posts event IDs"| node_chronicle_routes
node_attacker_tools -->|"replays attack requests"| node_demo_routes

click node_sdk_keys "https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/keys.ts"
click node_sdk_webauthn "https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/webauthn.ts"
click node_sdk_client "https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/client.ts"
click node_sdk_canonical "https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/canonical.ts"
click node_gateway_app "https://github.com/ajay-1011-git/kaaval/blob/main/backend/main.py"
click node_webauthn "https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/webauthn_routes.py"
click node_nonce "https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/nonce.py"
click node_demo_routes "https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/demo_app_routes.py"
click node_verification "https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/verify.py"
click node_event_bus "https://github.com/ajay-1011-git/kaaval/blob/main/backend/events.py"
click node_event_store "https://github.com/ajay-1011-git/kaaval/blob/main/backend/db.py"
click node_event_stream "https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/events_stream.py"
click node_radar_routes "https://github.com/ajay-1011-git/kaaval/blob/main/backend/radar/routes.py"
click node_radar_scoring "https://github.com/ajay-1011-git/kaaval/blob/main/backend/radar/scoring.py"
click node_guardian_routes "https://github.com/ajay-1011-git/kaaval/blob/main/backend/guardian/routes.py"
click node_guardian_oauth "https://github.com/ajay-1011-git/kaaval/blob/main/backend/guardian/oauth_policy.py"
click node_guardian_device "https://github.com/ajay-1011-git/kaaval/blob/main/backend/guardian/device_code_policy.py"
click node_chronicle_routes "https://github.com/ajay-1011-git/kaaval/blob/main/backend/chronicle/routes.py"
click node_chronicle_fallback "https://github.com/ajay-1011-git/kaaval/blob/main/backend/chronicle/fallback.py"
click node_dashboard "https://github.com/ajay-1011-git/kaaval/blob/main/frontend/app/page.tsx"
click node_event_client "https://github.com/ajay-1011-git/kaaval/blob/main/frontend/lib/eventsClient.ts"
click node_chronicle_client "https://github.com/ajay-1011-git/kaaval/blob/main/frontend/lib/chronicleClient.ts"
click node_attacker_tools "https://github.com/ajay-1011-git/kaaval/tree/main/demo-tools/attacker"

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_sdk_keys,node_sdk_webauthn,node_sdk_client,node_sdk_canonical,node_browser_user toneBlue
class node_gateway_app,node_webauthn,node_nonce,node_demo_routes,node_verification,node_event_bus,node_event_store,node_event_stream toneAmber
class node_radar_routes,node_radar_scoring,node_guardian_routes,node_guardian_oauth,node_guardian_device,node_chronicle_routes,node_chronicle_fallback,node_groq toneMint
class node_dashboard,node_event_client,node_chronicle_client toneRose
class node_attacker_tools toneIndigo
```

## Components

### PulseLock SDK

- [Session keys](https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/keys.ts): `sdk/src/keys.ts`
- [Passkey ceremonies](https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/webauthn.ts): `sdk/src/webauthn.ts`
- [Signed fetch](https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/client.ts): `sdk/src/client.ts`
- [Request canonicalization](https://github.com/ajay-1011-git/kaaval/blob/main/sdk/src/canonical.ts): `sdk/src/canonical.ts`

### Gateway security

- [Gateway app](https://github.com/ajay-1011-git/kaaval/blob/main/backend/main.py): `backend/main.py`
- [WebAuthn routes](https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/webauthn_routes.py): `backend/gateway/webauthn_routes.py`
- [Nonce issuance](https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/nonce.py): `backend/gateway/nonce.py`
- [Protected demo app](https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/demo_app_routes.py): `backend/gateway/demo_app_routes.py`
- [Proof verification](https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/verify.py): `backend/gateway/verify.py`
- [Event writing](https://github.com/ajay-1011-git/kaaval/blob/main/backend/events.py): `backend/events.py`
- [SQLite state](https://github.com/ajay-1011-git/kaaval/blob/main/backend/db.py): `backend/db.py`
- [SSE stream](https://github.com/ajay-1011-git/kaaval/blob/main/backend/gateway/events_stream.py): `backend/gateway/events_stream.py`

### Security services

- [Radar reports](https://github.com/ajay-1011-git/kaaval/blob/main/backend/radar/routes.py): `backend/radar/routes.py`
- [Exposure scoring](https://github.com/ajay-1011-git/kaaval/blob/main/backend/radar/scoring.py): `backend/radar/scoring.py`
- [Guardian evaluation](https://github.com/ajay-1011-git/kaaval/blob/main/backend/guardian/routes.py): `backend/guardian/routes.py`
- [OAuth policy](https://github.com/ajay-1011-git/kaaval/blob/main/backend/guardian/oauth_policy.py): `backend/guardian/oauth_policy.py`
- [Device-code policy](https://github.com/ajay-1011-git/kaaval/blob/main/backend/guardian/device_code_policy.py): `backend/guardian/device_code_policy.py`
- [Incident narration](https://github.com/ajay-1011-git/kaaval/blob/main/backend/chronicle/routes.py): `backend/chronicle/routes.py`
- [Deterministic fallback](https://github.com/ajay-1011-git/kaaval/blob/main/backend/chronicle/fallback.py): `backend/chronicle/fallback.py`

### Dashboard and narration

- [Dashboard](https://github.com/ajay-1011-git/kaaval/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Live event client](https://github.com/ajay-1011-git/kaaval/blob/main/frontend/lib/eventsClient.ts): `frontend/lib/eventsClient.ts`
- [Chronicle client](https://github.com/ajay-1011-git/kaaval/blob/main/frontend/lib/chronicleClient.ts): `frontend/lib/chronicleClient.ts`

### Attack demonstration

- [Attacker consoles](https://github.com/ajay-1011-git/kaaval/tree/main/demo-tools/attacker): `demo-tools/attacker`

### Other components

- **Browser user**
- **Groq API**

## Connections

- Browser user → Passkey ceremonies: starts passkey login
- Passkey ceremonies → Session keys: binds session key
- Passkey ceremonies → WebAuthn routes: registers or logs in
- WebAuthn routes → SQLite state: stores credentials and sessions
- Signed fetch → Passkey ceremonies: gets active session
- Signed fetch → Nonce issuance: requests nonce
- Signed fetch → Request canonicalization: builds signed envelope
- Signed fetch → Protected demo app: sends proof-bearing request
- Browser user → Signed fetch: makes protected request
- Gateway app → WebAuthn routes: mounts routes
- Gateway app → Nonce issuance: mounts routes
- Gateway app → Protected demo app: mounts routes
- Gateway app → Radar reports: mounts routes
- Gateway app → Guardian evaluation: mounts routes
- Gateway app → Incident narration: mounts routes
- Protected demo app → Proof verification: verifies protected request
- Proof verification → Event writing: writes decision event
- Protected demo app → SQLite state: records transfer
- Event writing → SQLite state: persists events
- Nonce issuance → SQLite state: stores nonce state
- Radar reports → Exposure scoring: generates report
- Guardian evaluation → OAuth policy: evaluates consent
- Guardian evaluation → Device-code policy: evaluates device code
- Guardian evaluation → Event writing: records decisions
- Incident narration → SQLite state: loads selected events
- Incident narration → Deterministic fallback: uses on failure or fallback mode
- Incident narration → Groq API: requests live narrative
- Browser user → Dashboard: views security status
- Dashboard → Radar reports: requests report
- Dashboard → Guardian evaluation: submits policy checks
- Dashboard → Live event client: subscribes to events
- Live event client → SSE stream: opens SSE connection
- SSE stream → SQLite state: polls event history
- Dashboard → Chronicle client: requests explanation
- Chronicle client → Incident narration: posts event IDs
- Attacker consoles → Protected demo app: replays attack requests