Employee Self-Service Portal

A full-stack employee self-service portal with role-based access control, leave management, AI recommendations, and chatbot functionality. WorkHub is an open‑source Employee Self‑Service Portal built as a hackathon project to explore how modern web stacks and AI features can simplify everyday HR workflows.

The goal of this project is not perfection — it’s learning, collaboration, and experimentation. If you’re a developer who enjoys full‑stack systems, dashboards, or AI integrations, you’re very welcome here.

Features

• Role-based access control (Employee, Manager, HR Admin)
• Leave application and approval workflow
• Dashboard personalization
• AI-driven learning and compliance recommendations
• Echo chatbot assistant
• Responsive design for laptop and mobile browsers

Tech Stack

• Frontend: React, Material-UI, Vite
• Backend: Python FastAPI, SQLAlchemy, SQLite
• Authentication: JWT tokens
• Containerization: Docker, Docker Compose

Prerequisites

• Docker and Docker Compose installed
• Git (optional, for cloning) but useful.

Getting Started

Using Docker Compose (Recommended)

1. Clone or navigate to the project directory
2. Run the following command:

docker-compose up --build

This will:

• Build and start the backend service on port 8000
• Build and start the frontend service on port 3000
• Create the database and seed initial data

3. Access the application:
   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Setup Environment Variables

Before running the backend, create your .env file from the example:

# On Linux / Mac
cp backend/.env.example backend/.env

# On Windows PowerShell
Copy-Item backend\.env.example backend\.env

### Demo Credentials

The database is seeded with the following test users:

**Employee:**
- Email: `employee@company.com`
- Password: `password123`

**Manager:**
- Email: `manager@company.com`
- Password: `password123`

**HR Admin:**
- Email: `hr@company.com`
- Password: `password123`

Project Structure

WorkHub/
├── backend/
│   ├── app/
│   │   ├── routers/        # API route handlers
│   │   ├── models.py       # Database models
│   │   ├── schemas.py      # Pydantic schemas
│   │   ├── auth.py         # Authentication logic
│   │   └── main.py         # FastAPI app
│   ├── requirements.txt
│   ├── Dockerfile
│   └── seed_data.py        # Database seeding script
├── frontend/
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── context/        # React context
│   │   └── services/       # API client
│   ├── package.json
│   └── Dockerfile
└── docker-compose.yml

API Endpoints

Authentication

• POST /auth/login - User login
• POST /auth/register - User registration

Dashboard

• GET /dashboard - Get dashboard data
• POST /dashboard/config - Update dashboard preferences

Leave Management

• POST /leave/apply - Apply for leave
• GET /leave/my - Get user's leave requests
• GET /leave/pending - Get pending leaves (Manager)
• POST /leave/approve - Approve/reject leave (Manager)

Admin

• POST /admin/user - Create user (HR)
• DELETE /admin/user/{id} - Delete user (HR)
• POST /admin/compliance - Add compliance policy (HR)
• POST /admin/learning - Add learning content (HR)

AI & Chatbot

• GET /recommendations - Get AI recommendations
• POST /chatbot/echo - Chat with Echo bot

Development

Backend Development

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend Development

cd frontend
npm install
npm run dev

Seeding Database

cd backend
python seed_data.py

Role-Based Access

• Employee: Can view own profile, apply for leave, view dashboard
• Manager: Can view team members, approve/reject leaves in their department
• HR Admin: Can create/delete users, manage compliance policies and learning content

Notes

• All authentication is handled via JWT tokens
• Role and department checks are enforced server-side
• The database file is stored in a Docker volume for persistence
• The application is designed for demo purposes and uses SQLite for simplicity

Troubleshooting

• If ports 3000 or 8000 are already in use, modify the port mappings in docker-compose.yml
• To reset the database, remove the Docker volume: docker-compose down -v
• Check container logs: docker-compose logs backend or docker-compose logs frontend

Contributing

WorkHub is open to contributors of all levels. You can help by:

• Improving UI/UX
• Fixing bugs
• Adding new features
• Improving documentation
• Refactoring code Please read CONTRIBUTING.md before opening a pull request.

Contributors ✨

Thanks to these wonderful people who have contributed to this project:

Contributions of any kind are welcome!

License

This project is licensed under the MIT License.

Acknowledgements

Built during a hackathon with curiosity, caffeine, and a lot of Docker rebuilds.

• If this project helps you learn something,that’s a win already ⭐