Project Wiki

Operational and technical documentation for the Onboarding/Offboarding platform.

Overview Architecture Data Model Onboarding Flow Offboarding Flow Email Engine PDF Engine Integrations Admin Apps Operations Hardening Troubleshooting Security

1) Overview

This system handles employee onboarding and offboarding requests from web forms. It generates branded PDF documents, sends condition-based notifications, stores records in the database, and optionally uploads PDFs to Nextcloud.

Primary users: regular staff (submit forms) and admin users (configure and operate).
Main entry points: Home, Onboarding form, Offboarding form, Requests Dashboard, Admin Apps.
Asynchronous processing: heavy tasks (PDF/email/upload) are executed by Celery worker jobs.

2) Architecture

Runtime Components

Web: Django app served by Gunicorn
Worker: Celery worker for async processing
Broker: Redis (Celery queue)
DB: PostgreSQL
Email Sink (test): MailHog (when test mode is active)

Request Processing Pattern

User submits form in web UI.
Form data is validated and stored as request object.
Background task is queued with request ID.
Worker generates PDF, sends notifications, uploads to Nextcloud (if enabled), and updates record.

3) Data Model (Key Entities)

OnboardingRequest: onboarding data, generated PDF path, requester info, signature file/url, conditional fields.
OffboardingRequest: offboarding data, requester info, generated PDF path.
EmployeeProfile: searchable profile for offboarding prefill.
WorkflowConfig: routing emails, integration overrides, feature flags, welcome email delay.
NotificationTemplate: subject/body templates with placeholders.
NotificationRule: condition-based custom routing rules.
FormFieldConfig + FormOption: Form Builder configuration and selectable options.
ScheduledWelcomeEmail: delayed welcome email queue state.

4) Onboarding Flow

User opens /onboarding/new/ and completes multi-step form.
Form saves request; requester identity is taken from logged-in user.
Task process_onboarding_request runs in worker.
PDF is generated using HTML template + letterhead overlay.
Staff can additionally generate a separate Einweisungs- und Übergabeprotokoll from the Requests Dashboard for face-to-face employee introduction and sign-off.
Staff can also open a simple live Einweisung durchführen page with real web checkboxes, notes, and draft/completed tracking.
Default notification emails + optional rule-based emails are sent.
Welcome email job is scheduled (configurable delay).
PDF is uploaded to Nextcloud if enabled.

5) Offboarding Flow

User opens /offboarding/new/ and can search existing profile first.
Form saves request with requester name/email from logged-in user.
Task process_offboarding_request runs in worker.
PDF is generated. If a previous onboarding request exists, the hardware section can be derived from that onboarding data.
If no saved onboarding request exists for that person, the offboarding PDF automatically falls back to a manual onboarding reference sheet with grouped onboarding fields and printable checkbox lists.
Notification emails are sent (default + rules).
PDF upload to Nextcloud runs if enabled.

6) Email Engine

Modes

Production mode: real recipients are used.
Test mode: recipients are redirected to test mailbox; original recipients are included in body.

Template Placeholders

Examples: {{ VORNAME }}, {{ NACHNAME }}, {{ FULL_NAME }}, {{ EMAIL }}, {{ DEPARTMENT }}, {{ CONTRACT_START }}.

Condition-based Rules

Configured in Admin Integrations page.
Rule supports operators such as always, equals, contains, is_true, is_false.
Can use template-based emails or custom subject/body.

7) PDF Engine

Template source: /backend/media/templates/onboarding_template.html and offboarding_template.html.
Additional onboarding intro template: /backend/media/templates/onboarding_intro_template.html.
Letterhead: /backend/media/templates/templates.pdf.
Output folder: /backend/media/pdfs/.
Fixed PDF labels and notes are rendered through task-level DE/EN text maps and follow the request language with German fallback.
Signature images are embedded for compatibility with xhtml2pdf rendering.
Conditional sections are hidden if no data is provided.
Offboarding fallback behavior: if no onboarding record is available, the PDF renders a manual onboarding review layout grouped into Stammdaten, Vertrag, IT-Setup, and Abschluss, plus checkbox grids for devices, software, accesses, workspace groups, resources, and additional IT items.
The onboarding intro PDF is a separate checklist-style document for live walkthroughs. It uses printable blank checkboxes and signature lines for both the employee and the trainer.
The onboarding intro PDF can now use admin-configured checklist items from the dedicated Einweisungs-Builder. If no custom items are configured, the system falls back to built-in defaults.
The live introduction page uses the same checklist structure as the intro PDF, so admins maintain one checklist definition and can use it both on screen and on paper.
The live introduction page shows progress in percent and can generate a separate PDF export of the saved live checklist state.

8) Integrations

Nextcloud

Configured from Admin Integrations UI (base URL, user, password, target directory).
Can be globally enabled/disabled from Home Admin Apps.

Mail Server

SMTP host/port/account configured in Admin Integrations UI / backend config.
Use SMTP test action before switching to production mode.

8b) Bilingual Core UI

