# prasad0706/innovahack-localclaude architecture

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

- Interactive diagram: https://gitdiagram.com/prasad0706/innovahack-localclaude
- Repository: https://github.com/prasad0706/innovahack-localclaude

## Overview

#### Purpose and Runtime

Sentinel is a Node.js/MongoDB system for governing agent-driven transactions: authenticate administrators, register agents and credentials, evaluate policy, execute simulated wallet actions, and retain auditable decision traces. A separate Vite/React frontend provides operational dashboards.

Backend startup is `backend/index.js`; frontend startup is `frontend/src/main.jsx` and `frontend/src/App.jsx`. The demo entry point is `backend/scripts/demoRunner.js`.

#### API Composition and System Control

The backend is organized as route-backed domains mounted from the server entry point. System-level state and operational controls—including overview/status and kill-switch-like controls—are concentrated in:
- `backend/index.js`
- `backend/system/systemRoutes.js`
- `backend/system/systemState.js`

These controls form a cross-cutting execution boundary: transaction and workflow processing should observe system state before allowing action.

#### Identity, Agents, and Credentials

Administrator authentication uses JWT-oriented middleware and an admin persistence model:
- `backend/auth/authRoutes.js`
- `backend/auth/authMiddleware.js`
- `backend/auth/Admin.js`

Agents are managed independently through:
- `backend/agents/Agent.js`
- `backend/agents/agentRoutes.js`

Credential management persists credentials and encapsulates credential operations:
- `backend/credential-manager/Credential.js`
- `backend/credential-manager/credentialService.js`
- `backend/credential-manager/credentialRoutes.js`

This separates human/operator authorization, agent identity, and secrets/credential lifecycle.

#### Policy-to-Decision Pipeline

Policies are stored and exposed through a dedicated policy engine:
- `backend/policy-engine/Policy.js`
- `backend/policy-engine/policyEngine.js`
- `backend/policy-engine/policyRoutes.js`

The engine is the primary decision boundary between a requested agent action and execution. Its outputs are surfaced by the frontend decision-oriented views, notably:
- `frontend/src/pages/DecisionViewerPage.jsx`
- `frontend/src/pages/PolicyManagementPage.jsx`

#### Workflows, Gateway, and Execution

Workflows model orchestrated multi-stage activity:
- `backend/workflow/Workflow.js`
- `backend/workflow/workflowRoutes.js`
- `backend/workflow/index.js`

Transaction ingress and transaction records are handled by:
- `backend/gateway/gatewayRoutes.js`
- `backend/gateway/Transaction.js`

Approved execution reaches a wallet simulator rather than an indicated external blockchain/payment provider:
- `backend/wallet/walletSimulator.js`
- `backend/wallet/index.js`

The principal control flow is: authenticated operator/agent request → gateway/workflow → system-state and policy evaluation → simulated wallet execution or denial → persisted transaction and audit evidence.

#### Cryptographic Integrity Boundary

Cryptographic utilities support confidential credentials and tamper-evident request/decision handling:
- `backend/crypto/aesGcm.js`
- `backend/crypto/signature.js`
- `backend/crypto/canonicalJson.js`

Supporting key, fingerprint, nonce, and timestamp modules indicate protections against replay and inconsistent signed payload serialization. The master encryption key is supplied as `SENTINEL_MEK`; JWT signing uses `JWT_SECRET`.

#### Auditability and Operations UI

Audit records and audit service APIs provide the durable trace layer:
- `backend/audit/AuditLog.js`
- `backend/audit/auditService.js`
- `backend/audit/auditRoutes.js`

The React UI consumes backend APIs through:
- `frontend/src/services/api.js`

Operational views cover live transactions, workflows, audit logs, agents, credentials, policies, and system controls, with core examples at:
- `frontend/src/pages/LiveTransactionsPage.jsx`
- `frontend/src/pages/WorkflowMonitorPage.jsx`
- `frontend/src/pages/AuditLogsPage.jsx`

Material infrastructure is Node.js 18+, npm, MongoDB (local or Atlas), environment-provided secrets, and the locally simulated wallet execution layer.

