# sivatejachary/vidyamargai architecture

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

- Interactive diagram: https://gitdiagram.com/sivatejachary/vidyamargai
- Repository: https://github.com/sivatejachary/vidyamargai

## Overview

HireAI is an AI-enabled recruiting and career platform. The principal workflow is a candidate using the web portal, whose requests reach the FastAPI backend for recruitment, resume, and learning capabilities; administrators also have management screens. The tree documents additional agent, job-ingestion, and MCP subsystems. Sampled AI OS engines show model-backed intent and reasoning, but do not establish how the application wires them into API requests. The graph therefore shows the documented web/API boundary and only specific internal or external calls supported by the sampled source.

Main entry points: [`backend/app/main.py`](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/main.py) (FastAPI application), [`backend/packages/model_client/client.py`](https://github.com/sivatejachary/vidyamargai/blob/main/backend/packages/model_client/client.py) (Model client), [`frontend/app/candidate`](https://github.com/sivatejachary/vidyamargai/tree/main/frontend/app/candidate) (Candidate portal), [`frontend/app/api/v1/[...slug]/route.ts`](https://github.com/sivatejachary/vidyamargai/blob/main/frontend/app/api/v1/%5B...slug%5D/route.ts) (API proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_portal["Candidate portal"]
  node_adminui["Admin portal"]
  node_webapi["API proxy<br/>[route.ts]"]
end

subgraph group_api["Application API"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_routers["Feature routers"]
  node_auth["Authentication<br/>[auth.py]"]
  node_database[("Application database<br/>[database.py]")]
  node_storage["File storage<br/>[storage.py]"]
end

subgraph group_career["Career capabilities"]
  node_profiles["Candidate profiles<br/>[profile.py]"]
  node_resumes["Resume services<br/>[resume.py]"]
  node_jobs["Job agent"]
  node_learning["Learning and skills<br/>[learning.py]"]
  node_mentoring["Career mentoring<br/>[mentor.py]"]
  node_chat["Career chat<br/>[chat.py]"]
end

subgraph group_agents["AI agent platform"]
  node_orchestrator["Agent orchestration<br/>[orchestrator.py]"]
  node_aios["AI OS runtime"]
  node_intent["Intent engine<br/>[engine.py]"]
  node_reasoning["Reasoning engine<br/>[engine.py]"]
  node_policy["Job policy<br/>[policy_engine.py]"]
  node_approval["Human approvals<br/>[approval_engine.py]"]
  node_mcp["MCP gateway<br/>[gateway.py]"]
end

subgraph group_integrations["External services"]
  node_modelclient["Model client<br/>[client.py]"]
  node_modelprovider["AI model provider"]
  node_objectstore[("MinIO storage")]
end

node_candidate(("Candidate"))
node_admin(("Administrator"))

node_candidate -->|"uses"| node_portal
node_admin -->|"uses"| node_adminui
node_portal -->|"sends requests"| node_webapi
node_webapi -->|"forwards requests"| node_fastapi
node_fastapi -->|"serves API"| node_routers
node_fastapi -->|"uses"| node_database
node_intent -->|"requests completion"| node_modelclient
node_reasoning -->|"requests completion"| node_modelclient
node_modelclient -->|"calls model"| node_modelprovider
node_storage -.->|"stores files"| node_objectstore

click node_portal "https://github.com/sivatejachary/vidyamargai/tree/main/frontend/app/candidate"
click node_adminui "https://github.com/sivatejachary/vidyamargai/tree/main/frontend/app/admin"
click node_webapi "https://github.com/sivatejachary/vidyamargai/blob/main/frontend/app/api/v1/%5B...slug%5D/route.ts"
click node_fastapi "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/main.py"
click node_routers "https://github.com/sivatejachary/vidyamargai/tree/main/backend/app/api/routers"
click node_auth "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/auth.py"
click node_profiles "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/profile.py"
click node_resumes "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/resume.py"
click node_jobs "https://github.com/sivatejachary/vidyamargai/tree/main/backend/app/job_agent"
click node_learning "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/learning.py"
click node_mentoring "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/mentor.py"
click node_chat "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/chat.py"
click node_orchestrator "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/services/orchestrator.py"
click node_aios "https://github.com/sivatejachary/vidyamargai/tree/main/backend/ai_os"
click node_intent "https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/intent_engine/engine.py"
click node_reasoning "https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/reasoning_engine/engine.py"
click node_policy "https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/policy/policy_engine.py"
click node_approval "https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/security/approval_engine.py"
click node_modelclient "https://github.com/sivatejachary/vidyamargai/blob/main/backend/packages/model_client/client.py"
click node_database "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/core/database.py"
click node_mcp "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/mcp/gateway.py"
click node_storage "https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/services/storage.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_portal,node_adminui,node_webapi toneBlue
class node_fastapi,node_routers,node_auth,node_database,node_storage toneAmber
class node_profiles,node_resumes,node_jobs,node_learning,node_mentoring,node_chat toneMint
class node_orchestrator,node_aios,node_intent,node_reasoning,node_policy,node_approval,node_mcp toneRose
class node_modelclient,node_modelprovider,node_objectstore,node_candidate,node_admin toneIndigo
```

## Components

### Web experience

- [Candidate portal](https://github.com/sivatejachary/vidyamargai/tree/main/frontend/app/candidate): `frontend/app/candidate`
- [Admin portal](https://github.com/sivatejachary/vidyamargai/tree/main/frontend/app/admin): `frontend/app/admin`
- [API proxy](https://github.com/sivatejachary/vidyamargai/blob/main/frontend/app/api/v1/%5B...slug%5D/route.ts): `frontend/app/api/v1/[...slug]/route.ts`

### Application API

- [FastAPI application](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Feature routers](https://github.com/sivatejachary/vidyamargai/tree/main/backend/app/api/routers): `backend/app/api/routers`
- [Authentication](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/auth.py): `backend/app/api/routers/auth.py`
- [Application database](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [File storage](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`

### Career capabilities

- [Candidate profiles](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/profile.py): `backend/app/api/routers/profile.py`
- [Resume services](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/resume.py): `backend/app/api/routers/resume.py`
- [Job agent](https://github.com/sivatejachary/vidyamargai/tree/main/backend/app/job_agent): `backend/app/job_agent`
- [Learning and skills](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/learning.py): `backend/app/api/routers/learning.py`
- [Career mentoring](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/mentor.py): `backend/app/api/routers/mentor.py`
- [Career chat](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/api/routers/chat.py): `backend/app/api/routers/chat.py`

### AI agent platform

- [Agent orchestration](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/services/orchestrator.py): `backend/app/services/orchestrator.py`
- [AI OS runtime](https://github.com/sivatejachary/vidyamargai/tree/main/backend/ai_os): `backend/ai_os`
- [Intent engine](https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/intent_engine/engine.py): `backend/ai_os/intent_engine/engine.py`
- [Reasoning engine](https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/reasoning_engine/engine.py): `backend/ai_os/reasoning_engine/engine.py`
- [Job policy](https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/policy/policy_engine.py): `backend/ai_os/policy/policy_engine.py`
- [Human approvals](https://github.com/sivatejachary/vidyamargai/blob/main/backend/ai_os/security/approval_engine.py): `backend/ai_os/security/approval_engine.py`
- [MCP gateway](https://github.com/sivatejachary/vidyamargai/blob/main/backend/app/mcp/gateway.py): `backend/app/mcp/gateway.py`

### External services

- [Model client](https://github.com/sivatejachary/vidyamargai/blob/main/backend/packages/model_client/client.py): `backend/packages/model_client/client.py`
- **AI model provider**
- **MinIO storage**

### Other components

- **Candidate**
- **Administrator**

## Connections

- Candidate → Candidate portal: uses
- Administrator → Admin portal: uses
- Candidate portal → API proxy: sends requests
- API proxy → FastAPI application: forwards requests
- FastAPI application → Feature routers: serves API
- FastAPI application → Application database: uses
- Intent engine → Model client: requests completion
- Reasoning engine → Model client: requests completion
- Model client → AI model provider: calls model
- File storage → MinIO storage: stores files