Non-Functional Requirements - Football Field Booking System

Version: 1.0 Last Updated: 2026-01-13 Owner: Tech Lead Scope: API Gateway + microservices (user-service, field-service, booking-service, payment-service, notification-service) + infrastructure (PostgreSQL, MongoDB, Redis, Kafka, Keycloak, Signoz)

Purpose & Applicability

This document defines non-functional requirements (NFRs) for the Football Field Booking Platform backend. These requirements apply to:

API Gateway (port 3000) as the primary ingress.
User Service (3001), Field Service (3002), Booking Service (3003), Payment Service (3004), Notification Service (3005).
Supporting infrastructure: PostgreSQL 15 (multi-instance), MongoDB 7, Redis 7, Kafka, Keycloak 24, OpenTelemetry + Signoz.

Assumptions

Backend is an NX monorepo with services implemented in NestJS 10 and TypeScript 5.
Authentication/authorization uses Keycloak (OIDC), and services validate tokens issued by Keycloak.
Production deployment targets Kubernetes, while local development uses Docker Compose.

Definitions

SLA: service-level agreement (externally visible uptime commitments).
SLO: service-level objective (internal targets).
p95 / p99: 95th/99th percentile latency over a rolling window.
RTO/RPO: recovery time objective / recovery point objective.
RED metrics: Rate, Errors, Duration.
USE metrics: Utilization, Saturation, Errors.

NFR-1: Performance Requirements

NFR-1.1: Response Time (Latency)

Priority: P0

Requirements

API Gateway request latency (p95): < 200ms
API Gateway request latency (p99): < 500ms
Inter-service calls latency (p95): < 150ms
Database query time (p95): < 50ms
Search endpoints (e.g., field search) (p95): < 200ms
Booking creation (excluding payment gateway external processing): < 1s
Payment processing (excluding third-party gateway): < 3s
Notification enqueue (Kafka publish or BullMQ enqueue): < 150ms

Measurement

Signoz distributed tracing with OpenTelemetry instrumentation on API Gateway and all services.

Acceptance Criteria

Latency SLO reports show compliance for 30-day rolling window, excluding incident postmortem windows.

NFR-1.2: Throughput

Priority: P0

Requirements

Support 1,000 concurrent users (MVP target).
Handle 100 RPS per service under normal load.
Booking creation sustained throughput: 50 RPS.
Payment intent creation sustained throughput: 20 RPS.

Measurement

Load testing with k6.
Track saturation via CPU, memory, DB connection pool, Kafka lag.

NFR-1.3: Tail Latency Targets by Operation

Priority: P1

Operation	Target (p95)	Notes
User login (OIDC token exchange)	< 500ms	Depends on Keycloak and network
Get current profile	< 200ms	user-service
Field search	< 200ms	field-service + caches
Field details	< 200ms	field-service
Availability lookup	< 250ms	booking-service + caches
Booking create (pre-payment)	< 1s	includes lock/validation
Payment status query	< 300ms	payment-service
Email enqueue	< 200ms	notification-service
Email delivered	< 1 min	external provider dependent

NFR-1.4: Resource Utilization

Priority: P1

Requirements

CPU usage: < 70% average, < 90% peak (per service).
Memory usage: < 80% average.
PostgreSQL connection pools: < 80% of max.
Redis memory: < 70% of allocated memory.

Measurement

Signoz + container metrics + PostgreSQL exporter metrics.

NFR-2: Scalability Requirements

NFR-2.1: Horizontal Scalability

Priority: P0

Requirements

Services must be stateless (no session state stored in memory).
Support horizontal scaling via multiple replicas behind load balancing.
Use Redis for shared cache and distributed locks (booking conflict prevention).
Use Kafka for asynchronous communication; avoid synchronous fan-out in hot paths.
Use DB connection pooling and backpressure on saturation.

Target Scale (Phase 2)

10,000 concurrent users
100,000 bookings/day
100,000 fields in catalog (or more, depending on geography)

NFR-2.2: Data Growth & Retention

Priority: P1

Requirements

User records: 1M
Bookings: 10M historical (2+ years)
Payments: 10M (1:1 with bookings that require payment)
Logs/traces: hot retention 7–30 days, cold retention 90 days–1 year based on storage cost.

Retention Policy (default)

Bookings: indefinite (or at least 2 years for business and dispute requirements)
Payment records: >= 2 years (or as required by local regulations)
Audit logs: >= 1 year
Traces: 7–14 days hot storage

NFR-2.3: Auto-scaling (Kubernetes)

Priority: P1

Requirements

Use Horizontal Pod Autoscaler (HPA) based on:
CPU > 70%
Memory > 80%
Custom metrics (RPS, latency, Kafka lag) where available
Scale-out time: < 2 minutes
Scale-in time: < 5 minutes

NFR-3: Reliability & Availability Requirements

NFR-3.1: Availability (SLA/SLO)

Priority: P0

System SLA (MVP)

Overall system uptime: 99.5% (≈ 43.8 hours downtime/year)

Service SLO Targets

Component	Availability SLO
API Gateway	99.9%
Booking Service	99.9%
Payment Service	99.9%
User/Field/Notification Services	99.5%

Notes

