---

title: HelpDesk AI Backend emoji: 🤖 colorFrom: green colorTo: blue sdk: docker pinned: false

---

🌟 GSSoC '26 Contributor & Community Campaign

We are extremely proud to be part of the GirlScript Summer of Code (GSSoC) 2026! To ensure high-quality contributions and maximum rewards for both developers and mentors, please review our official GSSoC Mentorship Guide & Review Standard.

To support the project and get real-time open-source project updates, please make sure you participate in our community campaign:

---

[!NOTE]

Eliminating the Manual Triage Bottleneck

Helpdesk.ai uses deep-learning neural networks and 4-layer enterprise architecture to categorize, prioritize, and resolve IT issues in milliseconds.

Table of Contents

• Neural System Orchestrator
• 🎯 Why Helpdesk.AI?
• 💎 The Enterprise Evolution
• 🏗️ System Architecture
• 🧠 The AI Neural Pipeline
• 🚀 Deployment & Operations
• 🗺️ Roadmap
• 📱 Mobile Ecosystem (V1)
• 🗄️ Database Schema
• 👥 Contributors

---

---

🛠️ Tech Stack

HelpDesk.AI is built with a modern, multi-layer technology stack:

Layer	Technology	Version
Frontend	React	19.2
Frontend	Vite	7.x
Frontend	TailwindCSS	3.4
Frontend	React Router	7.x
Frontend	Zustand	5.x
Frontend	Ant Design (antd)	6.x
Frontend	Recharts	3.x
Frontend	Framer Motion	12.x
Frontend	Tesseract.js (OCR)	7.x
Mobile	React Native + Expo	SDK 54
Mobile	Expo Router / Navigation	7.x
Backend	FastAPI	0.104+
Backend	Python	3.10
Backend	Uvicorn	0.24+
Backend	PyTorch	2.0+
Backend	HuggingFace Transformers	4.35+
Backend	Sentence-Transformers	2.2+
Backend	EasyOCR	latest
AI/ML	Google Gemini (google-genai)	latest
AI/ML	DistilBERT Classifier	custom
AI/ML	NER Model	custom
Database	Supabase (PostgreSQL)	2.22
Deployment	Docker	python:3.10-slim
Deployment	Vercel	production
Deployment	HuggingFace Spaces	docker

[!IMPORTANT]

🎯 Why Helpdesk.AI?

Helpdesk.AI is more than just a ticketing tool; it is a Neural Service Orchestrator designed for modern enterprises. It provides massive ROI by:

1. Eliminating the Triage Bottleneck: By using context-aware AI (DistilBERT), it categorizes 100% of tickets in milliseconds, bypassing the L1 support line entirely.
2. Proactive Resolution: Integrated LLMs (GitHub Models/Gemini) analyze issues during creation to suggest "Instant Fixes," severely reducing actual ticket volume.
3. Tiered Multi-Tenancy: Built for true SaaS isolation, it securely isolates completely separate companies within a single Supabase database.

---

💎 The Enterprise Evolution

Helpdesk.ai isn't just a ticketing tool; it's heavily engineered. Built to handle the complex requirements of modern organizations, it scales support without scaling headcount.

🏛️ 4-Layer Permission Matrix

Layer	Audience	Primary Capabilities
👑 Master Admin	Global Overseers	Tenant Registration, Company Onboarding, Global Health Monitoring.
🏢 Company Admin	IT Management	Org-specific Dashboard, User Auditing, Sentiment Analytics.
👤 Standard User	Employees	AI-Powered Ticket Creation, Semantic Search, Real-time Status.
🌐 Public Layer	Prospects	Premium journey, Sales Engineering contact, Live Pricing tiers.

---

🏗️ System Architecture

Helpdesk.ai utilizes a clean, decoupled architecture built for production operations.

graph TD
    A["User (Frontend)"] -->|"Submits Issue"| B("FastAPI Backend")
    B -->|"Text Processing"| C{"AI Inference Engine"}
    C -->|"DistilBERT v3"| D["Categorization Routing"]
    C -->|"NER Engine"| E["Entity Extraction"]
    C -->|"GitHub Models Inference"| F["Generative Resolves"]
    D --> G[("Supabase DB")]
    E --> G
    F --> G
    G -->|"Real-time WebSocket"| A
    G -->|"Dashboard Aggregation"| H["Admin Portal"]

---

📁 Project Structure

This document outlines the key directories in the HELPDESK.AI repository to help contributors navigate the codebase efficiently.

HELPDESK.AI/
├── Frontend/          # React frontend application (Vite-based)
├── backend/           # Backend API services
├── MobileApp/         # Mobile application (Android)
├── Model/             # ML models and AI inference code
├── supabase/          # Supabase database configuration and migrations
├── scripts/           # Utility and automation scripts
├── docs/              # Documentation files
├── app/               # Main application entry point
├── src/               # Source code modules
├── tests/             # Test suites and fixtures
├── k8s/               # Kubernetes deployment manifests
├── deploy/            # Deployment configurations and scripts
├── middleware/        # Express/FastAPI middleware components
├── utils/             # Helper functions and utilities
├── static/            # Static assets (CSS, images)
├── templates/         # HTML templates
└── ...

Directory	Purpose
Frontend/	React-based web UI built with Vite
backend/	FastAPI/Node.js backend API services
MobileApp/	React Native mobile application
Model/	Machine learning models (DistilBERT, NER, OCR)
supabase/	Database schema, migrations, and edge functions
scripts/	Build, deployment, and utility scripts
docs/	Project documentation and guides
app/	Core application logic
src/	Shared source modules and libraries
tests/	Unit, integration, and E2E tests
k8s/	Kubernetes manifests for production deployment
deploy/	CI/CD pipelines and deployment configs
middleware/	Authentication, logging, and request middleware
utils/	Common utilities and helper functions
static/	Static assets served by the application
templates/	HTML/email templates

