HR Suit Local Development Runbook

Document status: Source-verified local-development baseline
System of record: SalaryManagement API 1 source repository
Canonical launcher: scripts/start-full-local.ps1
Last source review: 2026-08-03
Uncertainty marker: Requires Confirmation

This page is the single operational reference for running HR Suit locally. It distinguishes the canonical full-local topology from projects that merely exist in the solution. A service is not described as required unless a checked-in launcher, routing configuration, or direct code dependency establishes that requirement.

Overview

HR Suit is a transitional .NET architecture. A Vite/React client portal and a separate Super Admin portal call a public ASP.NET Core Gateway. The Gateway routes extracted capabilities to dedicated services and sends compatibility routes to the legacy SalarySystem application. PostgreSQL provides persistence. RabbitMQ provides integration-event transport. The canonical Windows launcher starts a selected subset of the microservice solution; additional service projects are available for focused development and regression work.

The safest default for cross-module work is the checked-in full-local launcher. For focused work, use the smallest profile in Run Profiles and leave unrelated services stopped.

Repository locations

Concern	Verified location
Backend repository root	D:\Project\Git\SalaryManagement API 1
Microservice solution	microservices/HrSuit.Microservices.sln
Legacy application	SalarySystem.csproj
Frontend workspace	UI/salary-ui
Canonical topology	scripts/full-local-stack.config.psd1
Canonical launcher	scripts/start-full-local.ps1
Status command	scripts/status-full-local.ps1
Full smoke command	scripts/smoke-full-local.ps1
Stop command	scripts/stop-full-local.ps1
Docker topology	microservices/docker-compose.yml

Architecture rules

1. Browser traffic should use Gateway port 5000 for the canonical topology.
2. Extracted services own their verified routes when the corresponding Gateway routing switch is enabled.
3. The monolith remains the compatibility fallback for /api routes not cut over.
4. Each persistent extracted service uses its own logical PostgreSQL database.
5. Gateway is started last because it validates and depends on downstream destinations.
6. Port 5040 is intentionally unused by the canonical scripts; Attendance uses 5041.

Infrastructure

PostgreSQL

Property	Verified value
Purpose	Persistence for the monolith and stateful extracted services
Canonical host/port	localhost:5432
Required for	All canonical backend services except Gateway; Reporting, HR Operations, and Tenant Provisioning persistence is Requires Confirmation
Startup order	First
Health check	psql -h localhost -p 5432 -U postgres -d postgres -tAc "SELECT 1"
Canonical local user	postgres
Password source	HR_SUIT_POSTGRES_PASSWORD; launcher fallback postgres

The canonical launcher creates missing logical databases but does not drop, recreate, or seed existing databases. Each service retains ownership of its EF Core migration and startup seeding behavior.

RabbitMQ

Property	Verified value
Purpose	Integration-event transport
AMQP port	5672
Management port	15672
Required for	Canonical full stack and services configured with RabbitMq
Startup order	After PostgreSQL, before applications
Health check	http://localhost:15672/api/health/checks/alarms with management credentials
Exchange	hr-suit.integration-events
Local credentials	HR_SUIT_RABBITMQ_USERNAME / HR_SUIT_RABBITMQ_PASSWORD; launcher fallback guest / guest
Container name	hr-suit-microservices-rabbitmq-1

The launcher reuses a reachable broker, starts a local RabbitMQ Windows service when one exists, or delegates to microservices/scripts/start-local-rabbitmq.ps1. The stop script preserves RabbitMQ unless -StopRabbitMq is supplied.

Docker Desktop

Docker Desktop is one supported way to host RabbitMQ and the complete Compose topology. It is required by UI/salary-ui/scripts/run-local-gateway.ps1 and by docker compose; it is not required when using the host-process full-local launcher with PostgreSQL and RabbitMQ already available.

Health check: docker info. Default port: not applicable.

Optional observability

Observability:SeqUrl, Observability:OtlpEndpoint, and Observability:EnableConsoleExporter exist in service configuration. No canonical local Seq, Elasticsearch, Redis, Azurite, or OpenTelemetry Collector process is started by the verified launchers. Their ports, startup order, and health checks are Requires Confirmation.

Frontend Applications

Client HRMS Portal

Property	Verified value
Application	Client HRMS Portal
Path	UI/salary-ui/apps/client-hrms-portal
Port / URL	5173 / http://localhost:5173/
Required backend	Gateway for canonical mode; direct monolith is a supported fallback
Install	npm install from UI/salary-ui
Build	npm run build:client
Run	npm run dev:client -- --host 0.0.0.0 --port 5173
Health verification	HTTP success from http://localhost:5173/
Build output	dist/

Environment variables: VITE_API_BASE_URL, VITE_USE_PLATFORM_SERVICE, VITE_PLATFORM_GATEWAY_BASE_URL, VITE_SUPER_ADMIN_PORTAL_URL, VITE_CLIENT_PORTAL_URL, VITE_WORKSPACE_BASE_DOMAIN, VITE_LEGAL_TERMS_URL, VITE_PRIVACY_POLICY_URL, and VITE_SIGNUP_SUPPORT_EMAIL.

Super Admin Portal

Property	Verified value
Application	Super Admin Portal
Path	UI/salary-ui/apps/super-admin-portal
Port / URL	5174 / http://localhost:5174/
Required backend	Gateway; Platform and Identity for platform administration
Install	npm install from UI/salary-ui
Build	npm run build:admin
Run	npm run dev:admin -- --host 0.0.0.0 --port 5174
Health verification	HTTP success from http://localhost:5174/
Build output	dist-super-admin/

Frontend modes

Mode	VITE_API_BASE_URL	Notes
Canonical Gateway	http://localhost:5000	Shared client normalizes local origin to /api where needed
Gateway with explicit suffix	http://localhost:5000/api	Also supported by the shared API client
Direct monolith fallback	http://localhost:5223/api	Does not exercise Gateway or extracted-service routing

Backend Services

Status meanings: Canonical means included by scripts/full-local-stack.config.psd1; Available means an executable project and launch profile exist but the canonical launcher does not start it; Library means it is not an independently runnable service.

