# Horilla HR Dev Documentation

This document explains how this local Horilla HR development environment works, where the important files are, and what to do for common development tasks.

Project path:

```text
F:\data\Abk's workspace\rb development\rb-hr\Dev\horilla-hr-1.0\horilla-hr-1.0
```

Current local setup:

- Framework: Django 4.2.24
- Runtime: Python 3.12 inside `horillavenv`
- Database: SQLite, file `db.sqlite3`
- Environment file: `.env`
- Local server URL: `http://127.0.0.1:8000/`
- Admin test login: `admin` / `admin123`

## 1. How To Start The App

Open PowerShell and run:

```powershell
cd "F:\data\Abk's workspace\rb development\rb-hr\Dev\horilla-hr-1.0\horilla-hr-1.0"
.\horillavenv\Scripts\activate
python manage.py runserver 127.0.0.1:8000
```

Then open:

```text
http://127.0.0.1:8000/
```

If the browser goes to `/login/?next=/`, that is normal. It means Django is running and Horilla is asking you to sign in.

## 2. Important Commands

Run all commands from the project folder after activating the venv.

```powershell
.\horillavenv\Scripts\activate
```

Check the app:

```powershell
python manage.py check
```

Create migrations after model changes:

```powershell
python manage.py makemigrations
```

Apply migrations to the database:

```powershell
python manage.py migrate
```

Start server:

```powershell
python manage.py runserver 127.0.0.1:8000
```

Create a superuser manually:

```powershell
python manage.py createsuperuser
```

Reset local admin password:

```powershell
python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='admin'); u.set_password('admin123'); u.save()"
```

## 3. Environment File

Horilla reads settings from `.env`. The code that loads it is in `horilla/settings.py`:

```python
env.read_env(os.path.join(BASE_DIR, ".env"), overwrite=True)
```

Current dev database settings:

```text
DATABASE_URL=sqlite:///db.sqlite3
DB_ENGINE=django.db.backends.sqlite3
DB_NAME=db.sqlite3
TIME_ZONE=Asia/Karachi
DEBUG=True
```

`DEBUG=True` is for local development only. Production should use `DEBUG=False`, a real `SECRET_KEY`, restricted `ALLOWED_HOSTS`, and PostgreSQL.

## 4. Database

This local setup uses SQLite:

```text
db.sqlite3
```

SQLite is simple and good for testing screens and flows. For production, Horilla expects PostgreSQL.

Database flow:

1. Django reads `.env`.
2. `horilla/settings.py` creates the `DATABASES` config.
3. `python manage.py migrate` creates tables in `db.sqlite3`.
4. Login, employees, leave, payroll, attendance, and demo data all read/write to that database.

To reset local dev database completely:

1. Stop the server.
2. Delete `db.sqlite3`.
3. Run `python manage.py migrate`.
4. Use Horilla's Initialize Database or Load Demo Data button again.

Do this only for development, because it removes local data.

## 5. Demo Data

Demo JSON files are in:

```text
load_data/
```

Important files:

- `user_data.json`: demo Django users
- `employee_info_data.json`: employee records
- `work_info_data.json`: employee job/work information
- `base_data.json`: companies, departments, shifts, job positions, roles, work types
- `attendance_data.json`: attendance records
- `leave_data.json`: leave types, leave requests, available leave
- `payroll_data.json`: payroll settings, contracts, allowances, deductions, payslips
- `recruitment_data.json`: candidates, recruitment, stages
- `onboarding_data.json`: onboarding flow demo records
- `offboarding_data.json`: offboarding flow demo records
- `asset_data.json`: assets and assignments
- `pms_data.json`: performance management data
- `project_data.json`: projects/tasks/timesheets
- `mail_templates.json`: demo mail templates
- `mail_automations.json`: automation rules

The login page buttons use the database initialization password from `.env`:

```text
DB_INIT_PASSWORD=...
```

Use Initialize Database for an empty starter setup. Use Load Demo Data when you want sample HR data for testing.

## 6. Authentication And Login

Login URL:

```text
/login/
```

Current local test credential:

```text
Username: admin
Password: admin123
```

Django stores users in the `auth_user` table. Horilla links Django users to employee profiles through the `employee` app.

In demo data, many employees use email addresses as usernames, for example:

```text
michael.brown@horilla.com
sarah.anderson@horilla.com
emily.clark@horilla.com
```

Their passwords are stored as Django password hashes, not plain text. For local testing, resetting or creating known users is easiest.

## 7. How A Request Works

Example: opening `http://127.0.0.1:8000/employee/`