---

🗄️ Database Schema

The full table catalog, relationships, and migration-owned schema objects are documented in docs/helpdesk_schema.md.

---

🧠 The AI Neural Pipeline

Under the hood, Helpdesk.ai leverages a custom suite of high speed models.

1. High-Precision Classification Driven by DistilBERT v3, our classifier understands technical context and user sentiment to assign accurate Impact Scores. 2. NER Metadata Harvesting Automatically extracts vital technical identifiers without making the user fill out long dropdown forms: Hostnames, Serial Numbers, IP Addresses.

3. Duplicate Prevention If two users report the same outage, our sentence-transformers semantically link them to prevent "Ticket Flooding". 4. Generative OCR Built-in screenshot analysis pulls error codes directly out of images. We process the images securely in milliseconds.

---

🚀 Deployment & Operations

Create a .env file in the /Frontend directory:

VITE_SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
VITE_SUPABASE_ANON_KEY=your_key
VITE_STRIPE_GROWTH_LINK=your_stripe_link
VITE_BACKEND_URL=http://localhost:8000

Backend Environment Variables

Copy backend/.env.example to backend/.env and fill in your values:

cd backend
cp .env.example .env

Variable	Description	Example
SUPABASE_URL	Your Supabase project URL	https://xxx.supabase.co
SUPABASE_SERVICE_KEY	Service role key (keep secret!)	eyJhbGciOiJIUzI1NiIs...
ALLOW_DEGRADED_STARTUP	Allow startup even if models fail	0 (strict) or 1 (lenient)
SENTENCE_TRANSFORMER_MODEL_PATH	Local model path (optional)	./models/all-MiniLM-L6-v2
REQUIRE_SUPABASE	Include Supabase in readiness gate	false or true

Notes:

• SUPABASE_SERVICE_KEY is the service role key (not the anon key). Find it in Supabase Dashboard > Project Settings > API.
• If ALLOW_DEGRADED_STARTUP=1, the backend starts even if model downloads fail.
• SENTENCE_TRANSFORMER_MODEL_PATH avoids HuggingFace downloads. Download models manually first, then set the path.
• REQUIRE_SUPABASE=true makes the readiness check fail if Supabase is unreachable.

### Local Installation

```bash
git clone https://github.com/riteshbonthalakoti/HELPDESK.AI.git
cd HELPDESK.AI/Frontend
npm install
npm run dev

Healthcheck Verification Checklist

Use this checklist after local Docker/container startup and before promoting a deployment:

1. Confirm the API process is listening

   curl -fsS http://localhost:7860/health
   

   Expected result: HTTP 200 with status: "ok". This confirms the FastAPI app is reachable.

2. Check readiness for model-dependent traffic

   curl -fsS http://localhost:7860/ready
   

   Expected result: HTTP 200 with status: "ready" when required model services and configured dependencies are available. A 503 response means at least one readiness check is still failing and the instance should not receive production traffic yet.

3. Run the container healthcheck script

   cd backend
   HEALTHCHECK_URL=http://localhost:7860/ready python healthcheck.py
   

   Expected result: exit code 0. Override HEALTHCHECK_TIMEOUT_SECONDS if the local environment needs a longer probe timeout.

4. Verify runtime configuration

   • Set REQUIRE_SUPABASE=true when the deployment must fail readiness without Supabase configuration.
   • Use ALLOW_DEGRADED_STARTUP=1 only for local development or controlled smoke tests where duplicate-index and RAG availability are optional.
   • Confirm frontend VITE_BACKEND_URL points to the same backend URL being checked.

5. Inspect deployment logs if readiness fails

   • Review startup logs for classifier, NER, duplicate-index, RAG, and Supabase initialization messages.
   • Re-run /ready after fixing configuration or model asset issues.
   • Do not route user traffic to the instance until readiness returns ready.

---

⚙️ Tech Stack

Category	Technology	Purpose
Backend Framework	FastAPI	High-performance async REST API
AI/ML	Google Gemini	AI-powered ticket analysis & summarization
AI/ML	DistilBERT + Sentence Transformers	Ticket categorization & semantic search
Database	Supabase (PostgreSQL)	Multi-tenant data storage with Row-Level Security
Frontend	Next.js + Tailwind CSS	Modern reactive dashboard UI
Containerization	Docker	Consistent deployment across environments
CI/CD	GitHub Actions	Automated testing and deployment
Rate Limiting	SlowAPI	API rate limiting and DoS protection
Mobile	Android (Kotlin)	Native mobile app for on-the-go ticket management
Monitoring	LogRocket	Session replay and frontend error tracking

See .env.example for required environment variables.

---

🗺️ Roadmap

• Phase 1: Core Ticketing & DistilBERT Categorization.
• Phase 2: Multi-tenant SaaS Architecture (Supabase RLS).
• Phase 3: GitHub Models integration for generative knowledge-base articles.
• Phase 4: SAP / ServiceNow direct bidirectional sync.
• Phase 5: AI Voice Support Agent via Twilio.

---

📱 Mobile Ecosystem (V1)

Helpdesk.ai is now available as a native Android application. It features a complete mobile-first experience for employees and admins.

• Real-time Status Tracking: Instant updates on ticket progress with custom in-app notifications.
• Biometric Ready: Secure access with enterprise-grade authentication.
• Smart Onboarding: Dynamic routing for new users and pending registrations.
• Session Replay: Integrated with LogRocket for proactive debugging and user support.

📥 Download HelpDesk.ai V1 APK

---

✨ Contributors

Thanks goes to these wonderful people for contributing to this project ❤️

---