Service	Port	Database	Dependencies	Gateway Route	Health Endpoint	Swagger	Canonical Owner	Status
Gateway API	5000	None	Canonical downstream APIs; RabbitMQ	/	http://localhost:5000/health; dev downstream check /health/downstreams	http://localhost:5000/swagger	Public API gateway	Canonical
Platform Service	5097	hrsuit_platform	PostgreSQL, RabbitMQ, Identity for provisioning paths	/platform, /api/public	http://localhost:5097/health	http://localhost:5097/swagger	Platform	Canonical
Identity Service	5010	hrsuit_identity	PostgreSQL, RabbitMQ; Platform capability client	/identity	http://localhost:5010/health	http://localhost:5010/swagger	Identity	Canonical
SalarySystem	5223	salarydb; also reads Identity connection in Compose	PostgreSQL, RabbitMQ	/api compatibility fallback	http://localhost:5223/health	http://localhost:5223/swagger/index.html	Legacy workforce and compatibility APIs	Canonical
Employee Service	5267	hrsuit_employee	PostgreSQL, RabbitMQ; downstream guards are configuration-dependent	/employee, employee-owned /api routes	http://localhost:5267/health	http://localhost:5267/swagger	Workforce / Employee	Canonical
Attendance Service	5041	hrsuit_attendance	PostgreSQL, RabbitMQ	/attendance-service, /api/time-office	http://localhost:5041/health	http://localhost:5041/swagger	Attendance	Canonical
Leave Service	5050	hrsuit_leave	PostgreSQL, RabbitMQ; Workflow when approval switch is enabled	/leave, /api/leave-config	http://localhost:5050/health	http://localhost:5050/swagger	Leave	Canonical
Payroll Service	5158	hrsuit_payroll	PostgreSQL, RabbitMQ; Attendance availability guard	/payroll, /api/payroll-config	http://localhost:5158/health	http://localhost:5158/swagger	Payroll	Canonical
Workflow Service	5251	hrsuit_workflow	PostgreSQL, RabbitMQ	/api/workflow-config	http://localhost:5251/health	http://localhost:5251/swagger	Workflow	Canonical
Document Service	5168	hrsuit_document	PostgreSQL, RabbitMQ; configured document storage	/documents-service, /api/document-config	http://localhost:5168/health	http://localhost:5168/swagger	Document	Canonical
Notification Service	5074	hrsuit_notification	PostgreSQL, RabbitMQ	/notifications, /api/notification-config	http://localhost:5074/health	http://localhost:5074/swagger	Notification / Communication	Canonical
Tenant Provisioning Service	5014	Requires Confirmation	Configuration-defined	Requires Confirmation	http://localhost:5014/health	http://localhost:5014/swagger	Tenant provisioning	Available
HR Operations Service	5028	Requires Confirmation	Configuration-defined	Requires Confirmation	http://localhost:5028/health	http://localhost:5028/swagger	HR operations	Available
Recruitment Service	5241	hrsuit_recruitment	PostgreSQL; Workflow when approval switch is enabled	Gateway configuration contains a recruitment destination and routing switch	http://localhost:5241/health	http://localhost:5241/swagger	Recruitment	Available
Expense Service	5288	hrsuit_expense	PostgreSQL; Workflow when approval switch is enabled	Gateway configuration contains an expense destination	http://localhost:5288/health	http://localhost:5288/swagger	Expense	Available
Asset Service	5292	hrsuit_asset	PostgreSQL; Workflow when approval switch is enabled	Gateway configuration contains an asset destination	http://localhost:5292/health	http://localhost:5292/swagger	Asset	Available
Performance Service	5296	hrsuit_performance	PostgreSQL; Workflow when approval switch is enabled	Gateway configuration contains a performance destination	http://localhost:5296/health	http://localhost:5296/swagger	Performance	Available
Training Service	5307 in launch profile; Gateway default destination is 5321	hrsuit_training	PostgreSQL	Gateway configuration contains a training destination	http://localhost:5307/health	http://localhost:5307/swagger	Training	Available; configuration conflict
Helpdesk Service	5311	hrsuit_helpdesk	PostgreSQL	Gateway configuration contains helpdesk destination and routing switch	http://localhost:5311/health	http://localhost:5311/swagger	Helpdesk	Available
Reporting Service	5116	Requires Confirmation	Configuration-defined	Requires Confirmation	http://localhost:5116/health	http://localhost:5116/swagger	Reporting	Available
Integration Service	5050	hrsuit_integration	PostgreSQL	Requires Confirmation	http://localhost:5050/health	http://localhost:5050/swagger	Integration	Available; conflicts with Leave
Contracts	None	None	None	None	None	None	Shared contracts	Library
Shared Kernel	None	None	None	None	None	None	Shared implementation	Library

Swagger is wired in each listed executable Program.cs; the exact UI suffix beyond /swagger is framework-default except where the monolith documentation explicitly specifies /swagger/index.html.

Startup Order

This is the exact order in the canonical configuration array, with Gateway deferred until all non-Gateway entries are healthy.

Canonical commands

cd "D:\Project\Git\SalaryManagement API 1"
.\scripts\start-full-local.ps1
.\scripts\status-full-local.ps1
.\scripts\smoke-full-local.ps1

Stop only processes recorded by the orchestrator:

.\scripts\stop-full-local.ps1
# Include broker only when intentionally stopping it:
.\scripts\stop-full-local.ps1 -StopRabbitMq

Logs are written under run-logs/full-local/services. A healthy process found before startup is reused and not registered for later termination.

Run Profiles

RAM and CPU measurements are not captured in source. Every estimate field therefore remains Requires Confirmation until a repeatable measurement is checked in.

Authentication Profile

Item	Value
Purpose	Login, token issuance, activation, session and authorization cutover
Services	Identity; Gateway; Platform when capability/provisioning behavior is exercised; SalarySystem for compatibility smoke
Databases	hrsuit_identity; hrsuit_platform when Platform is used; salarydb for compatibility
Infrastructure	PostgreSQL; RabbitMQ where integration behavior is exercised
Estimated RAM	Requires Confirmation
Typical scenarios	Login, account activation, identity bootstrap, monolith compatibility
Health endpoints	:5010/health, :5097/health, :5223/health, :5000/health
Smoke tests	smoke-identity.ps1, smoke-auth-cutover.ps1, smoke-identity-bootstrap.ps1, smoke-identity-monolith-compat.ps1

Core HR Profile

Purpose: employee and legacy workforce development. Services: Employee, SalarySystem, Identity, Gateway, and Client Portal. Database: hrsuit_employee, salarydb, hrsuit_identity. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Typical scenario: employee CRUD and compatibility routing. Health: ports 5267, 5223, 5010, 5000, and 5173. Smoke: microservices/scripts/smoke-employee.ps1 plus the employee route in scripts/smoke-full-local.ps1.

Payroll Profile

Purpose: payroll calculation/configuration and attendance-dependent validation. Services: Payroll, Attendance, Employee or SalarySystem as required by the scenario, Identity, Gateway, Client Portal. Databases: hrsuit_payroll, hrsuit_attendance, plus workforce and identity stores used by the scenario. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Health: ports 5158, 5041, 5267/5223, 5010, 5000, 5173. Smoke: smoke-payroll.ps1, smoke-payroll-cutover.ps1, and scripts/validate-payroll-scenarios.ps1.

Recruitment Profile

Purpose: extracted recruitment development and compatibility validation. Services: Recruitment, Gateway, Identity, Workflow when approvals are enabled, Client Portal; SalarySystem may still own compatibility UI APIs. Database: hrsuit_recruitment, hrsuit_identity, hrsuit_workflow, and possibly salarydb. Infrastructure: PostgreSQL; RabbitMQ dependency for this profile is Requires Confirmation. Estimated RAM: Requires Confirmation. Health: ports 5241, 5000, 5010, 5251, 5173. Smoke: microservices/scripts/smoke-recruitment.ps1. Gateway cutover state defaults to false in checked-in Gateway settings.

Attendance Profile

Purpose: attendance, shift policy, and time-office routes. Services: Attendance, Gateway, Identity, Client Portal; SalarySystem when routing switches are false. Databases: hrsuit_attendance, hrsuit_identity, and salarydb for fallback. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Health: ports 5041, 5000, 5010, 5223, 5173. Smoke: smoke-attendance.ps1 and attendance-shift-cutover-go-no-go.ps1.

Leave Profile

Purpose: leave and leave-configuration flows. Services: Leave, Gateway, Identity, Workflow when approval routing is enabled, Client Portal; SalarySystem for fallback. Databases: hrsuit_leave, hrsuit_identity, hrsuit_workflow, salarydb as applicable. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Health: ports 5050, 5000, 5010, 5251, 5223, 5173. Smoke: smoke-leave.ps1.

Asset Profile

Purpose: extracted asset management and approval parity. Services: Asset, Gateway, Identity, Workflow when enabled, Client Portal; SalarySystem for compatibility. Databases: hrsuit_asset plus identity/workflow/fallback stores. Infrastructure: PostgreSQL; messaging requirement is Requires Confirmation. Estimated RAM: Requires Confirmation. Health: ports 5292, 5000, 5010, 5251, 5173. Smoke: smoke-asset.ps1, compare-asset-parity.ps1, asset-cutover-go-no-go.ps1.

