R

Relokate HR

System Architecture v3.0

Domain
Immigration & Relocation
Market
Germany / EU
Last Updated
March 2026
Immigration Workflow Management Platform
Relokate HR
Immigration & relocation management for companies bringing employees to Germany
NestJS 8 Next.js 12 MongoDB Auth0 Stripe AWS S3
25 API Modules 14 Database Models 3 Visa Workflow Types 4-Role RBAC
Streamlined visa processing with credit-based billing and multi-role access control
1Problem
Companies relocating employees to Germany face complex visa workflows, document management, and compliance tracking across HR teams, employees, and immigration consultants
2Solution
Built workflow management platform with 3 relocation service types (Non-EU 19 steps, EU 11 steps, Other 10 steps), dual-database strategy (MongoDB for cases, MySQL for templates), Auth0 SSO, Stripe credit system (ReloCoins), and 4-role RBAC
3Outcome
25 API modules, automated workflow tracking, credit-based billing reducing payment friction
Key Engineering Decisions
Dual ORM strategy: Typegoose (MongoDB) for dynamic case data + TypeORM (MySQL) for structured templates
Schema flexibility vs. structure
Auth0 JWT for enterprise SSO integration
Enterprise auth delegation
Credit-based billing (ReloCoins via Stripe) instead of per-transaction payments
Reduced payment friction
Multi-tenant company scoping for data isolation
Enterprise data security
3 distinct visa workflow types with step-by-step progression tracking
Domain-driven workflow engine
Soft-delete audit trail for compliance documentation
Regulatory compliance
Event-driven notifications for workflow state transitions
Workflow automation
25
Modules
14
Models
3
Workflow
Types
46
Pages
92
Components
44
Shared
Components
My Role
System architecture
Dual-database strategy
Auth0 integration
Workflow engine design
3
Applications
25
API Modules
14
Data Models
150
Components
8
Integrations
Live
Production
01
Client Applications
HR Dashboard
Next.js 12 / React 17 / Port 3001
+
46 Pages 92 Components Tailwind Auth0
Key Screens (v1 + v2 + v3)
  • Dashboard with analytics, charts, expiring permits widget
  • Ongoing & Closed Cases with filters, search, pagination
  • Case Detail with flow steps, documents, tasks, family info
  • Add Candidate wizard (6-step stepper with family linking)
  • Team Management, Department CRUD, Company Settings
  • Billing with Stripe checkout, credit top-up, order history
  • Reports with date range filters, CSV export
Libraries
Auth0 SDK
Stripe.js
React Query
Chart.js
Formik + Yup
DaisyUI
React Dropzone
React Table
Admin Panel
Next.js 12 / React 17 / Port 3002
+
19 Pages 14 Components Tailwind DaisyUI
Admin Features
  • Global dashboard with analytics across all companies
  • Case management (ongoing, closed, case detail)
  • Company management with drill-down profiles
  • Expiring permits tracker with proactive alerts
  • Deletion approval workflow (users, employees, companies)
  • Team management across organizations
  • Reports with cross-company filtering
Access Control
SUPER_ADMIN
ADMIN
Shared FE Components
React / TypeScript / Tailwind
+
44 Components Cross-App Design System
Component Categories
  • Add Candidate wizard (6-step stepper, shared across apps)
  • UI Kit: Button, Box, Input, FloatInput, FloatSelect, Label
  • Modals: ConfirmModal, DeleteModal, ModalContainer, ModalHeader
  • Form controls: Checkbox, Radio, Switch, TextArea, Select
  • File handling: Dropzone with drag-and-drop upload
  • Context: CaseContext for shared case state management
  • Utilities: Spinner, ThemedSuspense, FastTrackStatus
