Developer Guide — overview
This guide is the engineering view of ManpowerIQ: how the system is built and why. It is written for developers joining the codebase, reviewers, and anyone who needs to trust the documentation enough to change the code behind it.
It is the dev-guide companion to the User Guide: where the User Guide explains what the product does, this explains how it is implemented — the architecture, the access model, and the conventions for adding the next feature.
The one rule this guide follows
Every architectural claim here is verified against the code, not the pitch. ManpowerIQ's design documents and handover material describe an aspirational stack — MediatR/CQRS, scheduled background jobs, OpenTelemetry, SSO, refresh tokens. Several of those are not wired. This guide states the build status of each component honestly:
- Available — shipped and enforced in the product.
- Partial — shipped at reduced scope; the page says exactly where the edge is.
- Planned — designed or scaffolded, but not built. Documented as absent, never as architecture-in-use.
Where a page makes a non-obvious claim, it traces to the Phase-0 fact base (the verified file.cs:line source for each subsystem). The fact sheets are the source of truth; where the older design docs and the code disagree, the code wins.
What's actually in the stack
A quick honest orientation before the detail pages — verdicts verified 2026-06-10 against the EF model snapshot and source:
| Component | Status | One-line |
|---|---|---|
| Clean Architecture (Domain / Application / Infrastructure / API) | Available | Layered, service-based — not CQRS/MediatR |
| EF Core 8 + Npgsql / PostgreSQL | Available | Snake-case, migrations are the schema source of truth |
| Multi-tenancy (query filters + write stamping + Postgres RLS) | Available | Three independent isolation layers |
| RBAC (permission-centric) | Available | 97 permissions × 9 roles, runtime-enforced |
| JWT auth (username/password + dev fallback + lockout) | Available | 8-hour access token only |
| JWT refresh tokens | Planned | Not implemented — re-login on expiry |
| SSO / Active Directory | Planned | Not built |
| Serilog structured logging | Available | Wired in Program.cs |
| OpenTelemetry / distributed tracing | Planned | Not present |
| i18n (BE resx + FE i18next + RTL + bilingual columns) | Available | English/Arabic end-to-end |
| Background jobs (Hangfire) | Partial | Fire-and-forget import job only; no scheduled/recurring jobs |
| Mobile app | Planned | Expo skeleton (health screen); the real product is the responsive web app |
How this guide is organised
Architecture — the structural pages:
- Architecture overview — the stack and how the layers fit together.
- Solution layout — the projects and their dependency direction.
- Clean Architecture — the layering rule (and why there is no MediatR).
- Multi-tenancy — the three isolation layers.
- Authentication & RBAC — login, tokens, and permission enforcement.
- Audit & soft-delete — the auditing model and the soft-delete pattern.
- Internationalisation — English/Arabic across backend and frontend.
- Background jobs — what Hangfire actually runs (and what it doesn't).
- RBAC matrix — the canonical 9-role × 97-permission reference.
Conventions — the "how to build the next thing" patterns — follow after the architecture pages.
Related
- User Guide — overview
- Roles & permissions — the user-facing view of RBAC.