Services & Infrastructure
Notifications, storage, background jobs, queues, and export orchestration
Notification System
The notification system supports email, push, in-app, and chat-platform delivery while keeping event production separate from delivery mechanics.
Core responsibilities:
- domain services emit organization-scoped events
- notification services choose channels and format messages
- queue-backed delivery handles retries and slower integrations
Storage Infrastructure
S3-compatible object storage is required for uploads, exports, attachments, and generated artifacts.
S3_BUCKET=your-bucket
S3_REGION=eu-central-1
S3_ACCESS_KEY_ID=<access-key>
S3_SECRET_ACCESS_KEY=<secret-key>
S3_ENDPOINT=https://s3.amazonaws.com
S3_PUBLIC_URL=https://cdn.your-domain.comProduction deployments should assume object storage is required. Generated exports are not treated as durable local-disk files.
S3_PUBLIC_URL should be configured alongside the bucket and endpoint values so the runtime can generate stable public asset URLs where required.
Background Jobs
Z8 uses BullMQ with Valkey/Redis for background processing.
Job Types
| Queue Responsibility | Purpose |
|---|---|
| Exports | Large data and payroll exports |
| Scheduled exports | Recurring report and payroll runs |
| Notifications | Deferred delivery and batching |
| Cleanup | Maintenance and retention work |
| Webhooks | Retried outbound webhook delivery |
Worker Runtime
The worker is a dedicated process that:
- processes one-off jobs
- registers and runs repeatable cron-style jobs
- shares database, queue, and storage infrastructure with the web app
- scales independently from the HTTP runtime
Canonical Time Model
Service boundaries increasingly revolve around the canonical time-record model instead of treating work entries, absences, approvals, and downstream exports as unrelated pipelines.
Operationally that means:
- time-tracking services produce or reconcile normalized work and absence data
- approval services add decision state that can travel with canonical records
- reporting and payroll services consume normalized records instead of rebuilding business meaning from raw UI events
- notification and webhook systems react to organization-scoped events rather than owning time-domain state themselves
This separation keeps domain logic in time and approval services, while infrastructure services stay focused on delivery, storage, and background execution.
Payroll Export Architecture
Payroll export orchestration sits between the time domain and infrastructure services.
The architecture has two distinct target types:
- File formatters transform normalized work periods, absences, and wage mappings into downloadable artifacts such as DATEV, Lexware, Sage, and CSV-style SuccessFactors exports.
- API exporters validate target config, push attendance and absence data into external systems such as Personio, Workday, and SuccessFactors API flows, and record per-record sync outcomes.
Supporting service responsibilities are split as follows:
- payroll export services fetch normalized source data and mappings
- queue and worker infrastructure handles async export execution
- object storage keeps generated files for later download
- sync-record persistence captures partial success and retry behavior for API-based targets
- notifications or webhooks can announce export completion without becoming part of the export domain itself
Event Bus
The event bus provides internal pub/sub messaging for decoupled event handling across the application.
Webhook System
Webhooks consume organization-scoped events and hand delivery work off to queue-backed workers. This keeps external delivery concerns isolated from product-domain services.
Rate Limiting
Rate limiting uses the same Redis-compatible infrastructure family as queue processing so auth and API traffic controls can scale with the rest of the runtime.