HTTPS / REST / JWT
Auth0 Bearer Tokens
02
API & Business Logic
NestJS 8
Relokate Backend API
25 modules / 23 controllers / 28 services / 45 DTOs / Port 3000
+
Core
EmployeeModule
Case/employee CRUD, search, filter, status transitions, case numbering
Core
CompanyModule
Company profiles, credits (ReloCoins), contact info, compliance data
Core
CaseModule
Case workflow orchestration, status lifecycle management
Core
UserModule
User CRUD, role management (SUPER_ADMIN, ADMIN, HR_OWNER, HR_MEMBER)
Core
DepartmentModule
Department management scoped by company
Docs
EmployeeDocumentModule
Document upload/retrieval, type classification, employee/family assignment
Docs
EmployeeTaskModule
Task tracking per case (Open, In Approval, Completed)
Docs
EmployeeRelokateRequest
Relocation flow step tracking (23 workflow steps)
Docs
FileModule
S3 file upload/download with pre-signed URLs
Docs
TemplateModule
Document template management (TypeORM/MySQL)
Intel
AnalyticsModule
Dashboard stats, case trends, company reports, permit alerts
Intel
ReportsModule
Filtered reports: cases, companies, services, monthly summaries
Intel
CounterModule
Auto-increment case number generation (RLK-YYYY-NNNN format)
Billing
StripeModule
Payment processing, webhook handling, checkout sessions
Billing
OrdreModule
Order/invoice management, PDF generation, payment tracking
Auth
AuthModule
JWT strategy with Auth0 JWKS validation, Passport integration
Auth
OauthModule
Auth0 Management API: user creation, password resets, role sync
Comms
MailService
Mailjet transactional emails, permit expiry notifications
Comms
InvoiceService
PDF invoice generation with Handlebars templates (bank + card)
Comms
NewsletterModule
Newsletter subscriptions, referral tracking, launch notifications
Ops
DeletionModule
Soft-delete workflow: request, approve, audit trail across entities
Ops
CronjobsModule
Scheduled tasks: permit expiry alerts (hourly cron)
Ops
TeamModule
Team member management, company-scoped user listing
Ops
HealthController
Terminus health checks, readiness/liveness probes
Ops
SharedModule
Base model, Auth0 service, mail service, common utilities
JWT Auth Guard
Roles Guard
Company Scope Guard
Validation Pipe
Sentry Interceptor
HTTP Exception Filter
CORS Whitelist
Swagger / OpenAPI
SCHEDULED JOBS
@Cron('0 */1 * * *') permit_expiry_check
EventEmitter: admin.send.residence_permit_expiry
Stripe Webhook: payment.completed
Auth0 Callback: user.created
Typegoose ODM / Mongoose
TypeORM (Templates)
03
Data Layer & Models
Employee (Case)
Primary entity / Typegoose
+
35+ Fields Central Entity Soft Delete
Key Fields
caseNumber (RLK-YYYY-NNNN)
clientCaseNumber
service (4 types)
caseStatus (4 states)
residencePermitValidUntil
currentStep
relocationServiceType
paymentStatus / paymentMode
familyMember (self-ref)
isFastTrack / isFamilyReunification
Relations
  • company -> Company (ref)
  • documents -> EmployeeDocument[] (ref array)
  • createdBy -> User (ref)
  • familyMember -> Employee (self-ref)
Company
coinsNumber, VAT, registration
+
Credits System Compliance
Fields
  • name, shortName, companyId, vatId
  • address: city, street, postCode, houseNumber
  • contactPerson (firstName, lastName, email, phone)
  • coinsNumber (credit balance)
  • compliance: insolvency, social security, criminal checks
  • foundationDate, employeesNumber, registerNo, localCourt
User
Auth0 ID, role-based access
+
4 Roles Multi-Company
Roles
SUPER_ADMIN
ADMIN
HR_OWNER
HR_MEMBER
Fields
  • auth0Id, email (unique), firstName, lastName
  • company[] (Ref array - multi-company support)
  • department, function, phoneNumber
  • Deletion workflow: deletionStatus, requestedBy/At, approvedBy/At
Supporting Models
11 additional entities
+
Typegoose TypeORM
MongoDB (Typegoose)
  • EmployeeDocument: name, type, url, assignedTo (EMPLOYEE/FAMILY)
  • EmployeeTask: description, status (Open/In Approval/Completed)
  • EmployeeRelokateRequest: flow step tracking (23 steps)
  • Department: name, company (ref)
  • Ordre: invoices, ordreNumber, amount, paymentStatus, PDF
  • Newsletter: referral tracking, launch notifications
