# marwakhot/orion architecture

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

- Interactive diagram: https://gitdiagram.com/marwakhot/orion
- Repository: https://github.com/marwakhot/orion

## Overview

Orion is an HR and recruitment platform whose main workflow takes candidates from CV upload and job discovery through applications, assessments, and HR decisions; it also supports employee onboarding. The FastAPI application exposes these capabilities to candidate and HR users, with Supabase for persistence and AI services for parsing, matching, interviews, and knowledge-grounded chat. The README documents product capabilities not fully evidenced in sampled source. Edges are limited to explicit imports/calls, application registration, or documented workflows; some unsampled subsystem links are therefore omitted.

Main entry points: [`backend/main.py`](https://github.com/marwakhot/orion/blob/main/backend/main.py) (FastAPI app), [`backend/routers/applications.py`](https://github.com/marwakhot/orion/blob/main/backend/routers/applications.py) (Applications), [`backend/database.py`](https://github.com/marwakhot/orion/blob/main/backend/database.py) (Database client), [`backend/routers/cvs.py`](https://github.com/marwakhot/orion/blob/main/backend/routers/cvs.py) (CV management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_frontend["Web client<br/>[api.js]"]
  node_api["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_identity["JWT utilities<br/>[auth_utils.py]"]
  node_access["Access control<br/>[dependencies.py]"]
end

subgraph group_hiring["Recruitment workflow"]
  node_jobs["Job roles<br/>[jobs.py]"]
  node_cv["CV management<br/>[cvs.py]"]
  node_cvparse["CV parsing<br/>[cv_parser.py]"]
  node_matching["CV matching<br/>[cv_matching.py]"]
  node_applications["Applications<br/>[applications.py]"]
  node_assessment["Behavioral assessment<br/>[assessments.py]"]
  node_interviews["Interview management<br/>[interviews.py]"]
  node_feedback["HR feedback<br/>[feedback.py]"]
  node_email["Hiring email<br/>[email_service.py]"]
end

subgraph group_onboarding["Employee onboarding"]
  node_onboarding["Onboarding tasks<br/>[onboarding.py]"]
  node_templates["Onboarding templates"]
  node_team["Team directory<br/>[team.py]"]
end

subgraph group_platform["AI and persistence"]
  node_chat["HR assistant chat<br/>[chat_service.py]"]
  node_rag["Knowledge retrieval<br/>[rag_engine.py]"]
  node_vectors["Vector search<br/>[vector_store.py]"]
  node_ai["AI services<br/>[ai_service.py]"]
  node_dbclient["Database client<br/>[database.py]"]
end

node_candidate(("Candidate"))
node_hr(("HR staff"))
node_supabase[("Supabase")]
node_groq["Groq API"]
node_mailservice["Email delivery"]

node_candidate -->|"uses portal"| node_frontend
node_hr -->|"uses portal"| node_frontend
node_frontend -.->|"calls API"| node_api
node_api -->|"registers router"| node_auth
node_api -->|"registers router"| node_jobs
node_api -->|"registers router"| node_applications
node_api -->|"registers router"| node_cv
node_api -->|"registers router"| node_assessment
node_api -->|"registers router"| node_interviews
node_api -->|"registers router"| node_feedback
node_api -->|"registers router"| node_onboarding
node_api -->|"registers router"| node_templates
node_api -->|"registers router"| node_team
node_api -->|"exposes assistant"| node_chat
node_auth -->|"creates tokens"| node_identity
node_access -->|"decodes tokens"| node_identity
node_auth -->|"queries users"| node_dbclient
node_cv -->|"parses uploads"| node_cvparse
node_cv -->|"finds matched roles"| node_matching
node_applications -->|"requests rejection email"| node_email
node_applications -->|"reads and writes"| node_dbclient
node_email -->|"generates feedback"| node_ai
node_email -->|"sends messages"| node_mailservice
node_chat -->|"generates answers"| node_rag
node_chat -->|"stores conversations"| node_dbclient
node_rag -->|"embeds and generates"| node_ai
node_rag -->|"searches context"| node_vectors
node_vectors -->|"queries vectors"| node_dbclient
node_ai -.->|"requests completions"| node_groq
node_dbclient -->|"creates client"| node_supabase
node_candidate -->|"uploads CV"| node_cv
node_candidate -->|"submits applications"| node_applications
node_candidate -->|"completes assessment"| node_assessment
node_hr -->|"schedules interviews"| node_interviews
node_hr -->|"adds interview notes"| node_feedback
node_hr -->|"ranks candidates"| node_applications
node_candidate -->|"tracks tasks"| node_onboarding
node_candidate -->|"explores directory"| node_team
node_onboarding -->|"uses templates"| node_templates
node_candidate -->|"asks HR questions"| node_chat

click node_frontend "https://github.com/marwakhot/orion/blob/main/frontend/api.js"
click node_api "https://github.com/marwakhot/orion/blob/main/backend/main.py"
click node_auth "https://github.com/marwakhot/orion/blob/main/backend/routers/auth.py"
click node_identity "https://github.com/marwakhot/orion/blob/main/backend/auth_utils.py"
click node_access "https://github.com/marwakhot/orion/blob/main/backend/dependencies.py"
click node_jobs "https://github.com/marwakhot/orion/blob/main/backend/routers/jobs.py"
click node_cv "https://github.com/marwakhot/orion/blob/main/backend/routers/cvs.py"
click node_cvparse "https://github.com/marwakhot/orion/blob/main/backend/services/cv_parser.py"
click node_matching "https://github.com/marwakhot/orion/blob/main/backend/services/cv_matching.py"
click node_applications "https://github.com/marwakhot/orion/blob/main/backend/routers/applications.py"
click node_assessment "https://github.com/marwakhot/orion/blob/main/backend/routers/assessments.py"
click node_interviews "https://github.com/marwakhot/orion/blob/main/backend/routers/interviews.py"
click node_feedback "https://github.com/marwakhot/orion/blob/main/backend/routers/feedback.py"
click node_email "https://github.com/marwakhot/orion/blob/main/backend/services/email_service.py"
click node_onboarding "https://github.com/marwakhot/orion/blob/main/backend/routers/onboarding.py"
click node_templates "https://github.com/marwakhot/orion/blob/main/backend/routers/onboarding_templates.py"
click node_team "https://github.com/marwakhot/orion/blob/main/backend/routers/team.py"
click node_chat "https://github.com/marwakhot/orion/blob/main/backend/services/chat_service.py"
click node_rag "https://github.com/marwakhot/orion/blob/main/backend/services/rag_engine.py"
click node_vectors "https://github.com/marwakhot/orion/blob/main/backend/services/vector_store.py"
click node_ai "https://github.com/marwakhot/orion/blob/main/backend/services/ai_service.py"
click node_dbclient "https://github.com/marwakhot/orion/blob/main/backend/database.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_frontend,node_api,node_auth,node_identity,node_access toneBlue
class node_jobs,node_cv,node_cvparse,node_matching,node_applications,node_assessment,node_interviews,node_feedback,node_email,node_supabase toneAmber
class node_onboarding,node_templates,node_team,node_groq toneMint
class node_chat,node_rag,node_vectors,node_ai,node_dbclient toneRose
class node_candidate,node_hr,node_mailservice toneIndigo
```

## Components

### Application entry

- [Web client](https://github.com/marwakhot/orion/blob/main/frontend/api.js): `frontend/api.js`
- [FastAPI app](https://github.com/marwakhot/orion/blob/main/backend/main.py): `backend/main.py`
- [Authentication](https://github.com/marwakhot/orion/blob/main/backend/routers/auth.py): `backend/routers/auth.py`
- [JWT utilities](https://github.com/marwakhot/orion/blob/main/backend/auth_utils.py): `backend/auth_utils.py`
- [Access control](https://github.com/marwakhot/orion/blob/main/backend/dependencies.py): `backend/dependencies.py`

### Recruitment workflow

- [Job roles](https://github.com/marwakhot/orion/blob/main/backend/routers/jobs.py): `backend/routers/jobs.py`
- [CV management](https://github.com/marwakhot/orion/blob/main/backend/routers/cvs.py): `backend/routers/cvs.py`
- [CV parsing](https://github.com/marwakhot/orion/blob/main/backend/services/cv_parser.py): `backend/services/cv_parser.py`
- [CV matching](https://github.com/marwakhot/orion/blob/main/backend/services/cv_matching.py): `backend/services/cv_matching.py`
- [Applications](https://github.com/marwakhot/orion/blob/main/backend/routers/applications.py): `backend/routers/applications.py`
- [Behavioral assessment](https://github.com/marwakhot/orion/blob/main/backend/routers/assessments.py): `backend/routers/assessments.py`
- [Interview management](https://github.com/marwakhot/orion/blob/main/backend/routers/interviews.py): `backend/routers/interviews.py`
- [HR feedback](https://github.com/marwakhot/orion/blob/main/backend/routers/feedback.py): `backend/routers/feedback.py`
- [Hiring email](https://github.com/marwakhot/orion/blob/main/backend/services/email_service.py): `backend/services/email_service.py`

### Employee onboarding

- [Onboarding tasks](https://github.com/marwakhot/orion/blob/main/backend/routers/onboarding.py): `backend/routers/onboarding.py`
- [Onboarding templates](https://github.com/marwakhot/orion/blob/main/backend/routers/onboarding_templates.py): `backend/routers/onboarding_templates.py`
- [Team directory](https://github.com/marwakhot/orion/blob/main/backend/routers/team.py): `backend/routers/team.py`

### AI and persistence

- [HR assistant chat](https://github.com/marwakhot/orion/blob/main/backend/services/chat_service.py): `backend/services/chat_service.py`
- [Knowledge retrieval](https://github.com/marwakhot/orion/blob/main/backend/services/rag_engine.py): `backend/services/rag_engine.py`
- [Vector search](https://github.com/marwakhot/orion/blob/main/backend/services/vector_store.py): `backend/services/vector_store.py`
- [AI services](https://github.com/marwakhot/orion/blob/main/backend/services/ai_service.py): `backend/services/ai_service.py`
- [Database client](https://github.com/marwakhot/orion/blob/main/backend/database.py): `backend/database.py`

### Other components

- **Candidate**
- **HR staff**
- **Supabase**
- **Groq API**
- **Email delivery**

## Connections

- Candidate → Web client: uses portal
- HR staff → Web client: uses portal
- Web client → FastAPI app: calls API
- FastAPI app → Authentication: registers router (evidence: `backend/main.py`)
- FastAPI app → Job roles: registers router (evidence: `backend/main.py`)
- FastAPI app → Applications: registers router (evidence: `backend/main.py`)
- FastAPI app → CV management: registers router (evidence: `backend/main.py`)
- FastAPI app → Behavioral assessment: registers router (evidence: `backend/main.py`)
- FastAPI app → Interview management: registers router (evidence: `backend/main.py`)
- FastAPI app → HR feedback: registers router (evidence: `backend/main.py`)
- FastAPI app → Onboarding tasks: registers router (evidence: `backend/main.py`)
- FastAPI app → Onboarding templates: registers router (evidence: `backend/main.py`)
- FastAPI app → Team directory: registers router (evidence: `backend/main.py`)
- FastAPI app → HR assistant chat: exposes assistant (evidence: `backend/main.py`)
- Authentication → JWT utilities: creates tokens (evidence: `backend/routers/auth.py`)
- Access control → JWT utilities: decodes tokens (evidence: `backend/dependencies.py`)
- Authentication → Database client: queries users (evidence: `backend/routers/auth.py`)
- CV management → CV parsing: parses uploads (evidence: `backend/routers/cvs.py`)
- CV management → CV matching: finds matched roles (evidence: `backend/routers/cvs.py`)
- Applications → Hiring email: requests rejection email (evidence: `backend/routers/applications.py`)
- Applications → Database client: reads and writes (evidence: `backend/routers/applications.py`)
- Hiring email → AI services: generates feedback (evidence: `backend/services/email_service.py`)
- Hiring email → Email delivery: sends messages (evidence: `backend/services/email_service.py`)
- HR assistant chat → Knowledge retrieval: generates answers (evidence: `backend/services/chat_service.py`)
- HR assistant chat → Database client: stores conversations (evidence: `backend/services/chat_service.py`)
- Knowledge retrieval → AI services: embeds and generates (evidence: `backend/services/rag_engine.py`)
- Knowledge retrieval → Vector search: searches context (evidence: `backend/services/rag_engine.py`)
- Vector search → Database client: queries vectors (evidence: `backend/services/vector_store.py`)
- AI services → Groq API: requests completions
- Database client → Supabase: creates client (evidence: `backend/database.py`)
- Candidate → CV management: uploads CV
- Candidate → Applications: submits applications
- Candidate → Behavioral assessment: completes assessment
- HR staff → Interview management: schedules interviews
- HR staff → HR feedback: adds interview notes
- HR staff → Applications: ranks candidates
- Candidate → Onboarding tasks: tracks tasks
- Candidate → Team directory: explores directory
- Onboarding tasks → Onboarding templates: uses templates
- Candidate → HR assistant chat: asks HR questions