Booking/payment are business-critical and must be prioritized.

NFR-3.2: Fault Tolerance & Dependency Failure Handling

Priority: P0

Requirements

Implement timeouts for all outbound requests and DB queries.
Implement retries with exponential backoff + jitter for transient failures.
Implement circuit breakers for downstream service calls (especially payment gateways, notification providers).
Avoid cascading failures:
Rate-limit and shed load under overload.
Use bulkheads (separate pools/queues) for critical operations.
Graceful degradation examples:
If notification provider down → queue notifications and retry.
If Redis down → fall back to DB constraints and accept higher latency (booking flow may be limited).
If Kafka down → write events to outbox table (optional Phase 2) and replay when available.

NFR-3.3: Disaster Recovery

Priority: P1

Requirements

PostgreSQL backups:
Full backup daily
Incremental backup hourly (if tooling supports)
Backup retention: 30 days
RTO: < 4 hours
RPO: < 1 hour
Backup verification: weekly restore test in staging environment

NFR-3.4: Data Integrity & Consistency

Priority: P0

Requirements

Prevent double bookings by enforcing:
Database constraints (time overlap constraints where possible), and/or
Redis distributed locks with short TTL during booking creation, and
Transactional logic in booking-service.
Payment operations must be idempotent (idempotency key based on bookingId + provider reference).
All writes must validate:
At API layer (DTO validation)
At database layer (constraints, foreign keys, checks)
Use UTC timestamps for all persisted time values.

NFR-4: Security Requirements (Non-Functional)

NFR-4.1: Authentication

Priority: P0

Requirements

All endpoints except /health require authentication.
Use Keycloak OIDC; API Gateway validates access tokens and propagates identity claims.
Access token TTL: 15 minutes
Refresh token TTL: 7 days

NFR-4.2: Authorization

Priority: P0

Requirements

Role-based access control (RBAC): ADMIN, OWNER, CUSTOMER.
Resource-level authorization:
Only booking owner can cancel own bookings.
Only field owner can update their own fields.
Admin can approve fields and manage users.

NFR-4.3: Data Protection

Priority: P0

Requirements

TLS for all inter-service and external communications in production.
Sensitive configuration stored in secrets manager (Kubernetes secrets / Vault) not in repo.
Do not store full card details (PCI-DSS). Store only provider references.
Password storage:
If local auth exists: bcrypt with cost factor >= 12 (or Argon2 recommended).
If fully Keycloak-managed: no passwords stored in services DB.

NFR-4.4: API Security

Priority: P0

Requirements

Rate limiting:
Default: 100 req/min/user
Auth endpoints: 5 req/min
Payment endpoints: 10 req/min
Request validation: strict DTO validation, content-type enforcement.
CORS policy configured at gateway.
Security headers enabled at gateway.
Protect webhooks:
Stripe/VNPay webhook signature verification
IP allowlist where feasible

NFR-5: Observability, Monitoring & Alerting

NFR-5.1: Tracing & Correlation

Priority: P0

Requirements

Every inbound request must have a trace ID and request ID.
Propagate trace context across:
API Gateway → services
service → service
service → Kafka message headers
All logs must include:
traceId, requestId, userId (if available), service name, operation, error code

NFR-5.2: Metrics

Priority: P0

Minimum Metrics

RED metrics per endpoint: request rate, error rate, duration (p50/p95/p99)
USE metrics per service: CPU, memory, GC pauses, event loop lag
Kafka consumer lag and message publish failures
DB pool usage and slow query counts
Redis latency, memory usage, key eviction counts

NFR-5.3: Alerting

Priority: P1

Alert Policies

Error rate > 1% for 5 minutes (P1)
p95 latency breaches for 10 minutes (P1)
Kafka consumer lag > threshold (P1)
DB connections > 80% for 10 minutes (P1)
Payment failures spike (P0/P1 depending on severity)

NFR-6: Maintainability, Quality & Testability

NFR-6.1: Code Quality

Priority: P1

Requirements

Code coverage: >= 80% (unit + integration combined; per critical modules)
Linting and formatting enforced via CI
Conventional commits + PR reviews required
Shared libraries used for common concerns (messaging, cache, shared DTOs/enums)

NFR-6.2: Test Strategy

Priority: P1

Requirements

Unit tests for services and domain logic.
Integration tests for controllers and DB interactions.
E2E tests for critical flows:
Search field → create booking → create payment → confirm payment → notification.
Performance tests (k6) for hot endpoints.

NFR-7: Compatibility & Operability

NFR-7.1: Environment Parity

Priority: P0

Requirements

Dev, staging, production should be as similar as possible in:
config structure
secrets strategy
external dependencies (Kafka, Redis, DB)

NFR-7.2: Deployment & Rollback

Priority: P0

Requirements

Rolling deployments with health checks.
Rollback capability < 5 minutes.
Zero-downtime upgrades for stateless services.

Summary Table

Category	Requirements	P0	P1
Performance	4	2	2
Scalability	3	1	2
Reliability	4	3	1
Security	4	4	0
Observability	3	2	1
Maintainability	2	0	2
Operability	2	2	0
TOTAL	22	14	8

Document Version: 1.0 Last Updated: 2026-01-13 Owner: Tech Lead