👨‍💼 Workforce Hub | Enterprise Intelligent Workforce Management

A state-of-the-art, full-stack Human Resource Management System designed for modern, high-growth teams

Documentation • Report Bug • Request Feature

📑 Table of Contents

• Overview
• Tech Stack
• Core Features
• Prerequisites
• Quick Start
• Getting Started
• Production Deployment
• Limitations & Assumptions
• Contributing
• License

📚 Modular Documentation

• Backend: backend/README.md
• Frontend: frontend/README.md

🎯 Overview

Workforce Hub combines a premium React-based user interface with a FastAPI backend and intelligent data querying powered by OpenRouter AI. It's built for modern HR teams who need powerful insights without the complexity of traditional enterprise solutions.

Key Highlights

• 🤖 AI-Powered Insights - Natural language queries for workforce analytics
• ⚡ Lightning Fast - Built with modern tech stack for optimal performance
• 🎨 Beautiful UI - Executive-grade design with smooth animations
• 🔒 Production Ready - Deployed on Railway (backend) and Vercel (frontend)
• 📊 Data-Driven - Real-time analytics and actionable insights

Stats & Metrics

⚡ Quick Start

Get up and running in 5 minutes:

# Clone the repository
git clone https://github.com/upstackpilot0710/workforce-hub.git
cd workforce-hub

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env  # Configure your environment variables
uvicorn app.main:app --reload

# Frontend setup (in a new terminal)
cd frontend
npm install
cp .env.example .env  # Configure your environment variables
npm run dev

Visit http://localhost:5173 and you're ready to go! 🚀

🛠️ Tech Stack

Frontend

• ⚛️ React 18 + TypeScript - Modern UI framework with type safety
• ⚡ Vite - Lightning-fast build tool and dev server
• 🎨 Tailwind CSS - Utility-first styling with executive aesthetic
• 🎭 Framer Motion - Smooth animations and transitions

Backend

• 🚀 FastAPI (Python 3.12+) - High-performance async API framework
• 🔗 SQLAlchemy 2.0 - Powerful Python ORM
• 🤖 LangChain - AI orchestration framework
• 🧠 OpenRouter - Multi-model AI intelligence layer

Infrastructure

• 🗄️ PostgreSQL (via Supabase) - Robust relational database
• 🚂 Railway - Backend deployment platform
• ▲ Vercel - Frontend hosting with edge network

✨ Core Features

🤖 Intelligent HR Assistant

Production-ready conversational UI powered by OpenRouter AI that understands natural language queries about your workforce.

• 💬 Chat-based interface with persistent history
• 📊 Executive summaries and actionable insights
• 🔍 Natural language queries over employees, attendance, and metrics
• 📈 Leave trends analysis and headcount signals
• 🛡️ Network-hardened with timeout protection and error handling

👥 Employee Management

Complete CRUD operations for your workforce with intuitive filtering and search.

• ➕ Add, edit, and delete employee records
• 🏢 Department-based organization
• 🔄 Status management and filtering
• 📤 Bulk operations support
• 🔎 Advanced search and filtering

📊 Attendance Tracking

Streamlined attendance management with historical data and analytics.

• ✅ Quick daily attendance marking
• ✏️ Edit existing attendance entries
• 💾 Persistent database storage
• 📥 CSV export functionality
• 📈 Analytics dashboard with insights

🎨 Modern UI/UX

Beautiful, responsive interface built with modern design principles.

• 🪟 Glassy navbar with smooth transitions
• 📱 Fully responsive layout (mobile, tablet, desktop)
• ✨ Framer Motion animations
• 🌙 Clean, executive aesthetic
• ⚡ Fast and intuitive navigation

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.12 or higher - Download
• Node.js 18 or higher - Download
• PostgreSQL - Local installation or Supabase account
• Git - Download

💡 Quick Check: Run python --version, node --version, and git --version to verify installations

🚀 Getting Started

Step 1: Clone the Repository

git clone https://github.com/upstackpilot0710/workforce-hub.git
cd workforce-hub

Step 2: Backend Setup (FastAPI)

