Overview
Megadex is the user management service for a microservices architecture. It owns everything that describes who a user is, so that authentication and business services can refer to users by a numeric userId:
- 👤 User profiles — Identity, contact details, language, portrait, GDPR/marketing consent timestamps, and the role IDs assigned to each user (
roles) - 🔗 Social network links — User handles stored in
user_socialand exposed directly on user payloads associalsJsonAgg - 🌐 Social networks catalog — Supported social platforms (
social) managed as data without schema migrations - 🗂️ Table view preferences — Per-user saved grid configurations (
preferences) merged with locked system templates - 🌍 Reference lookups — Localized read-only catalogs for
countries,civilities, andgendersin English and French - 📜 History & audit logs — Trigger-backed change history (
log.history) and structured field-level diffs (log.audit) - 🎛️ Front-end admin — Manage users, social network catalogs, and audit logs through an Angular web interface
- 🛡️ BFF ACL enforcement — Enforce field allow-lists (
x-acl-fields), row conditions (x-acl-conditions), and consumer attribution forwarded by the BFF
Key Concepts
The users writable view
User data is normalized across three PostgreSQL tables — "user", user_role, and user_social — and exposed through a single writable users view backed by an INSTEAD OF INSERT OR UPDATE trigger (iud_user):
roles— integer array of assigned role IDs (mapped to"rolesArrayAgg"in SQL)socialsJsonAgg— JSON object of{ "<NetworkName>": "<handle>" }pairs validated against the activesocialcatalog
Because a single row carries the profile, role IDs, and social handles together, the BFF only needs one call to /megadex/users/search at sign-in to resolve an email address and load the user's roles. And administrative or self-service updates can modify profile fields, roles, and social links in a single POST or PUT. See Users.
Lifecycle synchronization
When a user is created or archived, Megadex can synchronize the corresponding password record with the password service when PWD_CREATE_URL is configured:
- User creation (
POST /megadex/users) — CallsPWD_CREATE_URLto provision a password record in the password service. If provisioning fails, the newly inserted user is automatically soft-archived so an unprovisioned account is never left active. - User archival (
POST /megadex/users/archive) — Archives the user's active password record.
Megadex does not revoke BFF sessions after role changes, deactivation, or archival. Existing sessions remain usable until their access tokens expire.
Super-admin role ceiling
Role 1 is reserved for the Super admin role. Megadex enforces a strict privilege ceiling (assertSuperAdminCeiling) on user creation, update, and archival:
- Only a caller who currently holds role
1may assign role1to a user. - Only a caller who currently holds role
1may modify or archive an existing user who holds role1.
Social networks catalog
Supported social networks live in the social table rather than in application code or enum types. Adding a new platform via POST /megadex/socials immediately makes it available on user profiles and in the Admin UI user form. Archiving a platform prevents new handles from being assigned to it while preserving historical records. See Social Networks.
Table view preferences
Administrators can customize column order, column widths, active filters, and sort order on the Admin UI tables. Preferences are stored in preference and preference_selection behind the writable preferences view:
- Rows with
userId IS NULLare locked system templates (Default,Compact,ArchivesandAuditforusers;Default,CompactandArchivesforsocials). - Editing a locked template automatically forks a personal preference row for the caller (copy-on-write), up to 10 personal views per user and per table. See Preferences.
Reference lookups
Countries (with nationalities), civilities, and genders are stored as ISO/standard codes with localized labels in country_trans, civility_trans, and gender_trans (seeded in English and French). Frontends query them through /megadex/countries/search, /megadex/civilities/search, and /megadex/genders/search filtered by lang. See Reference Lookups.