Current scope: the core user interface supports German and English switching for the main fixed UI pages.
Covered now: login, home, requests dashboard, onboarding form shell, offboarding form shell, common status/messages in views, and the main admin-tool labels/buttons for builders, integrations, welcome emails, and the handbook hub.
Phase 2 added: dynamic Form Builder option labels, field label/help-text overrides, and intro-builder checklist item labels now support German and English values.
Email phase added: admin-managed notification template subject/body content, notification rule custom subject/body content, and welcome email subject/body content now support explicit DE/EN values.
Runtime selection: onboarding and offboarding requests store the UI language at submission time, and notification delivery uses that language with German fallback.
Stability hardening: request models normalize preferred_language on save, and the database schema also enforces a default of de. This prevents null-language inserts outside the main form/view path.
PDF phase added: fixed PDF headings, labels, notes, and confirmation text now render in German or English based on the request language, with German as the fallback.
Editing path: these DE/EN values are maintained directly in the frontend builder pages, not only in Django admin.
Not fully bilingual yet: the main remaining gaps are long-form handbook/wiki copy and a few secondary admin/help texts.
Implementation: Django i18n with locale middleware, translation catalogs, and a DE/EN language switch in the main UI.

Translation Workflow

The long-term translation path uses Django's standard makemessages and compilemessages workflow.
gettext is installed in the Docker image so translations can be compiled inside the running container.
Translation catalogs live under /backend/locale/.
A root Makefile provides repeatable local commands for updating and compiling translations.
CI validates translation compilation on push and pull request via .github/workflows/i18n.yml.
The earlier ad hoc Python-based .mo compilation path should no longer be used for ongoing maintenance.

9) Admin Apps (Home)

Form Builder: manage field visibility/order/options.
Einweisungs-Builder: manage custom checklist items for the intro PDF and live introduction checklist, including section, visibility, and conditional display logic.
Integrations: Nextcloud, SMTP, default routing addresses, notification rules.
Welcome Emails: scheduled jobs, pause/resume/cancel/trigger now.
Requests Dashboard: search records, open PDFs, delete records (single/bulk for staff).
Einweisungs- und Übergabeprotokoll: staff-only PDF erzeugen, Neu erzeugen, and PDF öffnen actions directly on onboarding rows in the Requests Dashboard.
Einweisung durchführen: staff-only live checklist page opened from onboarding rows, with draft/completed status, notes, progress tracking, and a separate live-status PDF export.
Project Wiki: this documentation page.

10) Operations Runbook

Health Checks

App endpoint: /healthz/
If db=error, verify DB container and connection settings.

Where to Find Generated PDFs

Container path: /app/media/pdfs/
Host path: project backend/media/pdfs/ via mounted volume.

Deployment Notes

Use Docker Compose for web + worker + db + redis services.
After template/form/task changes, restart web and worker containers.
Run python manage.py check before release.
On a fresh database, the web container boot sequence now runs python manage.py bootstrap_initial_users right after migrations.
After adding or editing intro checklist items, regenerate the intro PDF from the Requests Dashboard to reflect the updated checklist.

Initial Bootstrap Users

Admin test user: admin_test / admin12345
Normal test user: user_test / user12345
The bootstrap step only creates these accounts when the user table is empty, so later restarts do not overwrite real users.

11) Security & Reliability Hardening (Current)

Cookie + header hardening: HTTPOnly cookies, SameSite cookies, X-Content-Type-Options: nosniff, stricter referrer policy, and frame protection.
Optional secure-cookie mode: can be enabled via environment for HTTPS deployments.
Upload guards: server-side upload size limits plus signature image magic-byte validation for PNG/JPEG.
SMTP reliability: explicit SMTP timeout to avoid hanging worker/web on mail network issues.
Nextcloud reliability: retry/backoff on upload errors, bounded timeouts, and graceful failure return instead of crashing flow.
Filename safety: PDF filenames are sanitized to safe filesystem characters.
Least privilege runtime: web and worker containers run as non-root app user.

Recommended for production: set secure cookies, explicit allowed hosts, CSRF trusted origins, and a strong secret key via environment variables.

12) Troubleshooting

Browser timeout or page hangs

Try http://127.0.0.1:8088/ instead of localhost if local DNS/proxy is unstable.
Check /healthz/ and web logs.

Onboarding submit does nothing

Check required/hidden conditional fields and form errors.
Open browser dev tools for JS errors.

PDF not generated

Check Celery worker logs for PDF task errors.
Verify template files exist and media folder permissions are correct.

Email not received

Verify email mode (test vs production).
Run SMTP test from Admin Apps.
Check SMTP settings and worker logs.

Login fails after fresh stack start

The system should bootstrap the initial users automatically after migrations on an empty database.
If login still fails, inspect web logs for bootstrap_initial_users and confirm the database volume was initialized correctly.

Nextcloud upload missing

Verify Nextcloud is enabled.
Test upload from Admin Apps.
Check credentials and destination directory path.

13) Security and Access Notes

Do not expose secrets in UI screenshots or logs.
Only staff users should access Admin Apps and this wiki page.
Use environment variables and admin overrides carefully in production.
Prefer production SMTP only after successful test-mode verification.

Last updated for current system behavior as of March 19, 2026.