Navigate to Backend Directory

cd backend

Create Virtual Environment

python -m venv venv

Activate Virtual Environment

Windows (PowerShell)

venv\Scripts\Activate.ps1

macOS/Linux

source venv/bin/activate

Install Dependencies

pip install -r requirements.txt

Configure Environment Variables

Create a .env file in the backend directory:

DATABASE_URL=postgresql://USER:PASSWORD@HOST:PORT/DBNAME
OPENROUTER_API_KEY=YOUR_OPENROUTER_KEY
SECRET_KEY=CHANGE_ME_TO_A_LONG_RANDOM_STRING
OPENROUTER_MODEL=arcee-ai/trinity-large-preview:free
DEBUG=true
API_KEY=CHANGE_ME_MATCHES_FRONTEND

⚠️ Important: Never commit .env files to version control

Start the Backend Server

uvicorn app.main:app --reload

✅ Backend is now running at:

• API: http://localhost:8000
• Swagger Docs: http://localhost:8000/docs

Step 3: Frontend Setup (React + Vite)

Navigate to Frontend Directory

cd ../frontend

Install Dependencies

npm install

Configure Environment Variables

Create a .env file in the frontend directory:

VITE_API_URL=http://localhost:8000/api/v1
VITE_API_KEY=CHANGE_ME_MATCHES_BACKEND

📝 Note: The VITE_API_KEY must match the backend API_KEY

Start the Development Server

npm run dev

✅ Frontend is now running at: http://localhost:5173

🌐 Production Deployment

Backend Deployment on Railway

1. Push to GitHub

git push -u origin main

2. Create Railway Project

• Go to Railway and create a new project
• Connect your GitHub repository

3. Configure Service

• Root Directory: backend
• Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT

4. Set Environment Variables

DATABASE_URL=<your-supabase-connection-string>
OPENROUTER_API_KEY=<your-openrouter-key>
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
ALLOWED_ORIGINS=https://<your-vercel-app>.vercel.app
API_KEY=<must-match-frontend-key>

5. Deploy & Copy URL

Frontend Deployment on Vercel

1. Create Vercel Project

• Go to Vercel and import your repository

2. Configure Project

• Framework Preset: Vite
• Root Directory: frontend

3. Set Environment Variables

VITE_API_URL=https://<your-railway-backend>/api/v1
VITE_API_KEY=<must-match-backend-key>

🔑 Important: The VITE_API_KEY must match your backend API_KEY

4. Deploy

🔧 Environment Variables Reference

Backend (.env)

Variable	Description	Required	Example
DATABASE_URL	PostgreSQL connection string	✅ Yes	postgresql://user:pass@host:5432/db
OPENROUTER_API_KEY	OpenRouter API key for AI	✅ Yes	sk-or-v1-...
SECRET_KEY	Secret key for security	✅ Yes	your-secret-key-here
API_KEY	API key for frontend auth	✅ Yes	your-api-key
OPENROUTER_MODEL	AI model to use	❌ No	arcee-ai/trinity-large-preview:free
DEBUG	Enable debug mode	❌ No	true
DEMO_ISOLATION_ENABLED	Enable device isolation	❌ No	true
DEMO_ISOLATION_MODE	Isolation mode	❌ No	device or ip

Frontend (.env)

Variable	Description	Required	Example
VITE_API_URL	Backend API base URL	✅ Yes	http://localhost:8000/api/v1
VITE_API_KEY	API key (matches backend)	✅ Yes	your-api-key

🐛 Troubleshooting

Common Issues

Issue: Backend won't start

# Solution: Check if port 8000 is already in use
lsof -ti:8000 | xargs kill -9  # macOS/Linux
netstat -ano | findstr :8000    # Windows

Issue: Frontend can't connect to backend

• Verify VITE_API_URL in frontend .env matches your backend URL
• Check if backend is running: curl http://localhost:8000/health
• Ensure VITE_API_KEY matches backend API_KEY

Issue: Database connection error

• Verify DATABASE_URL format is correct
• Check Supabase instance is running
• Ensure IP is whitelisted in Supabase dashboard