1. Browser sends request to Django dev server.
2. Django loads URL config from `horilla/urls.py`.
3. `horilla/urls.py` includes app URLs, such as `employee.urls`.
4. The matching URL points to a view function or class.
5. The view reads/writes models, checks permissions, and prepares context.
6. The view renders an HTML template from `templates/` or app template folders.
7. Browser receives HTML, CSS, JS, and static assets.

Core routing file:

```text
horilla/urls.py
```

Important included routes:

- `/` -> `base.urls`
- `/employee/` -> `employee.urls`
- `/api/` -> `horilla_api.urls`
- `/admin/` -> Django admin
- `/health/` -> returns JSON `{"status": "ok"}`
- `/inbox/notifications/` -> notification system

## 8. Main Project Files

`manage.py`

Django command entry point. All commands like `runserver`, `migrate`, and `createsuperuser` go through this file.

`horilla/settings.py`

Main Django configuration: installed apps, database, static/media files, middleware, language/timezone, security settings.

`horilla/urls.py`

Main URL router. It connects top-level URL paths to module URL files.

`.env`

Local environment settings. Do not use the local dev `.env` values in production.

`requirements.txt`

Python dependencies.

`package.json`

JavaScript/frontend dependencies. It contains Laravel Mix scripts and packages like jQuery, Select2, Ionicons, Alpine.js.

`templates/`

Shared HTML templates.

`static/`

CSS, JavaScript, images, and frontend assets used by templates.

`media/`

Uploaded files and user-generated media.

`load_data/`

Demo seed data used by Horilla's database/demo initialization flow.

## 9. Main Django Apps

Horilla is split into Django apps. Each app usually has:

- `models.py`: database tables
- `views.py`: request handling
- `urls.py`: routes
- `forms.py`: form validation and rendering helpers
- `admin.py`: Django admin registration
- `migrations/`: database schema migrations

### base

Core HR foundation. It contains companies, departments, job positions, job roles, shifts, work types, holidays, announcements, email configuration, and general settings.

### employee

Employee profiles and employee-related data. It connects employee records to Django users, handles personal/work info, bank details, notes, policies, disciplinary actions, and employee settings.

### attendance

Attendance records, attendance requests, overtime, validation rules, grace time, batch attendance, and work records.

### leave

Leave types, leave requests, available leave, allocations, holidays, compensatory leave, restrictions, and approval-related objects.

### payroll

Payroll contracts, allowances, deductions, tax brackets, payslips, reimbursements, loans, payroll settings, and payroll history.

### recruitment

Recruitments, candidates, stages, skills, interview schedules, candidate ratings, surveys, rejected candidates, and candidate documents.

### onboarding

Onboarding stages, tasks, portals, candidate onboarding flow, and candidate task tracking.

### offboarding

Resignation letters, offboarding stages, offboarding tasks, employee task assignments, notes, exit reasons, and offboarding settings.

### asset

Asset categories, asset lots, assets, asset assignments, asset requests, asset reports, and uploaded asset documents/images.

### pms

Performance management. Objectives, key results, feedback, meetings, questions, periods, comments, and bonus point settings.

### project

Projects, project stages, tasks, and timesheets.

### helpdesk

Tickets, ticket types, FAQs, comments, attachments, claim requests, and department manager mappings.

### notifications

Notification storage and views. Integrated through `/inbox/notifications/`.

### horilla_api

REST API layer. Contains API URLs and views for modules like auth, employee, base, attendance, asset, leave, payroll, helpdesk, and notifications.

### horilla_automations

Automation rules and mail automation logic. Uses demo data from `mail_automations.json`.

### horilla_views

Generic view helpers and saved table/filter/view state.

### horilla_widgets

Reusable UI widgets.

### horilla_documents

Document request and document management models/views.

### horilla_backup

Backup-related models, forms, views, and scheduler logic.

### biometric

Biometric device and biometric employee data.

### geofencing

Geo-fencing configuration.

### facedetection

Face detection configuration and employee face detection data.

### accessibility

Accessibility/default accessibility settings.

### report

Report views and report models.

### outlook_auth

Microsoft/Outlook authentication integration.

### horilla_ldap

LDAP integration support.

### dynamic_fields

Dynamic custom fields support.

## 10. Models, Views, Forms, URLs

Django module pattern:

```text
app/models.py  -> database structure
app/forms.py   -> input validation and form widgets
app/views.py   -> page behavior and business flow
app/urls.py    -> URLs for the app
app/templates/ -> HTML for that app, if present
```

When you want to understand a feature:

1. Find its menu/page URL in the browser.
2. Search the URL path in that app's `urls.py`.
3. Open the matched view in `views.py`.
4. Check which model/form/template it uses.
5. Check `models.py` to understand the database fields.

