# praneeth-ram/tickora-ai architecture

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

- Interactive diagram: https://gitdiagram.com/praneeth-ram/tickora-ai
- Repository: https://github.com/praneeth-ram/tickora-ai

## Overview

Tickora AI is a FastAPI attendance-and-HR chatbot that turns employee questions into read-only, permission-scoped database answers. The main workflow authenticates the employee, enters a LangGraph chat flow, interprets and corrects a query plan, validates access, executes an approved query, and formats a grounded response. The README also describes attendance, leave, work-from-home, timesheet, holiday, and schedule capabilities. Several endpoint and execution details are unsampled, so uncertain links are omitted or marked dashed.

Main entry points: [`backend/main.py`](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/main.py) (FastAPI endpoints), [`backend/services/llm_chat_service.py`](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/llm_chat_service.py) (Plan correction and answers), [`backend/agents/nodes.py`](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/agents/nodes.py) (Chat flow nodes), [`backend/services/dynamic_query_service.py`](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/dynamic_query_service.py) (Dynamic query execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_auth_dependency["Employee authentication<br/>[auth.py]"]
  node_auth_service["JWT and password service<br/>[auth_service.py]"]
  node_access["Role access policy<br/>[access_policy.py]"]
end

subgraph group_chat["Chat orchestration"]
  node_chat_graph["Chat graph<br/>[graph.py]"]
  node_chat_nodes["Chat flow nodes<br/>[nodes.py]"]
end

subgraph group_planning["Query planning"]
  node_model["Plan inference model<br/>[model_inference.py]"]
  node_chat_service["Plan correction and answers"]
  node_dates["Date resolution<br/>[date_resolver.py]"]
  node_registry["Approved operation registry"]
  node_answer["Answer construction<br/>[answer_builder.py]"]
end

subgraph group_data["Data access"]
  node_schema["Schema catalog<br/>[schema_catalog.py]"]
  node_query["Dynamic query execution"]
  node_db["Database engines<br/>[db.py]"]
end

subgraph group_domains["HR data domains"]
  node_attendance["Attendance records"]
  node_leave["Leave requests"]
  node_wfh["Work-from-home requests<br/>[wfh_repository.py]"]
  node_timesheets["Timesheets"]
  node_calendar["Holidays and schedules"]
end

node_employee(("Employee"))
node_frontend["Tickora application"]
node_postgres[("PostgreSQL")]

node_employee -->|"asks question"| node_frontend
node_frontend -->|"sends chat request"| node_api
node_api -->|"authenticates request"| node_auth_dependency
node_auth_dependency -->|"validates token"| node_auth_service
node_api -->|"resolves actor"| node_access
node_api -->|"invokes chat flow"| node_chat_graph
node_chat_graph -->|"dispatches nodes"| node_chat_nodes
node_chat_nodes -->|"corrects and answers"| node_chat_service
node_chat_nodes -->|"resolves dates"| node_dates
node_chat_nodes -->|"reads subject"| node_access
node_chat_service -->|"requests plan"| node_model
node_chat_service -->|"loads operations"| node_registry
node_chat_service -->|"executes plan"| node_query
node_chat_service -->|"builds response"| node_answer
node_registry -->|"discovers schema"| node_schema
node_query -->|"checks operations"| node_registry
node_query -->|"enforces scope"| node_access
node_query -->|"opens connection"| node_db
node_schema -->|"inspects database"| node_db
node_db -->|"connects"| node_postgres
node_api -.->|"uses repository"| node_attendance
node_api -.->|"uses repository"| node_leave
node_api -.->|"uses repository"| node_wfh
node_api -.->|"uses repository"| node_timesheets
node_api -.->|"uses repository"| node_calendar
node_answer -->|"returns answer"| node_frontend

click node_api "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/main.py"
click node_auth_dependency "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/dependencies/auth.py"
click node_auth_service "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/auth_service.py"
click node_access "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/security/access_policy.py"
click node_chat_graph "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/agents/graph.py"
click node_chat_nodes "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/agents/nodes.py"
click node_model "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/model_inference.py"
click node_chat_service "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/llm_chat_service.py"
click node_dates "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/date_resolver.py"
click node_registry "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/operation_registry.py"
click node_schema "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/schema_catalog.py"
click node_query "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/dynamic_query_service.py"
click node_db "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/db.py"
click node_answer "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/answer_builder.py"
click node_attendance "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/attendance_repository.py"
click node_leave "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/leave_repository.py"
click node_wfh "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/wfh_repository.py"
click node_timesheets "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/timesheet_repository.py"
click node_calendar "https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/calendar_repository.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,node_auth_dependency,node_auth_service,node_access toneBlue
class node_chat_graph,node_chat_nodes,node_postgres toneAmber
class node_model,node_chat_service,node_dates,node_registry,node_answer toneMint
class node_schema,node_query,node_db toneRose
class node_attendance,node_leave,node_wfh,node_timesheets,node_calendar,node_employee,node_frontend toneIndigo
```

## Components

### API and identity

- [FastAPI endpoints](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/main.py): `backend/main.py`
- [Employee authentication](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/dependencies/auth.py): `backend/dependencies/auth.py`
- [JWT and password service](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/auth_service.py): `backend/services/auth_service.py`
- [Role access policy](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/security/access_policy.py): `backend/security/access_policy.py`

### Chat orchestration

- [Chat graph](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/agents/graph.py): `backend/agents/graph.py`
- [Chat flow nodes](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/agents/nodes.py): `backend/agents/nodes.py`

### Query planning

- [Plan inference model](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/model_inference.py): `backend/services/model_inference.py`
- [Plan correction and answers](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/llm_chat_service.py): `backend/services/llm_chat_service.py`
- [Date resolution](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/date_resolver.py): `backend/services/date_resolver.py`
- [Approved operation registry](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/operation_registry.py): `backend/services/operation_registry.py`
- [Answer construction](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/answer_builder.py): `backend/services/answer_builder.py`

### Data access

- [Schema catalog](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/schema_catalog.py): `backend/services/schema_catalog.py`
- [Dynamic query execution](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/services/dynamic_query_service.py): `backend/services/dynamic_query_service.py`
- [Database engines](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/db.py): `backend/db.py`

### HR data domains

- [Attendance records](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/attendance_repository.py): `backend/repositories/attendance_repository.py`
- [Leave requests](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/leave_repository.py): `backend/repositories/leave_repository.py`
- [Work-from-home requests](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/wfh_repository.py): `backend/repositories/wfh_repository.py`
- [Timesheets](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/timesheet_repository.py): `backend/repositories/timesheet_repository.py`
- [Holidays and schedules](https://github.com/praneeth-ram/tickora-ai/blob/main/backend/repositories/calendar_repository.py): `backend/repositories/calendar_repository.py`

### Other components

- **Employee**
- **Tickora application**
- **PostgreSQL**

## Connections

- Employee → Tickora application: asks question
- Tickora application → FastAPI endpoints: sends chat request
- FastAPI endpoints → Employee authentication: authenticates request (evidence: `backend/main.py`)
- Employee authentication → JWT and password service: validates token (evidence: `backend/dependencies/auth.py`)
- FastAPI endpoints → Role access policy: resolves actor (evidence: `backend/main.py`)
- FastAPI endpoints → Chat graph: invokes chat flow (evidence: `backend/main.py`)
- Chat graph → Chat flow nodes: dispatches nodes (evidence: `backend/agents/graph.py`)
- Chat flow nodes → Plan correction and answers: corrects and answers (evidence: `backend/agents/nodes.py`)
- Chat flow nodes → Date resolution: resolves dates (evidence: `backend/agents/nodes.py`)
- Chat flow nodes → Role access policy: reads subject (evidence: `backend/agents/nodes.py`)
- Plan correction and answers → Plan inference model: requests plan (evidence: `backend/services/llm_chat_service.py`)
- Plan correction and answers → Approved operation registry: loads operations (evidence: `backend/services/llm_chat_service.py`)
- Plan correction and answers → Dynamic query execution: executes plan (evidence: `backend/services/llm_chat_service.py`)
- Plan correction and answers → Answer construction: builds response (evidence: `backend/services/llm_chat_service.py`)
- Approved operation registry → Schema catalog: discovers schema (evidence: `backend/services/operation_registry.py`)
- Dynamic query execution → Approved operation registry: checks operations (evidence: `backend/services/dynamic_query_service.py`)
- Dynamic query execution → Role access policy: enforces scope (evidence: `backend/services/dynamic_query_service.py`)
- Dynamic query execution → Database engines: opens connection (evidence: `backend/services/dynamic_query_service.py`)
- Schema catalog → Database engines: inspects database (evidence: `backend/services/schema_catalog.py`)
- Database engines → PostgreSQL: connects (evidence: `backend/db.py`)
- FastAPI endpoints → Attendance records: uses repository (evidence: `backend/main.py`)
- FastAPI endpoints → Leave requests: uses repository (evidence: `backend/main.py`)
- FastAPI endpoints → Work-from-home requests: uses repository (evidence: `backend/main.py`)
- FastAPI endpoints → Timesheets: uses repository (evidence: `backend/main.py`)
- FastAPI endpoints → Holidays and schedules: uses repository (evidence: `backend/main.py`)
- Answer construction → Tickora application: returns answer