Issue: AI queries not working

• Verify OPENROUTER_API_KEY is valid
• Check you have credits in OpenRouter account
• Ensure OPENROUTER_BASE_URL is set correctly

Issue: CORS errors

• Add your frontend URL to ALLOWED_ORIGINS in backend .env
• Clear browser cache and cookies
• Check browser console for specific CORS errors

⚠️ Current Limitations & Assumptions

Demo Mode Constraints

Authentication & Access

• ❌ No user authentication system - uses device isolation instead
• ❌ Data scoped per device/browser session via X-Device-Id header
• ❌ Not suitable for production multi-user environments

Architecture

• ❌ Single-tenant design - one organization only
• ❌ No multi-company data separation
• ❌ Basic role management - all users have full access
• ❌ Limited audit trail and compliance logging

Assumptions

This project is built with the following assumptions:

• 🎯 Demo environment with trusted users
• 👥 Small to medium team size (< 500 employees)
• 🌍 Single geographic region (no timezone complexity)
• 📋 Basic HR workflows without complex compliance requirements

Production Migration Path

For production deployment, you'll need to implement:

1. Authentication System - JWT/OAuth with secure session management
2. Multi-tenancy - Company-based data isolation with RLS
3. RBAC - Role-based permissions (Admin, Manager, Employee)
4. Audit Logging - Comprehensive compliance and change tracking
5. Advanced Features - Timezone support, complex workflows, reporting

❓ FAQ

Is this production-ready?

The application is production-ready in terms of architecture and code quality. However, it lacks authentication and is designed for demo/MVP use. For production, you'll need to implement proper authentication, RBAC, and multi-tenancy.

Can I use this for my company?

Yes! Workforce Hub is MIT licensed. You can use, modify, and deploy it for commercial purposes. Just remember to add authentication for production use.

How do I add new features?

The codebase is well-structured and easy to extend. Check out the Contributing section for guidelines. The backend uses FastAPI and the frontend uses React - both have extensive documentation.

What AI models are supported?

Workforce Hub uses OpenRouter, which supports multiple AI models. The default is arcee-ai/trinity-large-preview:free, but you can configure any OpenRouter-supported model via the OPENROUTER_MODEL environment variable.

How much does it cost to run?

- Frontend (Vercel): Free tier available - Backend (Railway): ~$5-20/month depending on usage - Database (Supabase): Free tier available (500MB) - AI (OpenRouter): Pay-per-use, ~$0.10-0.50 per day for normal usage

Can I self-host everything?

Absolutely! You can host the backend on any VPS, use a self-hosted PostgreSQL instance, and deploy the frontend on any static hosting service. The only external dependency is OpenRouter for AI features.

Does it support multiple companies/tenants?

Not yet. The current version is single-tenant. Multi-tenancy is in progress.

🧪 Testing & Quality

Frontend Build Check

cd frontend
npm run build

Backend Syntax Check

python -m compileall backend/app

🤝 Contributing

We love contributions! Whether it's bug fixes, feature additions, or documentation improvements - all PRs are welcome.

How to Contribute

1. Fork the repository
2. Create your 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

Development Guidelines

• Follow existing code style and conventions
• Write clear commit messages
• Add tests for new features
• Update documentation as needed

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

• FastAPI - Amazing Python web framework
• React - The library for web and native user interfaces
• OpenRouter - AI model routing and orchestration
• Supabase - Open source Firebase alternative
• Railway & Vercel - Deployment platforms
• Tailwind CSS - Utility-first CSS framework

📞 Support & Contact

Having trouble? We're here to help!

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Start a discussion
• 📧 Email: akashkumar.cs27@gmail.com
• 💬 Discussions: GitHub Discussions

If you find this project useful, please consider:

👨‍💻 Author

Built with ❤️ by Upstack Pilot

Making HR management intelligent and effortless for modern teams.

If you find Workforce Hub useful, please consider supporting it:

⭐ Star this repo • 🔀 Fork and contribute • 📢 Share with others

⬆ Back to Top

Made with ❤️ using React, FastAPI, and AI • © 2026 Upstack Pilot