# mgalen007/umurava-aria-project architecture

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

- Interactive diagram: https://gitdiagram.com/mgalen007/umurava-aria-project
- Repository: https://github.com/mgalen007/umurava-aria-project

## Overview

ARIA is an AI-assisted recruitment platform. Recruiters use the web dashboard to manage jobs and candidates, start screening sessions, review ranked evaluations, and submit feedback; the backend persists workflow data and sends completion notifications. The README documents file ingestion, notifications, settings, and Gemini integration, while sampled code confirms session orchestration and candidate imports. Some frontend-to-endpoint wiring and unsampled feature internals are not shown, so those links are limited to documented API interactions.

Main entry points: [`server/src/app.ts`](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/app.ts) (Express API), [`server/src/features/sessions/sessions.service.ts`](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.service.ts) (Session Orchestration), [`client/lib/api.ts`](https://github.com/mgalen007/umurava-aria-project/blob/main/client/lib/api.ts) (API Client), [`server/src/features/candidates/candidates.routes.ts`](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/candidates/candidates.routes.ts) (Candidate Management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Recruiter Workspace"]
  node_web["Next.js Workspace<br/>[page.tsx]"]
  node_auth_ui["Sign-in Pages<br/>[page.tsx]"]
  node_api_client["API Client<br/>[api.ts]"]
end

subgraph group_api["Recruitment API"]
  node_app["Express API<br/>[app.ts]"]
  node_auth_routes["Auth Routes<br/>[auth.routes.ts]"]
  node_auth_controller["Auth Controller<br/>[auth.controller.ts]"]
  node_auth_service["Auth Service<br/>[auth.service.ts]"]
  node_jobs["Job Management<br/>[jobs.routes.ts]"]
  node_candidates["Candidate Management"]
  node_candidate_service["Candidate Ingestion"]
  node_sessions["Session Screening<br/>[sessions.routes.ts]"]
  node_session_controller["Session Controller"]
  node_session_service["Session Orchestration"]
  node_notifications["Notifications"]
  node_settings["Recruiter Settings<br/>[settings.routes.ts]"]
end

subgraph group_intelligence["Screening Intelligence"]
  node_ai["AI Evaluation<br/>[ai.service.ts]"]
  node_feedback["AI Feedback"]
  node_normalization["Result Normalization"]
end

subgraph group_state["Persistence"]
  node_mongo[("MongoDB")]
end

node_recruiter(("Recruiter"))
node_gemini{{"Google Gemini"}}
node_file_upload["Resume Files"]

node_recruiter -->|"signs in"| node_auth_ui
node_recruiter -->|"manages hiring"| node_web
node_auth_ui -->|"requests auth"| node_api_client
node_web -->|"requests data"| node_api_client
node_api_client -->|"calls API"| node_app
node_app -->|"dispatches auth"| node_auth_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"invokes"| node_auth_service
node_auth_service -->|"reads and writes users"| node_mongo
node_app -->|"dispatches jobs"| node_jobs
node_app -->|"dispatches candidates"| node_candidates
node_app -->|"dispatches sessions"| node_sessions
node_app -->|"dispatches settings"| node_settings
node_candidates -->|"dispatches ingestion"| node_candidate_service
node_file_upload -->|"uploads resumes"| node_candidates
node_candidate_service -->|"stores profiles"| node_mongo
node_jobs -->|"stores postings"| node_mongo
node_sessions -->|"dispatches"| node_session_controller
node_session_controller -->|"invokes"| node_session_service
node_session_service -->|"reads and updates"| node_mongo
node_session_service -->|"evaluates session"| node_ai
node_ai -.->|"requests evaluation"| node_gemini
node_session_service -->|"creates completion notice"| node_notifications
node_notifications -->|"stores notices"| node_mongo
node_settings -->|"updates preferences"| node_mongo
node_recruiter -->|"reviews results"| node_feedback
node_feedback -->|"submits feedback"| node_session_service

click node_web "https://github.com/mgalen007/umurava-aria-project/blob/main/client/app/dashboard/page.tsx"
click node_auth_ui "https://github.com/mgalen007/umurava-aria-project/blob/main/client/app/(auth)/login/page.tsx"
click node_api_client "https://github.com/mgalen007/umurava-aria-project/blob/main/client/lib/api.ts"
click node_app "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/app.ts"
click node_auth_routes "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/auth/auth.routes.ts"
click node_auth_controller "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/auth/auth.controller.ts"
click node_auth_service "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/auth/auth.service.ts"
click node_jobs "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/jobs/jobs.routes.ts"
click node_candidates "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/candidates/candidates.routes.ts"
click node_candidate_service "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/candidates/candidates.service.ts"
click node_sessions "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.routes.ts"
click node_session_controller "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.controller.ts"
click node_session_service "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.service.ts"
click node_notifications "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/notifications/notification.service.ts"
click node_settings "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/settings/settings.routes.ts"
click node_ai "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/ai/ai.service.ts"
click node_feedback "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/ai/feedback.service.ts"
click node_normalization "https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/ai/normalize.service.ts"

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_web,node_auth_ui,node_api_client toneBlue
class node_app,node_auth_routes,node_auth_controller,node_auth_service,node_jobs,node_candidates,node_candidate_service,node_sessions,node_session_controller,node_session_service,node_notifications,node_settings toneAmber
class node_ai,node_feedback,node_normalization toneMint
class node_mongo toneRose
class node_recruiter,node_gemini,node_file_upload toneIndigo
```

## Components

### Recruiter Workspace

- [Next.js Workspace](https://github.com/mgalen007/umurava-aria-project/blob/main/client/app/dashboard/page.tsx): `client/app/dashboard/page.tsx`
- [Sign-in Pages](https://github.com/mgalen007/umurava-aria-project/blob/main/client/app/(auth)/login/page.tsx): `client/app/(auth)/login/page.tsx`
- [API Client](https://github.com/mgalen007/umurava-aria-project/blob/main/client/lib/api.ts): `client/lib/api.ts`

### Recruitment API

- [Express API](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/app.ts): `server/src/app.ts`
- [Auth Routes](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/auth/auth.routes.ts): `server/src/features/auth/auth.routes.ts`
- [Auth Controller](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/auth/auth.controller.ts): `server/src/features/auth/auth.controller.ts`
- [Auth Service](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/auth/auth.service.ts): `server/src/features/auth/auth.service.ts`
- [Job Management](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/jobs/jobs.routes.ts): `server/src/features/jobs/jobs.routes.ts`
- [Candidate Management](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/candidates/candidates.routes.ts): `server/src/features/candidates/candidates.routes.ts`
- [Candidate Ingestion](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/candidates/candidates.service.ts): `server/src/features/candidates/candidates.service.ts`
- [Session Screening](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.routes.ts): `server/src/features/sessions/sessions.routes.ts`
- [Session Controller](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.controller.ts): `server/src/features/sessions/sessions.controller.ts`
- [Session Orchestration](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/sessions/sessions.service.ts): `server/src/features/sessions/sessions.service.ts`
- [Notifications](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/notifications/notification.service.ts): `server/src/features/notifications/notification.service.ts`
- [Recruiter Settings](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/features/settings/settings.routes.ts): `server/src/features/settings/settings.routes.ts`

### Screening Intelligence

- [AI Evaluation](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/ai/ai.service.ts): `server/src/ai/ai.service.ts`
- [AI Feedback](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/ai/feedback.service.ts): `server/src/ai/feedback.service.ts`
- [Result Normalization](https://github.com/mgalen007/umurava-aria-project/blob/main/server/src/ai/normalize.service.ts): `server/src/ai/normalize.service.ts`

### Persistence

- **MongoDB**

### Other components

- **Recruiter**
- **Google Gemini**
- **Resume Files**

## Connections

- Recruiter → Sign-in Pages: signs in
- Recruiter → Next.js Workspace: manages hiring
- Sign-in Pages → API Client: requests auth
- Next.js Workspace → API Client: requests data
- API Client → Express API: calls API
- Express API → Auth Routes: dispatches auth
- Auth Routes → Auth Controller: dispatches
- Auth Controller → Auth Service: invokes
- Auth Service → MongoDB: reads and writes users
- Express API → Job Management: dispatches jobs
- Express API → Candidate Management: dispatches candidates
- Express API → Session Screening: dispatches sessions
- Express API → Recruiter Settings: dispatches settings
- Candidate Management → Candidate Ingestion: dispatches ingestion
- Resume Files → Candidate Management: uploads resumes
- Candidate Ingestion → MongoDB: stores profiles
- Job Management → MongoDB: stores postings
- Session Screening → Session Controller: dispatches
- Session Controller → Session Orchestration: invokes
- Session Orchestration → MongoDB: reads and updates
- Session Orchestration → AI Evaluation: evaluates session
- AI Evaluation → Google Gemini: requests evaluation
- Session Orchestration → Notifications: creates completion notice
- Notifications → MongoDB: stores notices
- Recruiter Settings → MongoDB: updates preferences
- Recruiter → AI Feedback: reviews results
- AI Feedback → Session Orchestration: submits feedback