Skip to content
BranchesTags

Repository files navigation

HR Chatbot - DocuFlow

An intelligent HR management system with AI-powered policy chatbot, automated reimbursement workflows, and secure authentication.

Features

1. AI-Powered HR Policy Chatbot

  • RAG (Retrieval-Augmented Generation) system using LangChain and Google Gemini
  • Interactive chat interface for querying company HR policies
  • Source document citations for transparency
  • Powered by FAISS vector store for efficient semantic search
  • Real-time responses with context-aware answers

2. Smart Reimbursement System

  • Bill submission with file upload
  • AI-generated reimbursement email drafts
  • Three categories: Gym, Medicine, Late Sitting Meal
  • Automated email scheduling (monthly on last day at 9 AM)
  • Draft, scheduled, and sent email tracking

3. Secure Authentication

  • Multi-step registration: Email → OTP → Password
  • Email verification with time-bound OTP (10-minute validity)
  • Organization email domain restriction
  • Password management
  • 30-day email verification expiration

Technology Stack

  • Backend: Django 5.0.0, Python 3.x
  • Database: SQLite3 (development), PostgreSQL recommended for production
  • AI/ML:
    • LangChain for RAG orchestration
    • Google Gemini API for LLM
    • HuggingFace Sentence Transformers for embeddings
    • FAISS for vector similarity search
  • Email: Django SMTP with Gmail
  • Task Scheduling: django-crontab
  • Frontend: HTML5, CSS3, Vanilla JavaScript

Quick Start

Prerequisites

  • Python 3.8+
  • pip
  • Virtual environment (recommended)
  • Google Gemini API key
  • Gmail account with app password

Installation

  1. Clone the repository

    git clone https://github.com/farooq78692/docsnow.git
cd docsnow

  2. Create and activate virtual environment

    python -m venv venv

# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Set up environment variables

    cp .env.example .env

    Edit .env and add your credentials:

    DJANGO_SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

GOOGLE_API_KEY=your_google_gemini_api_key
EMAIL_HOST_USER=your_email@gmail.com
EMAIL_HOST_PASSWORD=your_gmail_app_password
DEFAULT_FROM_EMAIL=your_email@gmail.com
HR_EMAIL_RECIPIENT=hr@yourcompany.com

  5. Run database migrations

    python manage.py migrate

  6. Create a superuser

    python manage.py createsuperuser

  7. Add HR policy document

    • Place your HR policies PDF in data/hr_policies.pdf
    • The system will automatically process it on first use

  8. Run the development server

    python manage.py runserver

  9. Access the application

Configuration

Google Gemini API Key

  1. Go to Google AI Studio
  2. Create a new API key
  3. Add it to your .env file as GOOGLE_API_KEY

Gmail Configuration

  1. Enable 2-Factor Authentication on your Gmail account
  2. Generate an App Password
  3. Use the app password in .env as EMAIL_HOST_PASSWORD

Email Domain Restriction

To restrict registration to specific email domains:

  1. Edit authentication/utils.py:44
  2. Modify the allowed_domains list: 
    allowed_domains = ['yourcompany.com', 'yourdomain.net']

HR Email Recipient

Set the default HR recipient in .env:

HR_EMAIL_RECIPIENT=hr@yourcompany.com

Usage

For Users

  1. Registration

    • Visit /auth/register/
    • Enter your organization email
    • Verify with OTP sent to your email
    • Complete registration with password

  2. HR Policy Chatbot

    • Navigate to the chatbot after login
    • Ask questions about company policies
    • View source references for each answer

  3. Submit Reimbursement

    • Go to "Submit Bill" in navigation
    • Upload bill image/document
    • Select category and enter amount
    • AI generates email draft automatically
    • Review and edit email before scheduling

  4. Manage Emails

    • View all your scheduled/sent emails
    • Edit draft emails
    • Track email status

For Administrators

  1. Access Admin Panel

    • Visit /admin/
    • Login with superuser credentials

  2. Manage Users

    • View registered users
    • Check email verification status
    • Manage user permissions

  3. Monitor Bills & Emails

    • Review submitted bills
    • Track email sending status
    • View scheduled emails

Scheduled Tasks

Monthly Email Sending

The system automatically sends scheduled reimbursement emails on the last day of each month at midnight UTC.

Setup cron job:

  1. Add cron jobs to system:

    python manage.py crontab add

  2. Verify cron jobs:

    python manage.py crontab show

  3. Remove cron jobs (if needed):

    python manage.py crontab remove

Project Structure

docsnow/
├── authentication/           # User auth, registration, email verification
│   ├── models.py            # User, EmailVerification, RegistrationSession
│   ├── views.py             # Registration, login, profile
│   ├── forms.py             # Email, OTP, registration forms
│   └── utils.py             # Email sending, OTP generation
├── chatbot/                 # AI-powered HR chatbot
│   ├── views.py             # Chat interface and API endpoint
│   └── utils/
│       └── langchain_utils.py  # RAG chain setup
├── billings/                # Reimbursement management
│   ├── models.py            # Bill, Email models
│   ├── views.py             # Bill submission, email management
│   ├── forms.py             # Bill and email forms
│   ├── cron.py              # Scheduled email sending
│   └── utils.py             # Email utilities
├── hr_chatbot/              # Django project settings
│   ├── settings.py          # Configuration
│   └── urls.py              # URL routing
├── templates/               # HTML templates
│   ├── authentication/      # Auth templates
│   ├── chatbot/             # Chat interface
│   ├── billings/            # Bill & email templates
│   └── shared/              # Base templates, navbar
├── data/
│   └── hr_policies.pdf      # Source document for RAG
├── bills/                   # Uploaded bill files
├── vectorstore/             # FAISS vector store cache
├── .env                     # Environment variables (DO NOT COMMIT)
├── .env.example             # Environment template
├── .gitignore               # Git ignore rules
├── requirements.txt         # Python dependencies
└── manage.py                # Django management script

