(NFRD)
VietGara — Multi-Tenant SaaS Platform for Auto Garage Management & Maintenance
Version 1.6 — October 9, 2026
1. Introduction
1.1. Purpose
This document specifies the non-functional requirements (NFRs) of the VietGara platform — the quality attributes the system must satisfy, complementing the Functional Requirements Document (FRD). The related architectural decisions are described in detail in the Software Architecture Document (SAD); this document focuses on measurable targets to serve as the basis for non-functional testing (performance testing, security testing, chaos testing, etc.).
1.2. Scope & Classification
Non-functional requirements are grouped into 9 quality categories, based on the ISO/IEC 25010 model and adapted for a multi-tenant SaaS context: Performance, Scalability, Availability & Reliability, Security, Maintainability, Interoperability, Usability, Observability, and Backup & Disaster Recovery.
1.3. Priority Convention
- Must have: minimum condition for go-live, non-negotiable.
- Should have: needs to be achieved within 2 releases of go-live.
- Could have: long-term goal, does not block go-live.
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-PF-01 | Synchronous API response time (P95) | Under 300ms for standard read APIs (customer, vehicle, inventory lookups), measured at the Gateway | Must have |
| NFR-PF-02 | Write API response time (P95) | Under 800ms for write operations involving inter-service gRPC calls (e.g. creating a repair order) | Must have |
| NFR-PF-03 | Owner Web and Admin Web page load time | Under 2 seconds for first load (First Contentful Paint) on an average 4G connection | Should have |
| NFR-PF-04 | Mobile app startup time | Under 3 seconds from app open to home screen (cold start) | Should have |
| NFR-PF-05 | Asynchronous event processing latency | Under 2 seconds from event publish to consumer completion under normal load | Must have |
| NFR-PF-06 | System transaction capacity | Support at least 50,000 business transactions/day at a scale of 1,000 garages without P95 degradation. Verified in Release 9.0 by a k6 run at about 50 garages with the P95 targets of NFR-PF-01, 02 and 05, and extrapolated by measured load | Must have |
3. Scalability
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-SC-01 | Horizontal scaling per service | Each service can independently increase its pod count on Kubernetes (HPA) based on CPU/queue latency, without scaling the whole system | Must have |
| NFR-SC-02 | Uninterrupted tenant growth | Adding a new tenant requires no downtime or manual configuration changes (automated via the License Service) | Must have |
| NFR-SC-03 | Linear database limits | Each service’s PostgreSQL database can support at least 1,000 tenants under the Pooled model before requiring sharding/silo | Should have |
| NFR-SC-04 | Message broker abstraction | Modules publish through the transactional outbox and consume through a subscriber interface, so the broker (Kafka, ADR-004) or the in-process dispatcher used in development can be swapped without changing business logic | Should have |
4. Availability & Reliability
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-AV-01 | System uptime | At least 99.5% in Phase 1–2, raised to 99.9% after Phase 9 (once monitoring, alerting and restore drills are in place and commercial SLAs with enterprise customers are in place) | Must have |
| NFR-AV-02 | No loss of financial transaction data | Guarantee at-least-once delivery for all settlement/invoicing-related events via the Outbox Pattern | Must have |
| NFR-AV-03 | Fault tolerance per service | A failure in a non-core service (e.g. Notification) must not interrupt a core business flow (e.g. creating a repair order) | Must have |
| NFR-AV-04 | Circuit breaker for third-party integrations | Automatically trip when an e-invoice provider or payment gateway fails repeatedly, preventing cascading failure | Should have |
| NFR-AV-05 | Controlled retries | Retry with backoff for failed asynchronous calls, with a bounded retry count to prevent infinite loops | Must have |
5. Security
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-SE-01 | Encryption in transit | All client-server and service-to-service communication uses TLS 1.2 or higher | Must have |
| NFR-SE-02 | Encryption at rest | Sensitive data (personal information, claim documents once insurance returns in Phase 17) is encrypted at the storage layer | Must have |
| NFR-SE-03 | Multi-tenant data isolation | PostgreSQL Row-Level Security enforced on 100% of tables containing tenant business data, verified by automated cross-tenant access test cases | Must have |
| NFR-SE-04 | Multi-factor authentication (MFA) | MFA is an optional second factor for every user that signs in with e-mail and password (Platform Admin, admin staff, owners, staff and customers); it is never enforced. Provided from Release 6.1 (TOTP with recovery codes; a user who turned it on gives a code at every e-mail and password sign-in; Google sign-in relies on Google’s 2-step verification); until then e-mail ownership is verified by OTP (FR-IAM-01) | Should have |
| NFR-SE-05 | No storage of payment card data | No direct storage of card numbers/payment account details in the system — all tokenized via the payment gateway (aligned with PCI-DSS SAQ-A principles) | Must have |
| NFR-SE-09 | API rate limiting | The gateway throttles requests per IP and per user: strict limits on sign-in, registration, OTP, password reset, public quote links and (from Phase 12) public booking; looser limits elsewhere; 429 with quota headers. Release 8.0 | Must have |
| NFR-SE-10 | Security headers and CORS | HSTS, content-type, frame and referrer headers, a content security policy for both web consoles and an explicit CORS policy for production hosts. Release 8.0 | Must have |
| NFR-SE-11 | Private files by default | Uploaded files are registered with an owner garage or user. Only logos and part images are public; every other kind is private and served through short-lived signed URLs. Release 5.0 | Must have |
| NFR-SE-12 | Support access to garage data | Staff of the platform read a garage’s data only through a time-boxed, read-only grant approved by the garage owner (a Platform Admin gives a reason instead of an approval). Sessions are read-only, cannot impersonate a user, show a banner, and every read is written to the audit log and shown to the owner. Releases 8.1-8.2 | Must have |
| NFR-SE-06 | Periodic security testing | Perform penetration testing at least once a year and before each new payment/invoicing feature launch | Should have |
| NFR-SE-07 | Immutable audit log | Security-relevant and financial operations are recorded in audit_log, which the application database role may only insert into (no update/delete grant). Release 1.1 records garage, staff, invitation, role, staff-group, plan and subscription changes; Billing & Settlement records settlement creation, allocation and payments (Security Architecture Section 7); receivables and invoicing entries follow with those modules | Must have |
| NFR-SE-08 | OTP protection | E-mail OTPs are 6 digits, valid 2 minutes, resendable after 30 seconds, and invalidated after 5 wrong attempts; password-reset answers do not reveal whether an e-mail is registered | Must have |
6. Maintainability
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-MT-01 | Patch deployment time | Under 30 minutes from code merge to production via the automated CI/CD pipeline (ArgoCD) | Should have |
| NFR-MT-02 | Automated test coverage | At least 70% code coverage for core business logic (Billing, Inventory, License); the backend CI gate enforces 90% on internal/ and pkg/ | Should have |
| NFR-MT-03 | Independent service deployment | A single service can be deployed without redeploying the whole system (per ADR-001, once split out of the Modular Monolith) | Must have |
| NFR-MT-04 | API version management | API changes do not break existing clients for at least 2 versions running in parallel | Should have |
| NFR-MT-05 | Infrastructure as code | All GCP environments (dev, staging, production) are created from Terraform with reviewed plans, locked state and no manual console changes. Release 9.2 | Must have |
| NFR-MT-06 | Automated test coverage of API and UI | The blackbox suite covers every P1 scenario and at least 80% of API operations (measured against the OpenAPI document); the web consoles have P1 scenarios in Playwright; every release adds its own scenarios (Definition of Done). Phase 4 | Must have |
| NFR-MT-07 | Row audit columns | Every business table has created_at, created_by, updated_at and updated_by, filled by a database trigger from the session user so that no code path can forget. Append-only tables (ledgers, audit and event logs, outbox) have the created pair only; link tables have the created pair, and the updated pair if rows can change. A schema test fails when a table has neither the columns nor an allowlist entry. Release 5.0 | Must have |
7. Interoperability
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-IO-01 | Standardized external communication | All client/partner-facing APIs follow the REST/JSON standard, with OpenAPI documentation | Must have |
| NFR-IO-02 | Independent adapters per partner | Adding a new e-invoice provider or insurer only requires writing a new adapter, without changing core logic (per SAD Sections 8–9) | Must have |
| NFR-IO-03 | Browser compatibility | Owner Web and Admin Web work correctly on the two most recent versions of Chrome, Edge, Safari, and Firefox | Must have |
| NFR-IO-04 | Mobile OS compatibility | The apps support Android 10+ and iOS 15+ | Must have |
8. Usability
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-US-01 | Interface language | 100% of the UI, error messages, e-mails and user guides are available in Vietnamese (the default) and English; the language is chosen per user | Must have |
| NFR-US-02 | Garage staff training time | Non-IT garage staff can competently perform the quote-to-settlement workflow after at most 2 hours of guided training | Should have |
| NFR-US-03 | Responsive across screen sizes | Owner Web and Admin Web are designed for 1280px and above, adapt to tablets (icon rail, full tables) and remain usable at 360px (navigation sheet, tables as cards, dialogs as bottom sheets); no horizontal page scrolling at any width; the desktop sidebar can be collapsed to an icon rail that opens over the page on hover or keyboard focus and remembers the choice | Should have |
| NFR-US-04 | Accessibility | Web: comply with WCAG 2.2 Level AA for the main user flows (4.5:1 text and 3:1 control/focus contrast in both themes, keyboard operation, focus management in dialogs, per-page titles, reduced-motion support). Mobile apps: at least WCAG 2.1 Level A until reviewed separately | Should have |
| NFR-US-05 | Light and dark themes | Every screen of the web and mobile apps is available in a light and a dark theme that follows the device setting by default; web users can choose Light, Dark or System; both themes meet NFR-US-04 contrast, verified by an automated token test | Should have |
| NFR-US-06 | Interface states | Every screen that loads data designs and builds its loading (skeleton), empty (with the next action), no-result, error (with retry) and success (toast) states | Should have |
9. Observability
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-OB-01 | Distributed tracing | 100% of requests spanning multiple services carry an end-to-end trace ID (OpenTelemetry), traceable from the Gateway to the final service. Every request (gRPC server instrumentation) and every database query gets a span; exported via OTLP once a collector is configured, otherwise still created (so logs correlate by trace ID) but not exported. “Multiple services” is still one process until a module splits out — this instruments the request path so that split carries the same trace unchanged | Must have |
| NFR-OB-02 | Automated incident alerting | Alert via on-call channels (Slack/PagerDuty) within 2 minutes when the 5xx error rate exceeds a configured threshold | Must have |
| NFR-OB-03 | Centralized logging | All service logs are centrally collected (Loki/ELK), retained for at least 30 days, and searchable by tenant_id | Must have |
| NFR-OB-04 | System monitoring dashboard | Grafana dashboards tracking latency, error rate, and throughput per service, updated in real time | Should have |
10. Backup & Disaster Recovery
| ID | Requirement | Measurable Target | Priority |
|---|
| NFR-BR-01 | Database backup frequency | Automated daily backups for all PostgreSQL databases, retaining at least the 30 most recent copies | Must have |
| NFR-BR-02 | Recovery Point Objective (RPO) | No more than 15 minutes of transaction data lost in the event of an incident (via Cloud SQL point-in-time recovery) | Must have |
| NFR-BR-03 | Recovery Time Objective (RTO) | Service restored within 4 hours of a major incident (region/AZ failure) | Must have |
| NFR-BR-04 | Disaster recovery drills | Conduct DR drills (restore from backup) at least twice a year, with a documented results report | Should have |