Main entry points: [`backend/index.js`](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/index.js) (Backend entry), [`backend/policy-engine/policyEngine.js`](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/policy-engine/policyEngine.js) (Policy engine), [`backend/gateway/gatewayRoutes.js`](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/gateway/gatewayRoutes.js) (Transaction gateway), [`backend/audit/auditService.js`](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/audit/auditService.js) (Audit service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend services"]
  node_server["Backend entry<br/>Node.js server<br/>[index.js]"]
  node_system{{"System controls<br/>system state<br/>[systemState.js]"}}
  node_gateway["Transaction gateway<br/>transaction API<br/>[gatewayRoutes.js]"]
  node_transaction[("Transaction records<br/>MongoDB model<br/>[Transaction.js]")]
  node_workflow["Workflow orchestration<br/>workflow service<br/>[index.js]"]
  node_policy{{"Policy engine<br/>decision engine<br/>[policyEngine.js]"}}
  node_policy_store[("Policies<br/>MongoDB model<br/>[Policy.js]")]
  node_wallet["Wallet simulator<br/>execution adapter<br/>[walletSimulator.js]"]
  node_audit["Audit service<br/>audit API<br/>[auditService.js]"]
  node_audit_store[("Audit logs<br/>MongoDB model<br/>[AuditLog.js]")]
end

subgraph group_security["Identity &amp; integrity"]
  node_auth{{"Admin authentication<br/>JWT middleware<br/>[authMiddleware.js]"}}
  node_admins[("Administrators<br/>MongoDB model<br/>[Admin.js]")]
  node_agents["Agents<br/>agent API and model<br/>[agentRoutes.js]"]
  node_credentials["Credential service<br/>credential lifecycle"]
  node_credential_store[("Credentials<br/>MongoDB model<br/>[Credential.js]")]
  node_crypto{{"Crypto integrity<br/>AES-GCM and signatures<br/>[aesGcm.js]"}}
end

subgraph group_frontend["Operations UI"]
  node_ui["React operations UI<br/>Vite frontend<br/>[App.jsx]"]
  node_api["API client<br/>frontend service<br/>[api.js]"]
  node_decision_view["Decision viewer<br/>React page"]
  node_workflow_view["Workflow monitor<br/>React page"]
end

node_ui -->|"uses"| node_api
node_ui -->|"renders"| node_decision_view
node_ui -->|"renders"| node_workflow_view
node_api -->|"calls"| node_server
node_server -->|"protects routes with"| node_auth
node_auth -->|"verifies"| node_admins
node_server -->|"mounts"| node_gateway
node_server -->|"mounts"| node_workflow
node_server -->|"mounts"| node_policy
node_server -->|"mounts"| node_audit
node_server -->|"mounts controls"| node_system
node_gateway -->|"checks state"| node_system
node_workflow -->|"checks state"| node_system
node_gateway -->|"evaluates action"| node_policy
node_workflow -->|"evaluates stages"| node_policy
node_policy -->|"loads"| node_policy_store
node_policy -->|"approved execution"| node_wallet
node_gateway -->|"persists"| node_transaction
node_policy -->|"decision trace"| node_audit
node_wallet -->|"execution evidence"| node_audit
node_audit -->|"persists"| node_audit_store
node_agents -->|"uses credentials"| node_credentials
node_credentials -->|"persists"| node_credential_store
node_credentials -->|"encrypts with"| node_crypto
node_policy -->|"verifies signed payloads"| node_crypto
node_decision_view -->|"reads decisions"| node_api
node_workflow_view -->|"reads workflows"| node_api

click node_server "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/index.js"
click node_system "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/system/systemState.js"
click node_gateway "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/gateway/gatewayRoutes.js"
click node_transaction "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/gateway/Transaction.js"
click node_workflow "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/workflow/index.js"
click node_policy "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/policy-engine/policyEngine.js"
click node_policy_store "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/policy-engine/Policy.js"
click node_wallet "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/wallet/walletSimulator.js"
click node_audit "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/audit/auditService.js"
click node_audit_store "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/audit/AuditLog.js"
click node_auth "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/auth/authMiddleware.js"
click node_admins "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/auth/Admin.js"
click node_agents "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/agents/agentRoutes.js"
click node_credentials "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/credential-manager/credentialService.js"
click node_credential_store "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/credential-manager/Credential.js"
click node_crypto "https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/crypto/aesGcm.js"
click node_ui "https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/services/api.js"
click node_decision_view "https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/pages/DecisionViewerPage.jsx"
click node_workflow_view "https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/pages/WorkflowMonitorPage.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_server,node_system,node_gateway,node_transaction,node_workflow,node_policy,node_policy_store,node_wallet,node_audit,node_audit_store toneBlue
class node_auth,node_admins,node_agents,node_credentials,node_credential_store,node_crypto toneAmber
class node_ui,node_api,node_decision_view,node_workflow_view toneMint
```

## Components

### Backend services

Node.js route domains and execution pipeline.

- [Backend entry](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/index.js): Node.js server · Mounts route-backed domains and system controls. · `backend/index.js`
- [System controls](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/system/systemState.js): system state · Execution gate for status and kill-switch controls. · `backend/system/systemState.js`
- [Transaction gateway](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/gateway/gatewayRoutes.js): transaction API · Accepts transaction requests and records their outcomes. · `backend/gateway/gatewayRoutes.js`
- [Transaction records](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/gateway/Transaction.js): MongoDB model · `backend/gateway/Transaction.js`
- [Workflow orchestration](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/workflow/index.js): workflow service · Coordinates multi-stage agent activity. · `backend/workflow/index.js`
- [Policy engine](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/policy-engine/policyEngine.js): decision engine · Approves or denies requested agent actions. · `backend/policy-engine/policyEngine.js`
- [Policies](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/policy-engine/Policy.js): MongoDB model · `backend/policy-engine/Policy.js`
- [Wallet simulator](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/wallet/walletSimulator.js): execution adapter · Local simulated wallet execution target. · `backend/wallet/walletSimulator.js`
- [Audit service](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/audit/auditService.js): audit API · Writes and exposes durable decision traces. · `backend/audit/auditService.js`
- [Audit logs](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/audit/AuditLog.js): MongoDB model · `backend/audit/AuditLog.js`

### Identity & integrity

Operator access, credential protection, and signed payload handling.

- [Admin authentication](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/auth/authMiddleware.js): JWT middleware · Authorizes administrator API access. · `backend/auth/authMiddleware.js`
- [Administrators](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/auth/Admin.js): MongoDB model · `backend/auth/Admin.js`
- [Agents](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/agents/agentRoutes.js): agent API and model · Maintains independent agent identities. · `backend/agents/agentRoutes.js`
- [Credential service](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/credential-manager/credentialService.js): credential lifecycle · Manages persisted credentials. · `backend/credential-manager/credentialService.js`
- [Credentials](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/credential-manager/Credential.js): MongoDB model · `backend/credential-manager/Credential.js`
- [Crypto integrity](https://github.com/prasad0706/innovahack-localclaude/blob/main/backend/crypto/aesGcm.js): AES-GCM and signatures · Protects credentials and canonical signed payloads. · `backend/crypto/aesGcm.js`

### Operations UI

Vite/React dashboards for operational control.

- [React operations UI](https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/App.jsx): Vite frontend · Operational dashboards and decision views. · `frontend/src/App.jsx`
- [API client](https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/services/api.js): frontend service · `frontend/src/services/api.js`
- [Decision viewer](https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/pages/DecisionViewerPage.jsx): React page · `frontend/src/pages/DecisionViewerPage.jsx`
- [Workflow monitor](https://github.com/prasad0706/innovahack-localclaude/blob/main/frontend/src/pages/WorkflowMonitorPage.jsx): React page · `frontend/src/pages/WorkflowMonitorPage.jsx`

## Connections

- React operations UI → API client: uses
- React operations UI → Decision viewer: renders
- React operations UI → Workflow monitor: renders
- API client → Backend entry: calls
- Backend entry → Admin authentication: protects routes with
- Admin authentication → Administrators: verifies
- Backend entry → Transaction gateway: mounts
- Backend entry → Workflow orchestration: mounts
- Backend entry → Policy engine: mounts
- Backend entry → Audit service: mounts
- Backend entry → System controls: mounts controls
- Transaction gateway → System controls: checks state
- Workflow orchestration → System controls: checks state
- Transaction gateway → Policy engine: evaluates action
- Workflow orchestration → Policy engine: evaluates stages
- Policy engine → Policies: loads
- Policy engine → Wallet simulator: approved execution
- Transaction gateway → Transaction records: persists
- Policy engine → Audit service: decision trace
- Wallet simulator → Audit service: execution evidence
- Audit service → Audit logs: persists
- Agents → Credential service: uses credentials
- Credential service → Credentials: persists
- Credential service → Crypto integrity: encrypts with
- Policy engine → Crypto integrity: verifies signed payloads
- Decision viewer → API client: reads decisions
- Workflow monitor → API client: reads workflows