Helpdesk Profile

Purpose: extracted helpdesk development and parity validation. Services: Helpdesk, Gateway, Identity, Client Portal; SalarySystem for fallback. Databases: hrsuit_helpdesk, identity and fallback stores. Infrastructure: PostgreSQL; messaging requirement is Requires Confirmation. Estimated RAM: Requires Confirmation. Health: ports 5311, 5000, 5010, 5173. Smoke: smoke-helpdesk.ps1, compare-helpdesk-parity.ps1, helpdesk-cutover-go-no-go.ps1.

Notification Profile

Purpose: notifications and notification configuration. Services: Notification, Gateway, Identity, Client Portal. Databases: hrsuit_notification, hrsuit_identity. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Health: ports 5074, 5000, 5010, 5173. Smoke: smoke-notification.ps1.

Workflow Profile

Purpose: workflow configuration and approval integration. Services: Workflow, Gateway, Identity, and the domain service publishing or consuming the approval flow. Databases: hrsuit_workflow, hrsuit_identity, plus domain store. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Health: ports 5251, 5000, 5010 and domain service health. Smoke: smoke-workflow.ps1 plus domain-specific smoke.

Reporting Profile

Purpose: reporting-service development. Services: Reporting on 5116; its Gateway route and required upstream services are Requires Confirmation. Database: Requires Confirmation. Infrastructure: Requires Confirmation. Estimated RAM: Requires Confirmation. Health: http://localhost:5116/health. Smoke test: no smoke-reporting.ps1 was found; Requires Confirmation.

Full Canonical Stack

Purpose: checked-in golden full-access topology. Services: every entry in scripts/full-local-stack.config.psd1. Databases: salarydb, hrsuit_platform, hrsuit_identity, hrsuit_employee, hrsuit_attendance, hrsuit_leave, hrsuit_payroll, hrsuit_workflow, hrsuit_document, hrsuit_notification. Infrastructure: PostgreSQL and RabbitMQ. Estimated RAM: Requires Confirmation. Typical scenarios: end-to-end changes, Gateway routing, cross-module flows, portal regression. Health: all canonical URLs in the inventory. Smoke: scripts/smoke-full-local.ps1.

Complete Regression Stack

Purpose: execute the broadest checked-in microservice regression. Services and databases: determined by microservices/scripts/run-v1-regression.ps1 plus its called smoke scripts. This is not identical to the canonical launcher. Infrastructure: PostgreSQL, RabbitMQ, and any dependencies asserted by the script. Estimated RAM: Requires Confirmation. Typical scenarios: release and cutover verification. Health endpoints: all invoked-service /health endpoints. Smoke: microservices/scripts/run-v1-regression.ps1. A single checked-in launcher for every executable project was not found; exact one-command startup is Requires Confirmation.

Feature → Service Mapping

Feature	Frontend	Gateway Route	Backend Service	Database	Messaging	Dependencies	Workflow	Notification
Authentication / activation	Both portals	/identity when AuthRouting:UseIdentityAuth=true; otherwise compatibility route	Identity / SalarySystem fallback	hrsuit_identity / salarydb	RabbitMQ configured	Platform capability client	No verified direct requirement	Activation behavior exists; delivery channel Requires Confirmation
Tenant and SaaS platform	Super Admin	/platform	Platform	hrsuit_platform	RabbitMQ configured	Identity provisioning client	Requires Confirmation	Requires Confirmation
Public registration	Client/public UI	/api/public	Platform	hrsuit_platform	RabbitMQ configured	Identity provisioning	Requires Confirmation	Verification behavior exists; channel Requires Confirmation
Employees	Client	/employee and employee-owned /api when cut over	Employee / SalarySystem fallback	hrsuit_employee / salarydb	RabbitMQ configured	Identity; fallback monolith	Requires Confirmation	Requires Confirmation
Attendance	Client	/attendance-service, /api/time-office	Attendance / SalarySystem fallback	hrsuit_attendance / salarydb	RabbitMQ configured	Workforce identity	Requires Confirmation	Requires Confirmation
Leave	Client	/leave, /api/leave-config	Leave / SalarySystem fallback	hrsuit_leave / salarydb	RabbitMQ configured	Identity	Optional via LEAVE_APPROVAL_USE_WORKFLOW	Requires Confirmation
Payroll	Client	/payroll, /api/payroll-config	Payroll / SalarySystem fallback	hrsuit_payroll / salarydb	RabbitMQ configured	Attendance; workforce data	Requires Confirmation	Requires Confirmation
Workflow configuration	Client/admin	/api/workflow-config	Workflow	hrsuit_workflow	RabbitMQ configured	Domain approval services	Owner	Requires Confirmation
Documents	Client	/documents-service, /api/document-config	Document / SalarySystem fallback	hrsuit_document / salarydb	RabbitMQ configured	Document storage configuration	Requires Confirmation	Requires Confirmation
Notifications	Both portals	/notifications, /api/notification-config	Notification	hrsuit_notification	RabbitMQ configured	Identity/tenant context	Consumes workflow-related behavior: exact contract Requires Confirmation	Owner
Recruitment	Client	Destination and switch verified; exact public prefix Requires Confirmation	Recruitment / SalarySystem fallback	hrsuit_recruitment / salarydb	Requires Confirmation	Identity	Optional via RECRUITMENT_APPROVAL_USE_WORKFLOW	Requires Confirmation
Expense	Client	Destination verified; exact prefix Requires Confirmation	Expense / SalarySystem fallback	hrsuit_expense / salarydb	Requires Confirmation	Identity	Optional via EXPENSE_APPROVAL_USE_WORKFLOW	Requires Confirmation
Asset	Client	Destination verified; exact prefix Requires Confirmation	Asset / SalarySystem fallback	hrsuit_asset / salarydb	Requires Confirmation	Identity	Optional via ASSET_APPROVAL_USE_WORKFLOW	Requires Confirmation
Performance	Client	Destination verified; exact prefix Requires Confirmation	Performance / SalarySystem fallback	hrsuit_performance / salarydb	Requires Confirmation	Identity	Optional via PERFORMANCE_APPROVAL_USE_WORKFLOW	Requires Confirmation
Training	Client	Destination verified; exact prefix Requires Confirmation	Training	hrsuit_training	Requires Confirmation	Identity	Requires Confirmation	Requires Confirmation
Helpdesk	Client	Destination and switch verified; exact prefix Requires Confirmation	Helpdesk / SalarySystem fallback	hrsuit_helpdesk / salarydb	Requires Confirmation	Identity	Requires Confirmation	Requires Confirmation
Reporting	Client/admin	Requires Confirmation	Reporting	Requires Confirmation	Requires Confirmation	Requires Confirmation	No verified ownership	No verified ownership
Integration	None verified	Requires Confirmation	Integration	hrsuit_integration	Requires Confirmation	Requires Confirmation	Requires Confirmation	Requires Confirmation
HR operations	Client	Compatibility routes Requires Confirmation	HR Operations project and SalarySystem compatibility	Requires Confirmation	Requires Confirmation	Requires Confirmation	Requires Confirmation	Requires Confirmation

Module Testing Guides

The following guides use only checked-in projects, health endpoints, and smoke-script names. “Typical APIs” names the verified Gateway boundary where known; it does not assert individual controller actions.

Identity

• Purpose: authentication, activation, bootstrap, session identity, and cutover from legacy authentication.
• Required services: Identity; add Platform for capability/provisioning; add SalarySystem for compatibility; Gateway for public-path testing.
• Required databases: hrsuit_identity; add hrsuit_platform and salarydb for those scenarios.
• Required queues: exact queues Requires Confirmation; exchange is hr-suit.integration-events.
• Frontend: both portals.
• Smoke tests: smoke-identity.ps1, smoke-auth-cutover.ps1, smoke-identity-bootstrap.ps1, smoke-identity-monolith-compat.ps1.
• Health: http://localhost:5010/health.
• Typical API boundary: /identity.
• Known dependencies: Platform capabilities and shared JWT issuer/audience/key.
• Known issues: the checked-in Gateway default keeps identity auth routing disabled; enable deliberately for cutover testing.
• Recommended profile: Authentication.

Employee

• Purpose: extracted employee/workforce capability.
• Required services: Employee, Identity, Gateway; SalarySystem for fallback/parity.
• Database: hrsuit_employee; salarydb for fallback.
• Queues: exact names Requires Confirmation.
• Frontend: Client HRMS Portal.
• Smoke: smoke-employee.ps1.
• Health: http://localhost:5267/health.
• Typical boundary: /employee plus employee-owned /api routes.
• Dependencies: tenant and identity context; other downstream guards are configuration-dependent.
• Known issue: EmployeeRouting:UseEmployeeService defaults false in Gateway appsettings.
• Profile: Core HR.

Attendance

• Purpose: attendance, time office, and shift-policy extraction.
• Services: Attendance, Identity, Gateway, Client Portal; SalarySystem for parity/fallback.
• Database: hrsuit_attendance.
• Queues: Requires Confirmation.
• Smoke: smoke-attendance.ps1, compare-attendance-shift-parity.ps1, attendance-shift-cutover-go-no-go.ps1.
• Health: http://localhost:5041/health.
• Typical boundaries: /attendance-service, /api/time-office.
• Dependencies: workforce identity; Payroll reads attendance in payroll scenarios.
• Known issue: port 5040 is intentionally avoided; routing switches default false outside the canonical Compose overrides.
• Profile: Attendance.

Leave

• Purpose: leave transactions and leave configuration.
• Services: Leave, Identity, Gateway; Workflow when approvals use it; SalarySystem for fallback.
• Database: hrsuit_leave.
• Queues: Requires Confirmation.
• Smoke: smoke-leave.ps1.
• Health: http://localhost:5050/health.
• Typical boundaries: /leave, /api/leave-config.
• Dependencies: optional Workflow through LEAVE_APPROVAL_USE_WORKFLOW.
• Known issue: conflicts with Integration Service on 5050.
• Profile: Leave.

Payroll

• Purpose: payroll operations and configuration.
• Services: Payroll, Attendance, workforce owner, Identity, Gateway, Client Portal.
• Database: hrsuit_payroll.
• Queues: Requires Confirmation.
• Smoke: smoke-payroll.ps1, smoke-payroll-cutover.ps1, compare-payroll-parity.ps1, payroll-cutover-go-no-go.ps1, scripts/validate-payroll-scenarios.ps1.
• Health: http://localhost:5158/health.
• Typical boundaries: /payroll, /api/payroll-config.
• Dependencies: Attendance and workforce data; availability relaxation is controlled by PayrollGuard__RelaxWhenPayrollUnavailableInDevelopment.
• Known issue: routing switch defaults false in Gateway appsettings.
• Profile: Payroll.

Recruitment

• Purpose: positions, candidates, interviews, offers, and extracted recruitment parity.
• Services: Recruitment, Identity, Gateway, Workflow for enabled approvals, Client Portal; SalarySystem fallback.
• Database: hrsuit_recruitment; legacy recruitment data also exists in salarydb compatibility storage.
• Queues: Requires Confirmation.
• Smoke: smoke-recruitment.ps1.
• Health: http://localhost:5241/health.
• Typical API: exact extracted Gateway prefix Requires Confirmation; legacy source documents /api/hr-suite/recruitment/*.
• Dependencies: optional Workflow via RECRUITMENT_APPROVAL_USE_WORKFLOW.
• Known issue: routing switch defaults false.
• Profile: Recruitment.

Performance

• Purpose: extracted performance capability and parity validation.
• Services: Performance, Identity, Gateway, optional Workflow, Client Portal, SalarySystem fallback.
• Database: hrsuit_performance.
• Queues and exact Gateway prefix: Requires Confirmation.
• Smoke: smoke-performance.ps1, compare-performance-parity.ps1, performance-cutover-go-no-go.ps1.
• Health: http://localhost:5296/health.
• Dependencies: optional Workflow via PERFORMANCE_APPROVAL_USE_WORKFLOW.
• Known issue: not started by the canonical full-local launcher.
• Profile: Complete Regression or a focused manual profile.

Training

• Purpose: extracted training capability.
• Services: Training, Identity, Gateway, Client Portal.
• Database: hrsuit_training.
• Queues: Requires Confirmation.
• Smoke: smoke-training.ps1.
• Health: launch profile http://localhost:5307/health.
• Typical API and dependencies: Requires Confirmation.
• Known issue: Gateway defaults to port 5321 while the service launch profile uses 5307.
• Profile: focused manual profile after overriding TRAINING_SERVICE_BASE_URL to the actual service URL.

Asset

• Purpose: asset lifecycle and approval extraction.
• Services: Asset, Identity, Gateway, optional Workflow, Client Portal, SalarySystem fallback.
• Database: hrsuit_asset.
• Queues and exact Gateway prefix: Requires Confirmation.
• Smoke: smoke-asset.ps1, compare-asset-parity.ps1, asset-cutover-go-no-go.ps1.
• Health: http://localhost:5292/health.
• Dependency: optional Workflow via ASSET_APPROVAL_USE_WORKFLOW.
• Known issue: not canonical-launcher managed.
• Profile: Asset.

Expense

• Purpose: expense lifecycle and approval extraction.
• Services: Expense, Identity, Gateway, optional Workflow, Client Portal, SalarySystem fallback.
• Database: hrsuit_expense.
• Queues and exact Gateway prefix: Requires Confirmation.
• Smoke: smoke-expense.ps1, compare-expense-parity.ps1, expense-cutover-go-no-go.ps1.
• Health: http://localhost:5288/health.
• Dependency: optional Workflow via EXPENSE_APPROVAL_USE_WORKFLOW.
• Known issue: not canonical-launcher managed.
• Profile: focused manual profile.

Helpdesk

• Purpose: ticket/helpdesk extraction and parity.
• Services: Helpdesk, Identity, Gateway, Client Portal, SalarySystem fallback.
• Database: hrsuit_helpdesk.
• Queues and exact Gateway prefix: Requires Confirmation.
• Smoke: smoke-helpdesk.ps1, compare-helpdesk-parity.ps1, helpdesk-cutover-go-no-go.ps1.
• Health: http://localhost:5311/health.
• Dependencies: identity and tenant context.
• Known issue: routing switch defaults false and service is not canonical-launcher managed.
• Profile: Helpdesk.

Workflow

• Purpose: workflow configuration and shared approval behavior.
• Services: Workflow, Identity, Gateway, and selected domain service.
• Database: hrsuit_workflow.
• Queues: exact names Requires Confirmation.
• Smoke: smoke-workflow.ps1.
• Health: http://localhost:5251/health.
• Typical boundary: /api/workflow-config.
• Dependencies: domain services opt in through approval environment switches.
• Known issues: end-to-end verification must include the participating domain service.
• Profile: Workflow.

Notification

• Purpose: notification delivery state and configuration.
• Services: Notification, Identity, Gateway, Client Portal.
• Database: hrsuit_notification.
• Queues: exact names Requires Confirmation.
• Smoke: smoke-notification.ps1.
• Health: http://localhost:5074/health.
• Typical boundaries: /notifications, /api/notification-config.
• Dependencies: RabbitMQ and tenant/identity context.
• Known issues: channel-specific external delivery prerequisites are Requires Confirmation.
• Profile: Notification.

Reporting

• Purpose: reporting API project.
• Services: Reporting; all upstream data dependencies Requires Confirmation.
• Database and queues: Requires Confirmation.
• Frontend: reporting views exist in the Client portal; binding to this extracted service is Requires Confirmation.
• Smoke: no dedicated checked-in reporting smoke script found.
• Health: http://localhost:5116/health.
• Typical APIs, dependencies, and known issues: Requires Confirmation.
• Profile: Reporting.

Platform

• Purpose: tenants, licensing, features, branding, subscriptions, provisioning, public registration, and SaaS administration.
• Services: Platform, Identity for provisioning, Gateway, Super Admin Portal; Client Portal for public signup scenarios.
• Database: hrsuit_platform; tenant provisioning has a second EF model snapshot in the Platform project.
• Queues: exact names Requires Confirmation; RabbitMQ is configured.
• Smoke: smoke-platform.ps1 and the checked-in smoke-platform-* suite, smoke-registration.ps1, smoke-customer-lifecycle.ps1.
• Health: http://localhost:5097/health.
• Typical boundaries: /platform, /api/public.
• Dependencies: Identity provisioning token and shared JWT settings.
• Known issue: provisioning worker defaults false in .env.example.
• Profile: Authentication or Full Canonical Stack.

CRM

• Purpose: sales CRM behavior is represented by smoke-sales-crm.ps1 and Super Admin UI code.
• Required services, database owner, queues, Gateway route, health endpoint, typical APIs, and extracted canonical owner: Requires Confirmation.
• Frontend: Super Admin Portal.
• Smoke: microservices/scripts/smoke-sales-crm.ps1.
• Known issue: no crm-service project exists in the microservice solution.
• Profile: Full Canonical Stack, with prerequisites read from the smoke script before execution.

Integration

• Purpose: integration service project.
• Services: Integration; other dependencies Requires Confirmation.
• Database: hrsuit_integration.
• Queues and frontend: Requires Confirmation.
• Smoke: smoke-integration.ps1.
• Health: http://localhost:5050/health.
• Typical APIs: Requires Confirmation.
• Known issue: its launch port conflicts with Leave.
• Profile: focused manual profile with a port override.

Environment Variables

The tables cover variables verified in canonical examples, launch scripts, or runtime source. Values containing secrets are development examples only and must not be committed with real credentials.

Canonical host launcher

Name	Default	Used by	Required	Security considerations
HR_SUIT_POSTGRES_PASSWORD	postgres	Full-local scripts	Optional locally	Secret; local fallback only
HR_SUIT_RABBITMQ_USERNAME	guest	Full-local scripts	Optional locally	Do not reuse outside localhost
HR_SUIT_RABBITMQ_PASSWORD	guest	Full-local scripts	Optional locally	Secret; do not reuse outside localhost
JWT_KEY	Checked-in development fallback	Full-local services	Optional only for local launcher	Secret; replace outside development
ASPNETCORE_ENVIRONMENT	Launcher sets Development	.NET services	Yes for expected dev behavior	Development may expose Swagger/tokens
ASPNETCORE_URLS	Set per process by --urls or Compose http://+:8080	.NET services	Supplied by launcher	Avoid public binding on untrusted networks

Compose ports and origins

Name	Default/example	Used by	Required	Security considerations
GATEWAY_HTTP_PORT	5000	Compose Gateway	Yes in .env.example	Local HTTP only
IDENTITY_HTTP_PORT	5010	Compose Identity	Yes	Local HTTP only
PLATFORM_HTTP_PORT	5097	Compose Platform	Yes	Local HTTP only
MONOLITH_HTTP_PORT	5223	Compose monolith	Optional default exists	Local HTTP only
EMPLOYEE_HTTP_PORT	5267	Compose Employee	Optional default exists	Local HTTP only
ATTENDANCE_HTTP_PORT	5041	Compose Attendance	Optional default exists	Local HTTP only
LEAVE_HTTP_PORT	5050	Compose Leave	Optional default exists	Conflicts with Integration host profile
PAYROLL_HTTP_PORT	5158	Compose Payroll	Optional default exists	Local HTTP only
WORKFLOW_HTTP_PORT	5251	Compose Workflow	Optional default exists	Local HTTP only
DOCUMENT_HTTP_PORT	5168	Compose Document	Optional default exists	Local HTTP only
NOTIFICATION_HTTP_PORT	5074	Compose Notification	Optional default exists	Local HTTP only
CLIENT_ORIGIN	http://localhost:5173	Gateway CORS	Yes in Compose	Restrict outside development
ADMIN_ORIGIN	http://localhost:5174	Gateway CORS	Yes in Compose	Restrict outside development

Service discovery and routing

Name	Default/example	Used by	Required	Security considerations
MONOLITH_BASE_URL	Compose http://monolith:8080; host http://localhost:5223	Gateway	Yes	Internal URL
IDENTITY_SERVICE_BASE_URL	Compose http://identity-service:8080	Gateway	Canonical Compose	Internal URL
PLATFORM_SERVICE_BASE_URL	Compose http://platform-service:8080	Gateway	Canonical Compose	Internal URL
EMPLOYEE_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
ATTENDANCE_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
LEAVE_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
PAYROLL_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
WORKFLOW_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
DOCUMENT_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
NOTIFICATION_SERVICE_BASE_URL	Compose service URL	Gateway	When destination used	Internal URL
RECRUITMENT_SERVICE_BASE_URL	Host default http://localhost:5241	Gateway	When destination used	Internal URL
HELPDESK_SERVICE_BASE_URL	Host default http://localhost:5311	Gateway	When destination used	Internal URL
EXPENSE_SERVICE_BASE_URL	Host default http://localhost:5288	Gateway	When destination used	Internal URL
ASSET_SERVICE_BASE_URL	Host default http://localhost:5292	Gateway	When destination used	Internal URL
PERFORMANCE_SERVICE_BASE_URL	Host default http://localhost:5296	Gateway	When destination used	Internal URL
TRAINING_SERVICE_BASE_URL	Gateway default http://localhost:5321	Gateway	When destination used	Must reconcile with launch profile 5307

Routing switches verified in source are EMPLOYEE_ROUTING_USE_EMPLOYEE_SERVICE, ATTENDANCE_ROUTING_USE_ATTENDANCE_SERVICE, ATTENDANCE_ROUTING_USE_SHIFT_POLICY_SERVICE, LEAVE_ROUTING_USE_LEAVE_SERVICE, PAYROLL_ROUTING_USE_PAYROLL_SERVICE, DOCUMENT_ROUTING_USE_DOCUMENT_SERVICE, NOTIFICATION_ROUTING_USE_NOTIFICATION_SERVICE, RECRUITMENT_ROUTING_USE_RECRUITMENT_SERVICE, HELPDESK_ROUTING_USE_HELPDESK_SERVICE, EXPENSE_ROUTING_USE_EXPENSE_SERVICE, ASSET_ROUTING_USE_ASSET_SERVICE, PERFORMANCE_ROUTING_USE_PERFORMANCE_SERVICE, and AUTH_ROUTING_USE_IDENTITY_AUTH. Checked-in Gateway JSON defaults the core cutover switches to false; canonical Compose explicitly enables several extracted destinations.

Database variables

Name/group	Default/example	Used by	Required	Security considerations
ConnectionStrings__DefaultConnection	Local value in appsettings	SalarySystem	Yes	Contains database credentials
ConnectionStrings__PlatformDb	hrsuit_platform connection	Platform	Yes	Secret-bearing
ConnectionStrings__IdentityDb	hrsuit_identity connection	Identity	Yes	Secret-bearing
ConnectionStrings__EmployeeDb	hrsuit_employee connection	Employee	Yes	Secret-bearing
ConnectionStrings__AttendanceDb	hrsuit_attendance connection	Attendance	Yes	Secret-bearing
ConnectionStrings__LeaveDb	hrsuit_leave connection	Leave	Yes	Secret-bearing
ConnectionStrings__PayrollDb	hrsuit_payroll connection	Payroll	Yes	Secret-bearing
ConnectionStrings__WorkflowDb	hrsuit_workflow connection	Workflow	Yes	Secret-bearing
ConnectionStrings__DocumentDb	hrsuit_document connection	Document	Yes	Secret-bearing
ConnectionStrings__NotificationDb	hrsuit_notification connection	Notification	Yes	Secret-bearing
ConnectionStrings__RecruitmentDb	hrsuit_recruitment connection	Recruitment	Yes when run	Secret-bearing
ConnectionStrings__ExpenseDb	hrsuit_expense connection	Expense	Yes when run	Secret-bearing
ConnectionStrings__AssetDb	hrsuit_asset connection	Asset	Yes when run	Secret-bearing
ConnectionStrings__PerformanceDb	hrsuit_performance connection	Performance	Yes when run	Secret-bearing
ConnectionStrings__TrainingDb	hrsuit_training connection	Training	Yes when run	Secret-bearing
ConnectionStrings__HelpdeskDb	hrsuit_helpdesk connection	Helpdesk	Yes when run	Secret-bearing
ConnectionStrings__IntegrationDb	hrsuit_integration connection	Integration	Yes when run	Secret-bearing
PLATFORM_DB_*, IDENTITY_DB_*, MONOLITH_DB_*, LEAVE_DB_*, MODULE_DB_*	See microservices/.env.example	Compose PostgreSQL services	Yes for relevant containers	Password values are secrets

JWT, messaging, provisioning, behavior, and frontend

Name/group	Default/example	Used by	Required	Security considerations
JWT_ISSUER	hr-suit.identity	Compose services	Yes	Must match all validators
JWT_AUDIENCE	hr-suit.services	Compose services	Yes	Must match all validators
JWT_KEY	Change-me example	All authenticating services	Yes	High-value secret; minimum length enforced by context
IDENTITY_BOOTSTRAP_PLATFORM_TOKEN	Local example token	Platform/Identity provisioning	Required for provisioning	Service credential; rotate and protect
RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS	guest / guest	Compose RabbitMQ/apps	Yes in Compose	Local-only defaults
RABBITMQ_AMQP_PORT, RABBITMQ_MANAGEMENT_PORT	5672, 15672	Compose	Yes	Do not expose publicly
RABBITMQ_EXCHANGE_NAME	hr-suit.integration-events	Services	Yes when messaging enabled	Not secret
PLATFORM_PROVISIONING_WORKER_ENABLED	false	Platform	Optional	Enabling causes background mutations
PLATFORM_TENANT_DATABASE_PREFIX	hrsuit_tenant	Platform	Required when provisioning	Validate generated DB names
Growth__Provisioning__*	Source-defined	Platform	Scenario-dependent	Service token is secret
Growth__Verification__ExposeCodeInDevelopment	Source-defined	Platform	Optional	Never enable outside development
IdentityBootstrap__ExposeActivationTokenInDevelopment	Source-defined	Identity	Optional	Never expose outside development
*_APPROVAL_USE_WORKFLOW	Source-defined	Domain services	Optional	Changes write/approval behavior
OutboxRelay__Transport, OutboxRelay__MaxRetries	Source-defined	Outbox-enabled services	Optional	Transport changes delivery semantics
VITE_API_BASE_URL	http://localhost:5000	Both portals	Yes	Public build-time value; never put secrets in Vite vars
VITE_USE_PLATFORM_SERVICE	false in .env.example; true in Gateway example	Frontend	Optional	Public build-time value
VITE_PLATFORM_GATEWAY_BASE_URL	http://localhost:5000	Frontend	Scenario-dependent	Public value
VITE_SUPER_ADMIN_PORTAL_URL	http://localhost:5174	Client portal	Optional	Public value
VITE_CLIENT_PORTAL_URL	http://localhost:5173	Portal handoff	Optional	Public value
VITE_WORKSPACE_BASE_DOMAIN	localhost	Signup/workspace flow	Optional	Public value
VITE_LEGAL_TERMS_URL, VITE_PRIVACY_POLICY_URL, VITE_SIGNUP_SUPPORT_EMAIL	Example.com values	Public signup UI	Optional	Replace examples before release

Additional deployment-only variables found in scripts (SECRET_ARN_*, VPC_CONNECTOR_ARN, OBSERVABILITY_CONFIG_ARN, REGION, ACCOUNT_ID, IMAGE_TAG, DOCUMENTS_BUCKET, ROOT_DOMAIN) are not local-development prerequisites. Their local defaults and use are Requires Confirmation.

Ports

Service	Port	Protocol	Health URL	Swagger URL
Gateway	5000	HTTP	http://localhost:5000/health	http://localhost:5000/swagger
Identity	5010	HTTP	http://localhost:5010/health	http://localhost:5010/swagger
Tenant Provisioning	5014	HTTP	http://localhost:5014/health	http://localhost:5014/swagger
HR Operations	5028	HTTP	http://localhost:5028/health	http://localhost:5028/swagger
Attendance	5041	HTTP	http://localhost:5041/health	http://localhost:5041/swagger
Leave	5050	HTTP	http://localhost:5050/health	http://localhost:5050/swagger
Integration	5050	HTTP	http://localhost:5050/health	http://localhost:5050/swagger
Notification	5074	HTTP	http://localhost:5074/health	http://localhost:5074/swagger
Platform	5097	HTTP	http://localhost:5097/health	http://localhost:5097/swagger
Reporting	5116	HTTP	http://localhost:5116/health	http://localhost:5116/swagger
Payroll	5158	HTTP	http://localhost:5158/health	http://localhost:5158/swagger
Document	5168	HTTP	http://localhost:5168/health	http://localhost:5168/swagger
Client Portal	5173	HTTP	http://localhost:5173/	Not applicable
Super Admin Portal	5174	HTTP	http://localhost:5174/	Not applicable
SalarySystem	5223	HTTP	http://localhost:5223/health	http://localhost:5223/swagger/index.html
Recruitment	5241	HTTP	http://localhost:5241/health	http://localhost:5241/swagger
Workflow	5251	HTTP	http://localhost:5251/health	http://localhost:5251/swagger
Employee	5267	HTTP	http://localhost:5267/health	http://localhost:5267/swagger
Expense	5288	HTTP	http://localhost:5288/health	http://localhost:5288/swagger
Asset	5292	HTTP	http://localhost:5292/health	http://localhost:5292/swagger
Performance	5296	HTTP	http://localhost:5296/health	http://localhost:5296/swagger
Training launch profile	5307	HTTP	http://localhost:5307/health	http://localhost:5307/swagger
Training Gateway default	5321	HTTP	Depends on override	Depends on override
PostgreSQL	5432	PostgreSQL	Authenticated SELECT 1	Not applicable
RabbitMQ	5672	AMQP	Use management health check	Not applicable
RabbitMQ Management	15672	HTTP	http://localhost:15672/api/health/checks/alarms	Not applicable

Databases

Database	Owner	Connection name	Migration project/location	Seeder	Purpose	Required services
salarydb	SalarySystem	DefaultConnection	SalarySystem.csproj; exact migrations path Requires Confirmation	Application startup behavior; exact seeder Requires Confirmation	Legacy and compatibility persistence	SalarySystem
hrsuit_platform	Platform	PlatformDb	platform-service/Data/Migrations	Development startup seeding is documented in microservice README; class Requires Confirmation	Platform/SaaS state	Platform
hrsuit_identity	Identity	IdentityDb	identity-service/Data/Migrations	Development startup seeding is documented; class Requires Confirmation	Authentication/identity	Identity
hrsuit_employee	Employee	EmployeeDb	employee-service/Infrastructure/Migrations	Requires Confirmation	Employee/workforce	Employee
hrsuit_attendance	Attendance	AttendanceDb	attendance-service/Infrastructure/Migrations	Requires Confirmation	Attendance/time office	Attendance
hrsuit_leave	Leave	LeaveDb	leave-service/Infrastructure/Migrations	Requires Confirmation	Leave	Leave
hrsuit_payroll	Payroll	PayrollDb	payroll-service/Infrastructure/Migrations	Requires Confirmation	Payroll	Payroll
hrsuit_workflow	Workflow	WorkflowDb	workflow-service/Infrastructure/Migrations	Requires Confirmation	Workflow	Workflow
hrsuit_document	Document	DocumentDb	document-service/Infrastructure/Migrations	Requires Confirmation	Document metadata/state	Document
hrsuit_notification	Notification	NotificationDb	notification-service/Infrastructure/Migrations	Requires Confirmation	Notification state/configuration	Notification
hrsuit_recruitment	Recruitment	RecruitmentDb	recruitment-service/Infrastructure/Migrations	Requires Confirmation	Recruitment	Recruitment
hrsuit_expense	Expense	ExpenseDb	expense-service/Infrastructure/Migrations	Requires Confirmation	Expenses	Expense
hrsuit_asset	Asset	AssetDb	asset-service/Infrastructure/Migrations	Requires Confirmation	Assets	Asset
hrsuit_performance	Performance	PerformanceDb	performance-service/Infrastructure/Migrations	Requires Confirmation	Performance	Performance
hrsuit_training	Training	TrainingDb	training-service/Infrastructure/Migrations	Requires Confirmation	Training	Training
hrsuit_helpdesk	Helpdesk	HelpdeskDb	helpdesk-service/Infrastructure/Migrations	Requires Confirmation	Helpdesk	Helpdesk
hrsuit_integration	Integration	IntegrationDb	integration-service/Infrastructure/Migrations	Requires Confirmation	Integration state	Integration

Platform also contains Provisioning/Migrations/TenantProvisioningDbContextModelSnapshot.cs. Its physical database placement is configuration-dependent and therefore Requires Confirmation.

Messaging

Item	Verified value
Broker	RabbitMQ
Host / AMQP port	localhost:5672 for host processes; rabbitmq:5672 in Compose
Management	localhost:15672
Virtual host	/
Exchange	hr-suit.integration-events
Publishers	Multiple services reference shared RabbitMQ/outbox configuration; authoritative event-by-event publisher list Requires Confirmation
Consumers	Authoritative queue binding and consumer list Requires Confirmation
Queue names	Requires Confirmation
Retry/dead-letter topology	Requires Confirmation

Do not create queue names from event class names. Verify broker declarations or consumer registration code before extending this section.

Health Checks

Canonical group

http://localhost:5000/health
http://localhost:5000/health/downstreams   # Development only
http://localhost:5097/health
http://localhost:5010/health
http://localhost:5223/health
http://localhost:5267/health
http://localhost:5041/health
http://localhost:5050/health
http://localhost:5158/health
http://localhost:5251/health
http://localhost:5168/health
http://localhost:5074/health
http://localhost:5173/
http://localhost:5174/

Optional service group

http://localhost:5014/health   # Tenant Provisioning
http://localhost:5028/health   # HR Operations
http://localhost:5116/health   # Reporting
http://localhost:5241/health   # Recruitment
http://localhost:5288/health   # Expense
http://localhost:5292/health   # Asset
http://localhost:5296/health   # Performance
http://localhost:5307/health   # Training launch profile
http://localhost:5311/health   # Helpdesk
http://localhost:5050/health   # Integration; cannot coexist with Leave on same host port

An HTTP 200 on a service /health proves the registered health checks pass. It does not prove Gateway routing or authorization. Use scripts/smoke-full-local.ps1 after direct health checks.

Smoke Testing

Module	Minimum services	Verification	Expected result
Identity	Identity; add Gateway for route test	Run smoke-identity.ps1; query health first	Script exits 0; health is 2xx
Platform	Platform, Identity for provisioning, Gateway	Run appropriate smoke-platform-*.ps1	Script exits 0 and assertions pass
Employee	Employee, Gateway, Identity	Run smoke-employee.ps1	No missing route/5xx; assertions pass
Attendance	Attendance, Gateway, Identity	Run smoke-attendance.ps1	Attendance assertions pass
Leave	Leave, Gateway, Identity; Workflow if enabled	Run smoke-leave.ps1	Leave assertions pass
Payroll	Payroll, Attendance, Gateway, Identity/workforce	Run smoke-payroll.ps1	Payroll assertions pass
Workflow	Workflow, Gateway, Identity	Run smoke-workflow.ps1	Workflow assertions pass
Document	Document, Gateway, Identity	Run smoke-documents.ps1; sync scenario uses smoke-document-sync.ps1	Document assertions pass
Notification	Notification, Gateway, Identity	Run smoke-notification.ps1	Notification assertions pass
Recruitment	Recruitment plus script prerequisites	Run smoke-recruitment.ps1	Recruitment assertions pass
Expense	Expense plus script prerequisites	Run smoke-expense.ps1	Expense assertions pass
Asset	Asset plus script prerequisites	Run smoke-asset.ps1	Asset assertions pass
Performance	Performance plus script prerequisites	Run smoke-performance.ps1	Performance assertions pass
Training	Training plus script prerequisites	Reconcile port, then run smoke-training.ps1	Training assertions pass
Helpdesk	Helpdesk plus script prerequisites	Run smoke-helpdesk.ps1	Helpdesk assertions pass
Integration	Integration, with Leave stopped or port overridden	Run smoke-integration.ps1	Integration assertions pass
Reporting	Reporting	Check /health; dedicated smoke Requires Confirmation	Health is 2xx; functional expected result Requires Confirmation
Full stack	Canonical stack	Run scripts/smoke-full-local.ps1	All direct health checks and Gateway route probes pass

The full smoke permits 401 or 403 on protected routes without a token but treats 404, 502, 503, connection failures, and timeouts as failures. This verifies route existence without weakening authorization.

Troubleshooting

Port conflict

1. Run Get-NetTCPConnection -State Listen -LocalPort <port>.
2. Resolve the owning PID with Get-Process -Id <pid>.
3. If it is a healthy HR Suit service, reuse it. The canonical launcher already does this.
4. If it is unrelated, stop it through its normal application/service controls or choose an explicit URL override.
5. Never terminate an unknown process solely by port number.

Gateway not routing

1. Verify http://localhost:5000/health.
2. In Development, verify http://localhost:5000/health/downstreams.
3. Verify the target service directly at its /health URL.
4. Check the relevant *_SERVICE_BASE_URL and routing switch.
5. In containers, use Compose DNS names, not localhost, for service-to-service URLs.
6. Run scripts/smoke-full-local.ps1 and inspect Gateway logs under run-logs/full-local/services.

Identity unavailable

Verify PostgreSQL, hrsuit_identity, :5010/health, shared JWT_ISSUER, JWT_AUDIENCE, and JWT_KEY. If testing extracted auth, verify AUTH_ROUTING_USE_IDENTITY_AUTH. Do not change signing keys in only one service.

RabbitMQ unavailable

Verify ports 5672 and 15672 and call the management alarm health endpoint with configured credentials. Run microservices/scripts/start-local-rabbitmq.ps1 or start the installed RabbitMQ service. Do not delete broker data or queues as a first-line fix.

Migration failure

1. Confirm the service uses the intended connection string and database.
2. Read the complete service log and identify the failing migration.
3. Use the owning project/context. Platform uses PlatformDbContext; Identity uses IdentityDbContext.
4. Back up any non-disposable database before update or rollback.
5. Do not use EnsureCreated to bypass migrations.
6. Do not delete a database unless the user has explicitly confirmed it is disposable.

Database unavailable

Run the authenticated SELECT 1, verify port 5432, then verify the logical database exists. The launcher can create a missing database but will not repair credentials or destructive schema drift.

Frontend cannot log in

Verify the portal is using http://localhost:5000 in canonical mode, Gateway CORS contains ports 5173 and 5174, Identity is healthy, and the login is attempted in the correct portal. Super Admin accounts belong in the Super Admin portal.

Swagger unavailable

Verify the service is running in Development and /health succeeds. Try /swagger and /swagger/index.html. Swagger middleware is registered in the executable services, but environment gating and exact UI suffix should be read from that service's Program.cs before changing configuration.

Health endpoint failing

Inspect the service stderr/stdout logs. A port listener is not sufficient: the launcher requires a successful HTTP health response. Check its database first, then RabbitMQ and configured downstream clients.

Frontend health succeeds but APIs fail

Vite serving / only proves the UI process is live. Inspect VITE_API_BASE_URL, browser network requests, CORS, Gateway health, and the target downstream health.

Known Port Conflicts

Conflict	Evidence	Safe resolution
Leave and Integration both use 5050	Both Properties/launchSettings.json files specify http://localhost:5050	Keep Leave on canonical 5050; start Integration with dotnet run --project ... --urls http://localhost:<free-port> and update its caller. Recommended exact override: Requires Confirmation
Training launch profile 5307 vs Gateway destination 5321	Training launch settings and Gateway appsettings disagree	Override TRAINING_SERVICE_BASE_URL=http://localhost:5307 or deliberately launch on 5321; select one per session
Port 5040 reserved on accepted dev machine	docs/full-local-stack.md and canonical config use Attendance 5041	Keep Attendance on 5041

Performance Recommendations

No repeatable resource benchmark is checked in. The following are topology recommendations, not numerical capacity claims.

Profile	Recommended use	Services	Estimated RAM	Estimated CPU
Minimal	Single-module implementation	Infrastructure plus Identity/Gateway and one domain service; add portal only when needed	Requires Confirmation	Requires Confirmation
Medium	Cross-module feature	Infrastructure, Platform, Identity, SalarySystem fallback, affected services, Gateway, one portal	Requires Confirmation	Requires Confirmation
Full	End-to-end and pre-PR smoke	Canonical full-local stack	Requires Confirmation	Requires Confirmation
Regression	Cutover/release verification	Services required by run-v1-regression.ps1	Requires Confirmation	Requires Confirmation

Prefer reusing healthy services. Use dotnet run --no-build only after a successful build and when source has not changed. Keep databases and RabbitMQ running between sessions if local policy permits; stop application processes with the orchestrator.

Daily Developer Checklist

Before coding

• Pull the intended branch and inspect local changes before modifying files.
• Confirm .NET SDK, Node/npm, PostgreSQL, psql, and RabbitMQ/Docker availability.
• Select the smallest adequate run profile.
• Verify environment files contain no production secrets.
• Run scripts/status-full-local.ps1 if reusing a previous stack.

Before debugging

• Confirm direct /health for every service in the selected profile.
• Confirm Gateway /health/downstreams when using Gateway.
• Confirm the portal's VITE_API_BASE_URL.
• Confirm routing switches match the service under test.
• Record relevant stdout/stderr and reproduce with the smallest smoke script.

Before creating a PR

• Build changed .NET projects and affected portal(s).
• Run unit tests for affected projects.
• Run the module smoke test and any cutover/parity script relevant to routing changes.
• Run scripts/smoke-full-local.ps1 for cross-module or Gateway changes.
• Update this runbook when ports, dependencies, routes, databases, health checks, commands, or profiles changed.
• Confirm no real secrets, local logs, or generated build output are included unintentionally.

Before merge

• Resolve review feedback and rerun affected checks.
• Confirm migration ownership and rollback notes for schema changes.
• Confirm routing defaults are intentional.
• Confirm new services are represented in the canonical config or explicitly marked non-canonical.
• Confirm this page contains no guessed values.

AI Assistant Notes

Future AI assistants maintaining this page must follow these rules:

1. Never invent a service, endpoint, route, port, queue, exchange, database, variable, command, dependency, owner, resource estimate, or startup relationship.
2. Verify runtime facts from source. Prefer launch settings, Program.cs, appsettings, Compose, project files, scripts, and migration snapshots over prose documentation.
3. Prefer an extracted service over a legacy implementation only when routing/cutover configuration proves ownership for the described profile.
4. Preserve the distinction between “project exists” and “canonical launcher starts project.”
5. Write Requires Confirmation for any field that cannot be verified.
6. Never expose secrets from .env, user-secret stores, deployment configuration, or logs. Document variable names and safe examples only.
7. Treat current working-tree changes as user-owned. Do not revert unrelated edits.
8. When a routing switch changes, update the service inventory, feature map, relevant profile, smoke guidance, and troubleshooting section together.
9. When a port changes, search launch settings, appsettings, scripts, Compose, UI env examples, and documentation for drift.
10. Do not claim a smoke test passed unless it was executed successfully in the current environment.

Future Maintenance Rules

Whenever a service is added, removed, renamed, extracted, merged, or assigned a new route, update all of the following in the same change:

• Overview architecture diagram.
• Infrastructure requirements.
• Frontend dependency descriptions.
• Backend inventory and canonical status.
• Startup order and launcher configuration.
• Every affected run profile.
• Feature-to-service matrix.
• Module testing guide.
• Environment-variable inventory.
• Port table and known conflicts.
• Database ownership, connection name, migrations, and seeding.
• Messaging publishers, consumers, exchanges, and queues when verified.
• Direct and Gateway health checks.
• Smoke-test matrix and troubleshooting instructions.

Verification procedure for maintenance

1. List solution projects with dotnet sln microservices/HrSuit.Microservices.sln list.
2. Enumerate microservices/src/*/Properties/launchSettings.json.
3. Enumerate appsettings*.json, Compose variables, and runtime environment-variable reads.
4. Inspect every executable Program.cs for health, Swagger, controllers/minimal routes, clients, messaging, migrations, and seeders.
5. Inspect Gateway destinations, transforms, route switches, and downstream checks.
6. Inspect scripts/full-local-stack.config.psd1 and all start/status/stop/smoke scripts.
7. Enumerate EF model snapshots and context registration.
8. Inspect both portal Vite configurations, package scripts, and .env*.example files.
9. Search for duplicate ports.
10. Build the documentation site and fix broken Markdown, Mermaid, or links.

Source precedence

When sources disagree, use this order and record the discrepancy instead of hiding it:

1. Executable runtime code and explicit command-line arguments.
2. Canonical launcher configuration.
3. Environment-specific appsettings and launch profiles.
4. Docker Compose and example environment files for container mode.
5. Smoke/status scripts.
6. Existing prose documentation.

Verification record

This revision was derived from the following checked-in source categories: the root and microservice solutions, all service launch profiles, service appsettings, Gateway configuration, microservices/docker-compose.yml, microservices/.env.example, scripts/full-local-stack.config.psd1, canonical start/status/stop/smoke scripts, frontend package.json and example environment files, executable Program.cs health/Swagger registration, EF Core model snapshots, and the available smoke/cutover script inventory.

The requested rendered-page count cannot be verified from Markdown alone because it depends on the renderer, theme, page size, and print settings. Content completeness is governed by verified source coverage, not padding. Rendered length: Requires Confirmation.