MySQL (TypeORM)
  • Template: id, file, name (document templates)
  • Document: id, file, name, type, userid
  • FAQ: id, title, description
Relocation Workflows
19 / 11 / 10 Steps
04
Domain Workflows & Business Logic
Non-EU Relocation
Full Services / 19 steps
+
19 Steps Visa Required Fast-Track
Workflow Steps
  • Payment received -> Welcome email -> Documents received
  • Welcome call -> Preparing application documents
  • Fast-track procedure -> Degree recognition (optional)
  • Fast-track invoice (to be paid -> paid)
  • Visa appointment -> Visa received
  • Preparing arrival -> Arrival to Germany
  • City registration (Anmeldung)
  • Residence permit: request -> appointment -> received -> valid
  • Work authorization received
EU Relocation
Streamlined / 11 steps
+
11 Steps No Visa Faster
Workflow Steps
  • Payment received -> Welcome email -> Documents received
  • Welcome call -> Accommodation found
  • Preparing arrival -> Arrival to Germany
  • Onboarding call -> Bank account opened
  • Health insurance set-up -> City registration
Other Services
Change employer / Purpose / Extension
+
10 Steps Permit Focus
Service Types
  • Change of employer
  • Change of purpose of stay
  • Extension of residence permit
Workflow
  • Payment -> Welcome -> Documents -> Welcome call
  • Preparing documents -> Permit appointment requested
  • Permit appointment -> Work auth -> Permit received -> Valid
Architectural Patterns
Security & Data
05
Architectural Patterns
Controller -> Service -> Model
Strict NestJS layering: controllers handle HTTP, services contain logic, Typegoose models handle persistence
Multi-Tenant Scoping
CompanyScopeGuard ensures all queries are scoped to the authenticated user's company associations
Role-Based Access Control
@Roles() decorator with RolesGuard: SUPER_ADMIN, ADMIN for analytics; HR_OWNER, HR_MEMBER for cases
Soft Delete Workflow
4-state deletion: ACTIVE -> PENDING_DELETION -> APPROVED -> DELETED with audit trail (who/when)
Event-Driven Notifications
NestJS EventEmitter2 for decoupled email triggers (permit expiry alerts, welcome emails)
DTO Validation
class-validator + class-transformer with global ValidationPipe; 45 DTOs across all modules
Dual ORM Strategy
Typegoose/Mongoose for primary domain (MongoDB); TypeORM for templates and FAQs (MySQL)
Shared Component Library
44 reusable React components shared between Dashboard and Admin via local package reference
External Services
Cloud Infrastructure
06
External Services & Integrations
🔐
Auth0
Identity provider, SSO, JWKS validation, user management API
💳
Stripe
Payment processing, checkout sessions, webhooks, invoicing
☁
AWS S3
Document storage, pre-signed URLs, file uploads (eu-central-1)
✉
Mailjet
Transactional emails, permit expiry alerts, welcome emails
🛡
Sentry
Error tracking, performance monitoring across all 3 apps
07
Infrastructure & Deployment
🐳
Docker Compose
4 services, multi-stage builds, health checks
🍃
MongoDB 6
Primary datastore, SSL certs, 512MB limit
🌐
nginx-proxy
Reverse proxy, Let's Encrypt SSL, auto-cert
📦
Node 18/20
Alpine images, dumb-init, yarn package manager
🚀
DigitalOcean
quantalynk.com subdomains, clean-build deploys
LIVE ENDPOINTS
api.relokatehr.quantalynk.com:3000
dashboard.relokatehr.quantalynk.com:3001
admin.relokatehr.quantalynk.com:3002
Explore Other Systems
→
Platypus
Real-Time Dog Walking Marketplace
→
Q-Invoice
Multi-Tenant Financial Billing Platform
→
Satshrut
Distributed Content & Live Streaming Platform
→
Q-Studio
Coworking Space SaaS Platform
→
Numerology CMS
AI-Enhanced Knowledge Platform
← Back to Portfolio