Non‐Functional Requirements - CodingF0X/Hogwarts-Library-MSA GitHub Wiki

1- Security:

  1. Transport Security
  • Internode communication (between microservices and RabbitMQ) should be on a trusted private network (e.g., Docker network).
  1. Authentication & Authorization
  • JWT must be signed.
  • Access tokens are short-lived (e.g., 15 minutes); refresh tokens expire in 7 days (configurable).
  • All inbound requests are checked with JwtAuthGuard
  • Sensitive endpoints (creating/deleting books, revoking users) are restricted to the "librarian" or "admin" role via RBAC.

 3. Data Encryption

  • Passwords and TOTP secrets must be stored as securely hashed values.
  • If storing PII (addresses, phone numbers), ensure the database encryption at rest is enabled.(Low)
  • If using S3 or a file store for avatars, enforce S3 bucket policies so that images are not publicly accessible except via signed URLs.(Low)

 4. Audit & Logging

  • All critical security events (login success/failure, password reset, MFA toggles, role changes) must be logged to the audit_logs table.
  • logs contain enough context (timestamp, userId, IP address, user agent) to diagnose security incidents (Low).

2- Performance & Scalability

  1. Caching
  • Cache frequently read data (e.g., book metadata) using an in-memory cache (e.g., Redis) or an HTTP caching layer in the API Gateway.
  • Cache responses for GET /books/:id for a short TTL (e.g., 60 seconds) to reduce pressure on Catalog + Inventory.

3- Reliability & Availability

  1. High Availability
  • Each service should automatically restart on failure (Docker's restart: always or Kubernetes liveness probes).
  • database replicas (e.g., a secondary PostgreSQL instance)

 2. Fault Tolerance

  • retry logic for RPC calls: if a downstream service is temporarily unavailable, retry 3 times with exponential back-off.
  • Gracefully handle missing services: if the Inventory Service is down, loan requests return a clear "Service Unavailable" rather than crashing.

 3. Data Consistency

  • Saga/Choreography pattern (event-driven) for distributed transactions (e.g., when checking out a book, first lock the copy in inventory, then write the loan record).
  • Ensure idempotency in event handlers (e.g., if loan.created is received twice, don't double-create the record).

4- Maintainability & Extensibility

  • Modular Code Organization using DDD and SOLID style

5- Usability & User Experience

  1. Consistent API Design
    RESTful conventions (HTTP verbs, status codes)
    eturn errors in a consistent JSON shape:
    {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "Invalid credentials"
    }
  2. Clear Error Messages
  • Avoid leaking internal details (e.g. stack traces).
  • user-friendly messages (e.g. "Your password is incorrect" rather than "Error code 401A").

 3. Interactive Documentation

  • Enable Swagger (via @nestjs/swagger) so any developer can navigate to GET /docs in each service and try out endpoints.
  • Keep DTOs annotated with JSDoc or @ApiProperty so the OpenAPI spec is accurate.