Example search commands:

```powershell
rg "path\(" employee\urls.py
rg "def .*employee" employee\views.py
rg "class Employee" employee\models.py
```

## 11. Static Files And Frontend

Frontend assets are mostly traditional Django templates plus static files.

Key folders:

```text
templates/
static/
```

JavaScript dependencies include jQuery, Select2, Ionicons, Alpine.js, and js-datepicker.

`package.json` has:

```json
"dev": "npm run development",
"development": "mix"
```

For normal backend development, you usually do not need to run npm unless you are changing compiled frontend assets.

## 12. Background Jobs And Schedulers

Several apps include `scheduler.py`, for example:

- `attendance/scheduler.py`
- `leave/scheduler.py`
- `employee/scheduler.py`
- `payroll/scheduler.py`
- `recruitment/scheduler.py`
- `pms/scheduler.py`
- `base/scheduler.py`
- `horilla_backup/scheduler.py`

Horilla uses APScheduler / django-apscheduler for scheduled jobs. During initial setup, you may see warnings like `no such table` before migrations exist. After migrations are applied, `python manage.py check` should be clean.

## 13. API

API routes start at:

```text
/api/
```

Main API URL file:

```text
horilla_api/urls.py
```

Submodules:

```text
horilla_api/api_urls/auth/
horilla_api/api_urls/employee/
horilla_api/api_urls/base/
horilla_api/api_urls/attendance/
horilla_api/api_urls/asset/
horilla_api/api_urls/leave/
horilla_api/api_urls/payroll/
horilla_api/api_urls/helpdesk/
horilla_api/api_urls/notifications/
```

API views are under:

```text
horilla_api/api_views/
```

## 14. Django Admin

Admin URL:

```text
/admin/
```

Use:

```text
admin / admin123
```

The Django admin is useful for checking raw database records, users, permissions, and model data.

## 15. Development Workflow

For a normal feature change:

1. Start server.
2. Reproduce the behavior in browser.
3. Identify the app/module.
4. Check `urls.py` for the route.
5. Check the view in `views.py`.
6. Check forms and models.
7. Edit code.
8. Run `python manage.py check`.
9. If models changed, run `makemigrations` and `migrate`.
10. Test in browser.

For database/model changes:

```powershell
python manage.py makemigrations
python manage.py migrate
python manage.py check
```

For dependency changes:

```powershell
pip install package-name
pip freeze > requirements.txt
```

Be careful before overwriting `requirements.txt`; it can reorder or change many dependency versions.

## 16. Local Vs Production

Local dev:

- SQLite is okay.
- `DEBUG=True` is okay.
- `ALLOWED_HOSTS=*` is okay only for local testing.
- Simple passwords are okay only for local testing.

Production:

- Use PostgreSQL.
- Use `DEBUG=False`.
- Use a strong secret key.
- Restrict `ALLOWED_HOSTS`.
- Configure HTTPS/security settings.
- Configure media/static storage properly.
- Use a real process manager/web server, not `runserver`.
- Do not use demo data or dev passwords.

## 17. Troubleshooting

### Server opens login page

That is normal. It means the app is running.

### Wrong password

Reset admin password:

```powershell
python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='admin'); u.set_password('admin123'); u.save()"
```

### `no such table`

Run migrations:

```powershell
python manage.py migrate
```

If model migrations do not exist yet:

```powershell
python manage.py makemigrations
python manage.py migrate
```

### Port already in use

Run on another port:

```powershell
python manage.py runserver 127.0.0.1:8001
```

### Packages missing

Activate venv and install requirements:

```powershell
.\horillavenv\Scripts\activate
pip install -r requirements.txt
```

### Static files look broken

Check that `static/` exists and the app is running with `DEBUG=True`. For production, use `collectstatic` and a proper static file server.

## 18. What To Learn First

Recommended order:

1. Django basics: models, views, urls, templates, migrations.
2. `horilla/settings.py` and `.env`.
3. `base`, because many modules depend on company/department/job/shift data.
4. `employee`, because most modules link to employees.
5. `attendance`, `leave`, and `payroll`, because they are the core HR workflows.
6. `recruitment`, `onboarding`, and `offboarding`.
7. API and automations.

## 19. Current Known Dev Choices

This environment was intentionally configured as a quick local development setup:

- SQLite instead of PostgreSQL.
- Local admin password reset to `admin123`.
- Demo data can be used for testing.
- This is not production-ready configuration.

For a serious staging/prod setup, switch to PostgreSQL and harden `.env`.