# singh-arun7/vkyc-ai-agent architecture

> Architecture diagram of the GitHub repository singh-arun7/vkyc-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/singh-arun7/vkyc-ai-agent
- Repository: https://github.com/singh-arun7/vkyc-ai-agent

## Overview

1. **Repository shape**
   This is a small two-tier application with a **Python backend** and a **browser frontend**. The backend is under `backend/`, the frontend under `frontend/`, and there is a small `backend/data/` directory for local data or model-related assets.

2. **User-facing layer**
   The frontend is a static client made of `index.html`, `app.js`, `styles.css`, and `languages.js`. That suggests a lightweight single-page UI rather than a framework-heavy app. Its main job is to collect user input, display results, and call the backend API.

3. **Backend application entrypoint**
   `backend/app/main.py` is the backend bootstrap point. It is the place where the server is started and where routes are wired together. For architecture diagrams, treat this as the backend root container that exposes the HTTP API.

4. **API boundary**
   `backend/app/routes/detect.py` is the main functional endpoint area. The name strongly indicates the system’s core workflow is a **detection / inference request** exposed over HTTP. This is the primary boundary between the browser and the backend.

5. **Core business capability**
   The repository name `vkyc-ai-agent` and the `detect` route indicate the backend likely performs some kind of **AI-assisted verification or detection** task. The architecture is therefore centered on a request coming from the UI, being processed server-side, and returning a detection result to the client.

6. **Data and local assets**
   `backend/data/` is a separate storage area from code. In a diagram, this should be shown as a backend-side data dependency, likely for model files, reference assets, configuration artifacts, or cached inputs/outputs used by the detection flow.

7. **Frontend-to-backend flow**
   The key runtime flow is:
   user interacts with the frontend → frontend JavaScript sends a request to the backend detect endpoint → backend processes the request and produces a result → frontend renders the response.  
   That is the central end-to-end path in the repo.

8. **Subsystem boundaries**
   The cleanest architectural split is:
   - **Presentation layer:** `frontend/`
   - **Application/API layer:** `backend/app/`
   - **Detection logic:** `backend/app/routes/detect.py`
   - **Local assets/data:** `backend/data/`  
   This suggests the system is intentionally separated by responsibility, with the UI decoupled from the detection implementation.

9. **Technology footprint**
   The backend uses Python and a dependency-managed environment via `backend/requirements.txt`. The frontend is plain HTML/CSS/JavaScript. No separate database, message broker, or external service is visible in the file tree, so the architecture appears intentionally minimal.

10. **Likely deployment model**
   The repo looks suited to a simple deployment where the backend serves an API and the frontend is served as static files, either by a web server or separately in the browser. There is no evidence of microservices or multi-service orchestration.

11. **What to emphasize in a diagram**
   Show a single browser client talking to one backend service, with the backend having one highlighted route for detection and a local data/assets folder. Avoid drawing extra infrastructure unless later code reveals databases, object storage, or third-party AI services.

12. **Overall architecture summary**
   This is a compact **AI-enabled client/server app**: a static JS frontend, a Python HTTP backend, and a detection-focused route backed by local data/assets. The main architectural concern is the request/response path from UI to inference logic and back to the user.

Main entry points: [`frontend/app.js`](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/app.js) (Client Logic), [`backend/app/main.py`](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/app/main.py) (Backend App), [`backend/app/routes/detect.py`](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/app/routes/detect.py) (Detect API), [`frontend/index.html`](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/index.html) (Browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client<br/>[index.html]"))
  node_ui_shell["UI Shell<br/>static UI<br/>[index.html]"]
  node_client_logic["Client Logic<br/>js client<br/>[app.js]"]
  node_lang_assets["Language Data<br/>ui data<br/>[languages.js]"]
end

subgraph group_backend["Backend"]
  node_backend_app["Backend App<br/>python api<br/>[main.py]"]
  node_detect_api["Detect API<br/>route<br/>[detect.py]"]
  node_local_data[("Local Data<br/>assets")]
  node_dependencies["Requirements<br/>python deps<br/>[requirements.txt]"]
end

node_browser -->|"loads"| node_ui_shell
node_ui_shell -->|"runs"| node_client_logic
node_client_logic -->|"uses"| node_lang_assets
node_client_logic -->|"calls"| node_detect_api
node_backend_app -->|"wires"| node_detect_api
node_detect_api -->|"reads"| node_local_data
node_backend_app -.->|"depends on"| node_dependencies
node_browser -->|"requests"| node_backend_app

click node_browser "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/index.html"
click node_ui_shell "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/index.html"
click node_client_logic "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/app.js"
click node_lang_assets "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/languages.js"
click node_backend_app "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/app/main.py"
click node_detect_api "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/app/routes/detect.py"
click node_local_data "https://github.com/singh-arun7/vkyc-ai-agent/tree/main/backend/data"
click node_dependencies "https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/requirements.txt"

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_browser,node_ui_shell,node_client_logic,node_lang_assets toneBlue
class node_backend_app,node_detect_api,node_local_data,node_dependencies toneAmber
```

## Components

### Frontend

Static browser UI and client-side interaction layer.

- [Browser](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/index.html): client · User-facing runtime that loads the static UI and sends requests. · `frontend/index.html`
- [UI Shell](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/index.html): static UI · Main HTML entry and app layout for the client. · `frontend/index.html`
- [Client Logic](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/app.js): js client · Handles user input, API calls, and result rendering. · `frontend/app.js`
- [Language Data](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/frontend/languages.js): ui data · Frontend language/label content used by the client. · `frontend/languages.js`

### Backend

Python application, API routes, and local data assets.

- [Backend App](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/app/main.py): python api · Backend application bootstrap and HTTP server entrypoint. · `backend/app/main.py`
- [Detect API](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/app/routes/detect.py): route · Primary detection/inference endpoint exposed over HTTP. · `backend/app/routes/detect.py`
- [Local Data](https://github.com/singh-arun7/vkyc-ai-agent/tree/main/backend/data): assets · Backend-side data and model-related assets consumed by the app. · `backend/data`
- [Requirements](https://github.com/singh-arun7/vkyc-ai-agent/blob/main/backend/requirements.txt): python deps · Backend package and runtime dependencies. · `backend/requirements.txt`

## Connections

- Browser → UI Shell: loads · The browser loads the static client entry.
- UI Shell → Client Logic: runs · The UI shell is driven by client-side JavaScript.
- Client Logic → Language Data: uses · Client logic reads language and label content.
- Client Logic → Detect API: calls · Frontend sends detection requests to the backend.
- Backend App → Detect API: wires · The backend entrypoint registers the detection route.
- Detect API → Local Data: reads · Detection logic depends on backend local assets or cached data.
- Backend App → Requirements: depends on · The backend runtime is defined by its Python dependencies.
- Browser → Backend App: requests · The UI communicates with the backend service over HTTP.