# khushi02-git/agentaccess architecture

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

- Interactive diagram: https://gitdiagram.com/khushi02-git/agentaccess
- Repository: https://github.com/khushi02-git/agentaccess

## Overview

AgentAccess is a policy-based access-control framework for AI-agent database and OS operations, with a web console for oversight. The main workflow routes API requests through authentication, query validation and role/policy authorization before database execution, while recording audit events; entity resolution and AI-assisted SQL generation are additional query capabilities. The console exposes agent, RBAC, audit, query, and system views. A separate OS-monitor package demonstrates access controls, agent monitoring, audit logging, and job scheduling. Evidence is limited to the README and the supplied excerpts and source index; some feature-to-route details remain unsampled.

Main entry points: [`backend/main.py`](https://github.com/khushi02-git/agentaccess/blob/main/backend/main.py) (API Application), [`frontend/src/App.jsx`](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/App.jsx) (Console Router), [`backend/database.py`](https://github.com/khushi02-git/agentaccess/blob/main/backend/database.py) (Application Database), [`frontend/src/lib/api.js`](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/lib/api.js) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Services"]
  node_api_app["API Application<br/>[main.py]"]
  node_schemas["Request Schemas<br/>[schemas.py]"]
  node_auth_routes["Authentication Routes<br/>[auth.py]"]
  node_db[("Application Database<br/>[database.py]")]
  node_audit_service["Audit Service<br/>[audit_service.py]"]
  node_audit_routes["Audit Routes<br/>[audit.py]"]
  node_dashboard_routes["Dashboard Routes<br/>[dashboard.py]"]
end

subgraph group_policy["Query and Policy"]
  node_auth_service["Authentication and RBAC<br/>[auth_service.py]"]
  node_query_routes["Query Routes<br/>[query.py]"]
  node_query_service["SQL Validation<br/>[query_service.py]"]
  node_entity_routes["Entity Resolution Routes"]
  node_entity_service["Entity Resolution"]
  node_gemini_routes["SQL Generation Routes<br/>[gemini.py]"]
  node_gemini_service["SQL Generation<br/>[gemini_service.py]"]
end

subgraph group_console["Web Console"]
  node_frontend_app["Console Router<br/>[App.jsx]"]
  node_api_client["API Client<br/>[api.js]"]
  node_agent_page["Agent View<br/>[Agent.jsx]"]
  node_rbac_page["RBAC View<br/>[RBAC.jsx]"]
  node_audit_page["Audit Trail<br/>[AuditTrail.jsx]"]
  node_dashboard_page["Dashboard<br/>[Dashboard.jsx]"]
  node_system_page["System Monitor<br/>[SystemMonitor.jsx]"]
  node_logs_page["Logs and Violations<br/>[Logs.jsx]"]
end

subgraph group_os["OS Operations"]
  node_os_routes["OS Monitor Routes<br/>[os_monitor.py]"]
  node_os_service["OS Monitor Service"]
  node_access_matrix["Access Matrix<br/>[access_matrix.py]"]
  node_agent_monitor["Agent Monitor<br/>[agent_monitor.py]"]
  node_os_audit["OS Audit Log<br/>[audit_log.py]"]
  node_os_limits["Resource Limits<br/>[limits.py]"]
  node_scheduler_live["Live Scheduler<br/>[scheduler_live.py]"]
  node_scheduler_sim["Scheduler Simulator<br/>[scheduler_sim.py]"]
end

node_agent_user(("Agent"))
node_web_operator(("Console Operator"))

node_agent_user -->|"submits requests"| node_api_app
node_api_app -->|"routes to"| node_auth_routes
node_api_app -->|"routes to"| node_query_routes
node_api_app -->|"routes to"| node_entity_routes
node_api_app -->|"routes to"| node_gemini_routes
node_api_app -->|"routes to"| node_audit_routes
node_api_app -->|"routes to"| node_dashboard_routes
node_api_app -->|"routes to"| node_os_routes
node_auth_routes -->|"calls"| node_auth_service
node_query_routes -->|"validates SQL"| node_query_service
node_query_routes -->|"checks access"| node_auth_service
node_query_routes -->|"records events"| node_audit_service
node_query_routes -->|"executes approved SQL"| node_db
node_auth_service -->|"checks policy"| node_db
node_entity_routes -->|"calls"| node_entity_service
node_entity_service -->|"checks table access"| node_auth_service
node_entity_service -->|"searches records"| node_db
node_entity_service -->|"records failures"| node_audit_service
node_gemini_routes -->|"calls"| node_gemini_service
node_gemini_routes -->|"validates generated SQL"| node_query_service
node_gemini_routes -->|"records events"| node_audit_service
node_audit_routes -->|"reads audit data"| node_db
node_audit_service -->|"writes audit records"| node_db
node_dashboard_routes -->|"reads dashboard data"| node_db
node_os_routes -->|"calls"| node_os_service
node_os_routes -->|"records events"| node_audit_service
node_api_app -.->|"uses request models"| node_schemas
node_web_operator -->|"opens console"| node_frontend_app
node_frontend_app -->|"routes to"| node_agent_page
node_frontend_app -->|"routes to"| node_rbac_page
node_frontend_app -->|"routes to"| node_audit_page
node_frontend_app -->|"routes to"| node_dashboard_page
node_frontend_app -->|"routes to"| node_system_page
node_frontend_app -->|"routes to"| node_logs_page
node_agent_page -->|"requests data"| node_api_client
node_rbac_page -->|"requests data"| node_api_client
node_audit_page -->|"requests events"| node_api_client
node_dashboard_page -.->|"requests data"| node_api_client
node_system_page -.->|"requests stats"| node_api_client
node_logs_page -.->|"requests logs"| node_api_client
node_agent_monitor -->|"checks access"| node_access_matrix
node_agent_monitor -->|"logs events"| node_os_audit
node_agent_monitor -->|"enforces limits"| node_os_limits
node_scheduler_live -->|"authorizes jobs"| node_access_matrix
node_scheduler_live -->|"monitors agents"| node_agent_monitor
node_scheduler_live -->|"logs jobs"| node_os_audit
node_scheduler_sim -->|"uses limits"| node_os_limits

click node_api_app "https://github.com/khushi02-git/agentaccess/blob/main/backend/main.py"
click node_schemas "https://github.com/khushi02-git/agentaccess/blob/main/backend/schemas.py"
click node_auth_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/auth.py"
click node_auth_service "https://github.com/khushi02-git/agentaccess/blob/main/backend/services/auth_service.py"
click node_query_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/query.py"
click node_query_service "https://github.com/khushi02-git/agentaccess/blob/main/backend/services/query_service.py"
click node_entity_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/entity_resolution.py"
click node_entity_service "https://github.com/khushi02-git/agentaccess/blob/main/backend/services/entity_resolution_service.py"
click node_gemini_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/gemini.py"
click node_gemini_service "https://github.com/khushi02-git/agentaccess/blob/main/backend/services/gemini_service.py"
click node_db "https://github.com/khushi02-git/agentaccess/blob/main/backend/database.py"
click node_audit_service "https://github.com/khushi02-git/agentaccess/blob/main/backend/services/audit_service.py"
click node_audit_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/audit.py"
click node_dashboard_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/dashboard.py"
click node_os_routes "https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/os_monitor.py"
click node_os_service "https://github.com/khushi02-git/agentaccess/blob/main/backend/services/os_monitor_service.py"
click node_frontend_app "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/lib/api.js"
click node_agent_page "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/Agent.jsx"
click node_rbac_page "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/RBAC.jsx"
click node_audit_page "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/AuditTrail.jsx"
click node_dashboard_page "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/Dashboard.jsx"
click node_system_page "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/SystemMonitor.jsx"
click node_logs_page "https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/Logs.jsx"
click node_access_matrix "https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/access_matrix.py"
click node_agent_monitor "https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/agent_monitor.py"
click node_os_audit "https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/audit_log.py"
click node_os_limits "https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/limits.py"
click node_scheduler_live "https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/scheduler_live.py"
click node_scheduler_sim "https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/scheduler_sim.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_api_app,node_schemas,node_auth_routes,node_db,node_audit_service,node_audit_routes,node_dashboard_routes toneBlue
class node_auth_service,node_query_routes,node_query_service,node_entity_routes,node_entity_service,node_gemini_routes,node_gemini_service toneAmber
class node_frontend_app,node_api_client,node_agent_page,node_rbac_page,node_audit_page,node_dashboard_page,node_system_page,node_logs_page toneMint
class node_os_routes,node_os_service,node_access_matrix,node_agent_monitor,node_os_audit,node_os_limits,node_scheduler_live,node_scheduler_sim toneRose
class node_agent_user,node_web_operator toneIndigo
```

## Components

### API and Services

- [API Application](https://github.com/khushi02-git/agentaccess/blob/main/backend/main.py): `backend/main.py`
- [Request Schemas](https://github.com/khushi02-git/agentaccess/blob/main/backend/schemas.py): `backend/schemas.py`
- [Authentication Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Application Database](https://github.com/khushi02-git/agentaccess/blob/main/backend/database.py): `backend/database.py`
- [Audit Service](https://github.com/khushi02-git/agentaccess/blob/main/backend/services/audit_service.py): `backend/services/audit_service.py`
- [Audit Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/audit.py): `backend/routes/audit.py`
- [Dashboard Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/dashboard.py): `backend/routes/dashboard.py`

### Query and Policy

- [Authentication and RBAC](https://github.com/khushi02-git/agentaccess/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Query Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/query.py): `backend/routes/query.py`
- [SQL Validation](https://github.com/khushi02-git/agentaccess/blob/main/backend/services/query_service.py): `backend/services/query_service.py`
- [Entity Resolution Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/entity_resolution.py): `backend/routes/entity_resolution.py`
- [Entity Resolution](https://github.com/khushi02-git/agentaccess/blob/main/backend/services/entity_resolution_service.py): `backend/services/entity_resolution_service.py`
- [SQL Generation Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/gemini.py): `backend/routes/gemini.py`
- [SQL Generation](https://github.com/khushi02-git/agentaccess/blob/main/backend/services/gemini_service.py): `backend/services/gemini_service.py`

### Web Console

- [Console Router](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API Client](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`
- [Agent View](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/Agent.jsx): `frontend/src/pages/Agent.jsx`
- [RBAC View](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/RBAC.jsx): `frontend/src/pages/RBAC.jsx`
- [Audit Trail](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/AuditTrail.jsx): `frontend/src/pages/AuditTrail.jsx`
- [Dashboard](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [System Monitor](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/SystemMonitor.jsx): `frontend/src/pages/SystemMonitor.jsx`
- [Logs and Violations](https://github.com/khushi02-git/agentaccess/blob/main/frontend/src/pages/Logs.jsx): `frontend/src/pages/Logs.jsx`

### OS Operations

- [OS Monitor Routes](https://github.com/khushi02-git/agentaccess/blob/main/backend/routes/os_monitor.py): `backend/routes/os_monitor.py`
- [OS Monitor Service](https://github.com/khushi02-git/agentaccess/blob/main/backend/services/os_monitor_service.py): `backend/services/os_monitor_service.py`
- [Access Matrix](https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/access_matrix.py): `AgentAccess-OS/monitor/access_matrix.py`
- [Agent Monitor](https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/agent_monitor.py): `AgentAccess-OS/monitor/agent_monitor.py`
- [OS Audit Log](https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/audit_log.py): `AgentAccess-OS/monitor/audit_log.py`
- [Resource Limits](https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/limits.py): `AgentAccess-OS/monitor/limits.py`
- [Live Scheduler](https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/scheduler_live.py): `AgentAccess-OS/monitor/scheduler_live.py`
- [Scheduler Simulator](https://github.com/khushi02-git/agentaccess/blob/main/AgentAccess-OS/monitor/scheduler_sim.py): `AgentAccess-OS/monitor/scheduler_sim.py`

### Other components

- **Agent**
- **Console Operator**

## Connections

- Agent → API Application: submits requests (evidence: `backend/main.py`)
- API Application → Authentication Routes: routes to (evidence: `backend/main.py`)
- API Application → Query Routes: routes to (evidence: `backend/main.py`)
- API Application → Entity Resolution Routes: routes to (evidence: `backend/main.py`)
- API Application → SQL Generation Routes: routes to (evidence: `backend/main.py`)
- API Application → Audit Routes: routes to (evidence: `backend/main.py`)
- API Application → Dashboard Routes: routes to (evidence: `backend/main.py`)
- API Application → OS Monitor Routes: routes to (evidence: `backend/main.py`)
- Authentication Routes → Authentication and RBAC: calls (evidence: `backend/routes/auth.py`)
- Query Routes → SQL Validation: validates SQL (evidence: `backend/routes/query.py`)
- Query Routes → Authentication and RBAC: checks access (evidence: `backend/routes/query.py`)
- Query Routes → Audit Service: records events (evidence: `backend/routes/query.py`)
- Query Routes → Application Database: executes approved SQL (evidence: `backend/routes/query.py`)
- Authentication and RBAC → Application Database: checks policy (evidence: `backend/services/auth_service.py`)
- Entity Resolution Routes → Entity Resolution: calls (evidence: `backend/routes/entity_resolution.py`)
- Entity Resolution → Authentication and RBAC: checks table access (evidence: `backend/services/entity_resolution_service.py`)
- Entity Resolution → Application Database: searches records (evidence: `backend/services/entity_resolution_service.py`)
- Entity Resolution → Audit Service: records failures (evidence: `backend/services/entity_resolution_service.py`)
- SQL Generation Routes → SQL Generation: calls (evidence: `backend/routes/gemini.py`)
- SQL Generation Routes → SQL Validation: validates generated SQL (evidence: `backend/routes/gemini.py`)
- SQL Generation Routes → Audit Service: records events (evidence: `backend/routes/gemini.py`)
- Audit Routes → Application Database: reads audit data (evidence: `backend/routes/audit.py`)
- Audit Service → Application Database: writes audit records (evidence: `backend/services/audit_service.py`)
- Dashboard Routes → Application Database: reads dashboard data (evidence: `backend/routes/dashboard.py`)
- OS Monitor Routes → OS Monitor Service: calls (evidence: `backend/routes/os_monitor.py`)
- OS Monitor Routes → Audit Service: records events (evidence: `backend/routes/os_monitor.py`)
- API Application → Request Schemas: uses request models
- Console Operator → Console Router: opens console (evidence: `frontend/src/App.jsx`)
- Console Router → Agent View: routes to (evidence: `frontend/src/App.jsx`)
- Console Router → RBAC View: routes to (evidence: `frontend/src/App.jsx`)
- Console Router → Audit Trail: routes to (evidence: `frontend/src/App.jsx`)
- Console Router → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- Console Router → System Monitor: routes to (evidence: `frontend/src/App.jsx`)
- Console Router → Logs and Violations: routes to (evidence: `frontend/src/App.jsx`)
- Agent View → API Client: requests data (evidence: `frontend/src/pages/Agent.jsx`)
- RBAC View → API Client: requests data (evidence: `frontend/src/pages/RBAC.jsx`)
- Audit Trail → API Client: requests events (evidence: `frontend/src/pages/AuditTrail.jsx`)
- Dashboard → API Client: requests data
- System Monitor → API Client: requests stats
- Logs and Violations → API Client: requests logs
- Agent Monitor → Access Matrix: checks access (evidence: `AgentAccess-OS/monitor/agent_monitor.py`)
- Agent Monitor → OS Audit Log: logs events (evidence: `AgentAccess-OS/monitor/agent_monitor.py`)
- Agent Monitor → Resource Limits: enforces limits (evidence: `AgentAccess-OS/monitor/agent_monitor.py`)
- Live Scheduler → Access Matrix: authorizes jobs (evidence: `AgentAccess-OS/monitor/scheduler_live.py`)
- Live Scheduler → Agent Monitor: monitors agents (evidence: `AgentAccess-OS/monitor/scheduler_live.py`)
- Live Scheduler → OS Audit Log: logs jobs (evidence: `AgentAccess-OS/monitor/scheduler_live.py`)
- Scheduler Simulator → Resource Limits: uses limits (evidence: `AgentAccess-OS/monitor/scheduler_sim.py`)