API Endpoints

Chat API

POST /api/chat/

Send a question to the HR chatbot.

Request:

{
  "question": "What is the vacation policy?"
}

Response:

{
  "answer": "According to company policy...",
  "sources": [
    {
      "content": "Relevant excerpt from policy document...",
      "metadata": {
        "page": 5,
        "source": "hr_policies.pdf"
      }
    }
  ]
}

Authentication: Required (session-based)

CSRF: Required (include X-CSRFToken header)

Database Models

Authentication App

User (extends AbstractUser)

  • email: Primary identifier (unique)
  • email_verified: Boolean flag
  • email_verified_date: Verification timestamp
  • created_at: Account creation date

EmailVerification

  • id: UUID primary key
  • email: Email address
  • otp: 6-digit verification code
  • is_used: Usage status
  • expires_at: Expiration timestamp

RegistrationSession

  • id: UUID primary key
  • email: Registration email
  • email_verified: Email verification status
  • otp_verified: OTP verification status
  • expires_at: Session expiration

Billings App

Bill

  • file: Uploaded bill document
  • bill_category: Gym / Medicine / Late Sitting Meal
  • bill_amount: Decimal field
  • raw_text: OCR/extracted text (optional)
  • uploaded_at: Upload timestamp

Email

  • user: Foreign key to User
  • subject: Email subject
  • body: Email content
  • recipient: Recipient email address
  • cc, bcc: Optional fields
  • status: Draft / Scheduled / Sent
  • bill: Foreign key to Bill (optional)
  • scheduled_time: When to send
  • sent_at: Actual send time
  • created_at, updated_at: Timestamps

Security

Critical Security Notes

  1. Never commit .env file - Contains sensitive credentials
  2. Change Django SECRET_KEY - Generate a new one for production
  3. Set DEBUG=False in production
  4. Configure ALLOWED_HOSTS with your domain
  5. Use HTTPS in production
  6. Rotate API keys regularly
  7. Review file upload permissions on bills directory

Production Checklist

  • Set DEBUG=False
  • Configure ALLOWED_HOSTS with your domain
  • Use PostgreSQL instead of SQLite
  • Set up proper logging
  • Configure static files with WhiteNoise or CDN
  • Set up SSL/TLS certificates
  • Use environment-specific settings
  • Set up database backups
  • Configure rate limiting
  • Set up monitoring and alerts
  • Review and update dependencies

Troubleshooting

Common Issues

1. Vector store error on first chatbot use

  • Cause: FAISS index not created yet
  • Solution: The system will automatically create it on first query (may take 30-60 seconds)

2. OTP not received

  • Cause: Gmail authentication failure
  • Solution: Verify Gmail app password is correct, check spam folder

3. CSRF verification failed on chat

  • Cause: Missing CSRF token in request
  • Solution: Clear browser cookies and reload page

4. Bill file upload fails

  • Cause: bills/ directory permissions
  • Solution: Ensure bills/ directory exists and is writable

5. Scheduled emails not sending

  • Cause: Cron job not configured
  • Solution: Run python manage.py crontab add

Development

Running Tests

python manage.py test

Creating Migrations

python manage.py makemigrations
python manage.py migrate

Collecting Static Files

python manage.py collectstatic

Code Style

This project follows PEP 8 guidelines. Use tools like black and flake8:

pip install black flake8
black .
flake8 .

Deployment

Recommended Stack

  • Hosting: AWS EC2, DigitalOcean, Heroku, or Railway
  • Database: PostgreSQL
  • Web Server: Gunicorn + Nginx
  • SSL: Let's Encrypt (Certbot)
  • Static Files: AWS S3 or WhiteNoise

Environment Variables for Production

DJANGO_SECRET_KEY=<generate-strong-secret-key>
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,www.yourdomain.com

DATABASE_URL=postgresql://user:pass@host:port/dbname

GOOGLE_API_KEY=<your-api-key>
EMAIL_HOST_USER=<your-email>
EMAIL_HOST_PASSWORD=<app-password>
DEFAULT_FROM_EMAIL=<from-email>
HR_EMAIL_RECIPIENT=<hr-email>

Example Deployment (Heroku)

# Install Heroku CLI and login
heroku login

# Create app
heroku create your-app-name

# Set environment variables
heroku config:set DJANGO_SECRET_KEY=your-secret
heroku config:set DEBUG=False
# ... set all other env vars

# Add PostgreSQL
heroku addons:create heroku-postgresql:hobby-dev

# Deploy
git push heroku main

# Run migrations
heroku run python manage.py migrate

# Create superuser
heroku run python manage.py createsuperuser

Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

This project is licensed under the MIT License.

Support

For issues, questions, or contributions:

Acknowledgments

  • Django framework and community
  • LangChain for RAG infrastructure
  • Google Gemini for AI capabilities
  • HuggingFace for embedding models
  • FAISS for vector search

Built with Django & AI | Made for efficient HR management

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages