Architecture - Swiss HR Easy

Deployment model: single-tenant

Every customer runs their own Azure environment — App Service, PostgreSQL Flexible Server, Blob Storage, and Key Vault. There is no shared database and no cross-customer data path. Multi-tenant is explicitly out of scope. Practical consequences:

Data residency is per customer. Swiss deployments run in Switzerland North.
Configuration, feature flags, and integrations are per installation.
Upgrades are per environment, so a customer can sit on a version while another moves.
Within one installation there may still be multiple legal employers — see Legal entities.

Technology

Layer	Choice
Framework	Next.js 15 (App Router), React 18, TypeScript
Database	PostgreSQL via Prisma — `prisma/schema.prisma` is the truth
Auth	Microsoft Entra ID (SSO) + signed magic links
Storage	Azure Blob Storage
Mail and Teams	Microsoft Graph
Secrets	Azure Key Vault (field-encryption key, integration credentials)
Observability	Azure Application Insights
AI	Anthropic Claude (reasoning), Voyage AI (embeddings)

Module structure

Features live in src/modules/{module}/ and expose a single public contract:

src/modules/{module}/
  services/     # business logic — the brain
  components/   # React components — the face
  types.ts      # module-specific types
  index.ts      # the only surface other modules may import

Anything not exported from index.ts is module-internal. Cross-module calls go through the contract, never into another module’s services/ directly. This is ADR-004. Shared, cross-cutting code lives in src/lib/ — authentication and RBAC, audit logging, the Prisma client singleton, storage, e-mail, Graph, crypto, and the Swiss helpers (cantons, AHV numbers, address and phone normalisation).

Modules at a glance

Recruitment

Positions, pipeline, interviews, references, talent pools, job distribution.

Employee lifecycle

Employment periods, leave, sick leave, holidays, on/offboarding.

Pre-boarding

The journey between “offer accepted” and “first day”.

Contracts

Templates, placeholder variables, generation, e-signature.

Certificates

Arbeitszeugnis, Zwischenzeugnis, Arbeitsbestätigung.

Probation

Reflective meeting companion and questionnaires.

Time tracking

Entries, weekly summaries, ArG break compliance.

Payroll

Monthly Lohnabrechnung engine and year-end declarations.

Bexio

Payroll-employee sync into bexio.

Compensation

Role catalog, salary bands, dated assignments.

Salary visibility

Masking and hand-picked salary access grants.

Budgeting

Five budgeting methods, forecasts, proposals.

Expenses

Receipt OCR, Swiss categories, two-level approval.

Feedback

Cycles, continuous feedback, growth journeys, team vitality.

Surveys

Anonymous employee surveys with k-anonymity.

Decision making

Consent, advice process, systemic consensus, dot voting.

Workflows

The visual engine behind approvals and checklists.

Semantic search

Embeddings, sentiment, event history, reasoning.

Document intelligence

Vectorless, reasoning-based retrieval over long documents.

Observability

Structured logging and Application Insights correlation.

Organization

Locations, teams, and the manager graph.

Reports

Cross-module reporting and exports.

Notifications

In-app inbox and subscription preferences.

How modules talk to each other

Modules communicate through an in-process event bus (src/lib/events/), not by reaching into each other:

eventBus.emit("employee.onboarded", { employeeId });

eventBus.on("employee.onboarded", async (data) => {
  /* … */
});

Events are named {module}.{entity}.{action}. The pre-boarding orchestrator is the clearest example: it listens for personal-data submission, document upload, and contract signature, and advances the journey without those modules knowing it exists. This is ADR-005.

Request path

Every API route follows the same skeleton — authenticate, check permission, check ownership, validate input with Zod, delegate to a service, write an audit entry, return a projected DTO. The rule set and the reasoning behind it are in API route conventions.

​Deployment model: single-tenant

​Technology

​Module structure

​Modules at a glance