itworx-knowledge-hub-Public/docs/05-non-functional-requirements.md

Non-functional requirements

Reliability and integrity

• Published content, revisions, audit and outbox changes are transactionally consistent.
• A failed request cannot leave a partially published page.
• Attachment references cannot point to missing committed blobs without a detectable integrity violation.
• Imports are idempotent and reversible by import ID.
• Backups are considered successful only after manifest and hash validation.
• Restore is tested into a clean target.
• Database migrations are forward-tested from every supported released schema.

Performance targets

Targets are measured on a modest x86-64 Unraid host with SSD-backed PostgreSQL after warm startup, using the documented synthetic dataset.

Operation	Dataset	Target
Application shell first authenticated response	normal	p95 < 1.0 s
Page API read	100,000 pages	p95 < 300 ms
Search first page	100,000 pages / 1,000,000 revisions	p95 < 750 ms
Lazy tree child load	10,000-node collection	p95 < 300 ms
Page publish without attachment	normal	p95 < 500 ms
Project context bundle	10,000 project-linked records total	p95 < 800 ms
API health liveness	normal	p95 < 100 ms

The UI should remain responsive under a 4× CPU slowdown profile. Performance regressions must be measured; arbitrary timeout increases are not fixes.

Capacity targets

Initial validated design target:

• 100,000 current pages;
• 1,000,000 page revisions;
• 10,000 projects;
• 1,000,000 project updates/relations combined;
• 100,000 attachment references;
• 500 GiB attachment storage, constrained by host capacity;
• 20 concurrent interactive sessions;
• 10 service accounts.

These are validation ceilings, not expected normal usage.

Availability

• Single-host design; no false high-availability claim.
• Graceful shutdown and database connection draining.
• Readiness becomes false when mandatory dependencies are unavailable.
• Liveness remains independent of transient PostgreSQL unavailability.
• Background jobs use leases/idempotency to recover after restart.
• No required outbound internet dependency for normal operation.

Security

• Private by default.
• Least privilege.
• Secure session cookies and CSRF protection.
• Strong password policy and lockout.
• Scoped, revocable service tokens.
• Authorization at use-case/query boundaries.
• Safe Markdown and attachment handling.
• Security headers.
• Sensitive-data log redaction.
• Non-root production container.
• Dependency, secret and container scans in release gate.
• Threat model maintained in docs/26-threat-model.md.

Accessibility

• WCAG 2.2 AA target for implemented flows.
• Keyboard-complete operation.
• Visible focus.
• Semantic landmarks and headings.
• Dialog focus trap/return.
• Sufficient contrast.
• 200% zoom and narrow viewport without loss of function.
• Reduced-motion support.
• Automated axe coverage plus manual keyboard/screen-reader spot checks.

Compatibility

Supported clients for release validation:

• current stable Chromium-based desktop browser;
• current stable Firefox desktop;
• representative Android Chromium viewport;
• touch and keyboard interaction.

The server supports Linux containers on x86-64. ARM64 support is desirable when the dependency chain and CI can verify it.

Maintainability

• Modular-monolith dependency rules enforced by tests.
• Strict nullability and TypeScript.
• Warnings as errors.
• Versioned API.
• Documented migrations and ADRs.
• One high-level verification command.
• No hidden manual production build steps.
• Current-state and evidence documents updated per milestone.

Observability

• Structured JSON logs in production.
• Correlation/request ID.
• Health status and bounded system metrics.
• Audit trail separate from diagnostic logs.
• No user page bodies or attachment contents in normal logs.
• Background-job state visible to administrators.

Localization and timezone

• Primary UI locale: nl-BE.
• Store instants in UTC.
• Render dates/times in the configured installation timezone, default Europe/Brussels.
• Store locale-independent status values and translate in the UI.