Standalone ARM — System Requirements Specification
1. Architectural Vision
The standalone ARM is designed as an ERP-agnostic, cloud-native billing platform that operates independently and communicates with external systems (ERP, SIS, payment gateways, parent portals) through a standardized integration layer.
1.1 Guiding Principles
| Principle |
Description |
| ERP-Agnostic |
No dependency on any specific ERP. Integrates with NetSuite, Microsoft Dynamics, and future ERPs via connectors. |
| API-First |
All functionality accessible via RESTful APIs. UI and integrations consume the same API surface. |
| Multi-Tenant |
Single deployment serves multiple institutions with full data isolation. |
| Configuration over Code |
Institution-specific behavior controlled through configuration, not custom code deployments. |
| Three-Layer Architecture |
Generic base → Configurable → Custom/Exception |
| Event-Driven |
Key business events (billing generated, payment received, payment failed) emit events consumable by external systems. |
| Cloud-Native |
Designed for cloud deployment (serverless or containerized) with auto-scaling capabilities. |
1.2 High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────────┐
│ STANDALONE ARM PLATFORM │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Admin UI │ │ Parent │ │ API │ │ Background Workers │ │
│ │ (Staff) │ │ Portal │ │ Gateway │ │ (RPS Processing, │ │
│ │ │ │ (Parents) │ │ │ │ Notifications, Files) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
│ │ │ │ │ │
│ └────────────────┴────────────────┴─────────────────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ Core API Layer │ │
│ │ (Business Logic) │ │
│ └─────────┬──────────┘ │
│ │ │
│ ┌──────────────────────────┼──────────────────────────┐ │
│ │ │ │ │
│ ┌──────▼──────┐ ┌───────────────▼──────────┐ ┌───────────▼──────────┐ │
│ │ Data Store │ │ Integration Layer │ │ Event Bus │ │
│ │ (Database) │ │ (ERP, SIS, Payment, │ │ (Webhooks, Async) │ │
│ │ │ │ Portal Connectors) │ │ │ │
│ └─────────────┘ └─────────────┬────────────┘ └──────────────────────┘ │
│ │ │
└──────────────────────────────────┼──────────────────────────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
┌──────▼──────┐ ┌────────────▼──────────┐ ┌────────▼──────────┐
│ ERP │ │ SIS / Student │ │ Payment │
│ (NetSuite, │ │ Information │ │ Gateways │
│ Dynamics) │ │ Systems │ │ (eway, Stripe, │
└─────────────┘ └───────────────────────┘ │ bank files) │
└───────────────────┘
2.1 Technology Stack
| Component |
Requirement |
Rationale |
| Backend Language |
[PLACEHOLDER — recommend Node.js/TypeScript or Python] |
To be decided based on team capabilities and ecosystem |
| API Framework |
RESTful API with OpenAPI 3.0 specification |
Standard, well-documented, tooling-rich |
| Database |
[PLACEHOLDER — recommend PostgreSQL] |
Relational data model with ACID compliance, JSON support for flexible config |
| Cache Layer |
[PLACEHOLDER — recommend Redis] |
Session management, rate limiting, frequently accessed config |
| Message Queue |
[PLACEHOLDER — recommend RabbitMQ or AWS SQS] |
Asynchronous event processing, payment processing queues |
| File Storage |
[PLACEHOLDER — recommend S3-compatible object storage] |
Generated invoices (PDF), ABA files, import/export files |
| Frontend Framework |
[PLACEHOLDER — recommend React or Vue.js] |
Admin UI and parent portal |
| Hosting |
Cloud-native (AWS, Azure, or GCP) |
Auto-scaling, managed services |
2.2 Deployment Models
| ID |
Requirement |
Priority |
| SRS-DEP-001 |
The system shall support multi-tenant SaaS deployment — single deployment serving multiple institutions |
P1 |
| SRS-DEP-002 |
The system shall support containerized deployment (Docker/Kubernetes) for portability |
P2 |
| SRS-DEP-003 |
The system shall support serverless deployment for cost optimization at low scale |
P3 |
| SRS-DEP-004 |
The system shall support on-premises or private cloud deployment for institutions requiring data sovereignty |
P4 |
| SRS-DEP-005 |
The system shall support blue-green or canary deployment strategies for zero-downtime upgrades |
P2 |
3. API Design
3.1 Core API Requirements
| ID |
Requirement |
Priority |
| SRS-API-001 |
All functionality shall be exposed via RESTful APIs following OpenAPI 3.0 specification |
P1 |
| SRS-API-002 |
APIs shall use JSON request/response format with consistent error handling |
P1 |
| SRS-API-003 |
APIs shall support pagination, filtering, sorting, and field selection on list endpoints |
P1 |
| SRS-API-004 |
APIs shall use Bearer token (JWT) authentication with configurable token expiry |
P1 |
| SRS-API-005 |
APIs shall support API versioning (URL-based: /api/v1/, /api/v2/) |
P1 |
| SRS-API-006 |
APIs shall implement rate limiting per tenant with configurable thresholds |
P1 |
| SRS-API-007 |
APIs shall support idempotent operations for payment-critical endpoints |
P1 |
| SRS-API-008 |
APIs shall return standardized error responses with error codes, messages, and correlation IDs |
P1 |
| SRS-API-009 |
The system shall provide a GraphQL endpoint as an alternative query interface |
P4 |
3.2 API Domains
| Domain |
Base Path |
Description |
| Debtors |
/api/v1/debtors |
CRUD for debtor (family) records |
| Students |
/api/v1/students |
CRUD for student records |
| Items |
/api/v1/items |
CRUD for fee and discount items |
| Billing Instructions |
/api/v1/billing-instructions |
Create, read, regenerate, delete billing instructions |
| Billing Profiles |
/api/v1/billing-profiles |
CRUD for family billing profiles |
| Transactions |
/api/v1/transactions |
Generate, read, update, void invoices and billing orders |
| Payments |
/api/v1/payments |
Record, read, refund payments |
| RPS |
/api/v1/rps |
CRUD for recurring payment schedules |
| Configurator |
/api/v1/configurator |
Configurator state management (step-by-step wizard) |
| Reports |
/api/v1/reports |
Report generation and retrieval |
| Integrations |
/api/v1/integrations |
Manage ERP/SIS connector configuration |
| Admin |
/api/v1/admin |
Tenant configuration, user management, feature flags |
| Webhooks |
/api/v1/webhooks |
Configure webhook subscriptions for events |
| Files |
/api/v1/files |
Upload/download files (CSV imports, ABA exports, PDFs) |
| ID |
Requirement |
Target |
Priority |
| SRS-PRF-001 |
API response time for single-record operations (GET, POST, PUT) |
< 200ms (p95) |
P1 |
| SRS-PRF-002 |
API response time for list/search operations |
< 500ms (p95) |
P1 |
| SRS-PRF-003 |
Billing instruction generation (automated configurator) for 1,000 students |
< 30 seconds |
P1 |
| SRS-PRF-004 |
Invoice generation (bulk — all families in a cycle) for 1,000 families |
< 5 minutes |
P1 |
| SRS-PRF-005 |
Daily RPS processing for 5,000 payment records |
< 15 minutes |
P1 |
| SRS-PRF-006 |
Concurrent users — admin UI |
50+ per tenant |
P1 |
| SRS-PRF-007 |
Concurrent users — parent portal |
500+ per tenant (during payment window) |
P1 |
| SRS-PRF-008 |
ABA file generation for 1,000 direct debit records |
< 10 seconds |
P1 |
| SRS-PRF-009 |
PDF invoice generation per invoice |
< 2 seconds |
P1 |
| SRS-PRF-010 |
Report generation for 100,000 transaction records |
< 30 seconds |
P2 |
5. Scalability Requirements
| ID |
Requirement |
Priority |
| SRS-SCL-001 |
The system shall scale horizontally — adding compute capacity without architectural changes |
P1 |
| SRS-SCL-002 |
The system shall support 100+ institutions (tenants) on a single deployment |
P1 |
| SRS-SCL-003 |
The system shall support institutions with up to 50,000 students |
P2 |
| SRS-SCL-004 |
The system shall support up to 1,000,000 transaction records per tenant per year |
P2 |
| SRS-SCL-005 |
Database queries shall be optimized with indexing strategies for the expected data volumes |
P1 |
| SRS-SCL-006 |
Background jobs (RPS processing, file generation, email sending) shall be queued and processed asynchronously |
P1 |
| SRS-SCL-007 |
The system shall support geographic distribution (multi-region deployment) |
P3 |
6. Availability & Reliability
| ID |
Requirement |
Target |
Priority |
| SRS-AVL-001 |
System uptime SLA |
99.9% (8.7 hours downtime per year) |
P1 |
| SRS-AVL-002 |
Planned maintenance window |
< 30 minutes per occurrence, off-peak hours |
P1 |
| SRS-AVL-003 |
Recovery Point Objective (RPO) — maximum data loss in disaster |
< 1 hour |
P1 |
| SRS-AVL-004 |
Recovery Time Objective (RTO) — maximum time to restore service |
< 4 hours |
P1 |
| SRS-AVL-005 |
Database backups |
Automated daily, point-in-time recovery for 30 days |
P1 |
| SRS-AVL-006 |
The system shall implement circuit breakers for external service calls (payment gateways, ERP) |
|
P1 |
| SRS-AVL-007 |
The system shall gracefully degrade when external services are unavailable (queue payments for retry, show cached data) |
|
P1 |
7. Logging, Monitoring & Observability
| ID |
Requirement |
Priority |
| SRS-MON-001 |
The system shall implement structured logging (JSON format) with correlation IDs across all services |
P1 |
| SRS-MON-002 |
The system shall publish health check endpoints (/health, /ready) for load balancer and orchestrator use |
P1 |
| SRS-MON-003 |
The system shall emit metrics for: API latency, error rates, active RPS processing, payment success/failure rates |
P1 |
| SRS-MON-004 |
The system shall support integration with standard monitoring tools (Prometheus, Grafana, Datadog, or CloudWatch) |
P2 |
| SRS-MON-005 |
The system shall implement distributed tracing for request flow across services |
P2 |
| SRS-MON-006 |
The system shall alert on: payment processing failures, API error rate spikes, queue backlogs, certificate expiry |
P1 |
| SRS-MON-007 |
All payment-related operations shall produce audit logs with full request/response details (excluding PII/card data) |
P1 |
8. Data Architecture
8.1 Data Isolation
| ID |
Requirement |
Priority |
| SRS-DAT-001 |
Each tenant's data shall be fully isolated — no cross-tenant data leakage |
P1 |
| SRS-DAT-002 |
Multi-tenancy shall be implemented via [PLACEHOLDER — schema-per-tenant or row-level isolation with tenant_id] |
P1 |
| SRS-DAT-003 |
Tenant identification shall be embedded in API authentication tokens — no manual tenant switching |
P1 |
8.2 Data Migration
| ID |
Requirement |
Priority |
| SRS-MIG-001 |
The system shall support importing existing data from the current NetSuite-based ARM (debtors, students, items, billing instructions, transaction history) |
P1 |
| SRS-MIG-002 |
The system shall provide migration scripts/tools for each existing client (Saint Edwards, Al Faisal, Pymble) |
P1 |
| SRS-MIG-003 |
Migration shall preserve historical transaction and payment data for audit trail continuity |
P1 |
| SRS-MIG-004 |
The system shall support parallel running (old and new system simultaneously) during migration period |
P2 |
9. Configuration Management
9.1 Tenant Configuration
| ID |
Requirement |
Priority |
| SRS-CFG-001 |
Each tenant shall have an isolated configuration store covering: institution details, billing settings, payment options, integration credentials, feature flags |
P1 |
| SRS-CFG-002 |
Configuration changes shall be versioned and auditable (who changed what, when) |
P1 |
| SRS-CFG-003 |
Configuration shall support inheritance: platform defaults → tenant overrides |
P2 |
| SRS-CFG-004 |
Feature flags shall control availability of optional features per tenant (e.g., building levy, annual discount, B Pay) |
P2 |
| SRS-CFG-005 |
Configuration changes shall take effect without system restart (hot reload) |
P2 |
9.2 Version Management
| ID |
Requirement |
Priority |
| SRS-VER-001 |
The system shall maintain a single codebase — no per-client code branches |
P1 |
| SRS-VER-002 |
All client variations shall be handled through configuration and feature flags, not code forks |
P1 |
| SRS-VER-003 |
Deployment pipeline: single source repository → CI/CD → staging → production (all tenants) |
P1 |
| SRS-VER-004 |
The system shall support semantic versioning (MAJOR.MINOR.PATCH) with documented changelogs |
P2 |
10. Background Processing
| ID |
Requirement |
Priority |
| SRS-BKG-001 |
The system shall support scheduled jobs (e.g., daily RPS processing, automated reminders) with configurable schedules per tenant |
P1 |
| SRS-BKG-002 |
Background jobs shall be idempotent — safe to retry without side effects |
P1 |
| SRS-BKG-003 |
The system shall implement job queuing with visibility into job status (pending, running, completed, failed) |
P1 |
| SRS-BKG-004 |
Failed jobs shall be retried with configurable retry policies (count, interval, exponential backoff) |
P1 |
| SRS-BKG-005 |
The system shall support dead-letter queues for jobs that fail after all retries |
P2 |
| SRS-BKG-006 |
Background jobs shall respect tenant isolation — jobs for one tenant cannot affect another |
P1 |
11. Testing Requirements
| ID |
Requirement |
Priority |
| SRS-TST-001 |
The system shall maintain unit test coverage of ≥ 80% for core business logic |
P1 |
| SRS-TST-002 |
The system shall have integration tests for all API endpoints |
P1 |
| SRS-TST-003 |
The system shall have end-to-end tests for critical billing and payment workflows |
P1 |
| SRS-TST-004 |
The system shall support a sandbox/test mode for payment gateway integration (no real charges) |
P1 |
| SRS-TST-005 |
The system shall support tenant-specific test environments for UAT |
P2 |
| SRS-TST-006 |
Performance/load testing shall validate the targets defined in Section 4 |
P2 |
Appendix: Technology Decision Log
| Decision |
Options Considered |
Selected |
Rationale |
Status |
| Backend language |
Node.js/TypeScript, Python, Go, Java |
[PLACEHOLDER] |
[PLACEHOLDER] |
Open |
| Database |
PostgreSQL, MySQL, MongoDB |
[PLACEHOLDER] |
[PLACEHOLDER] |
Open |
| Cloud provider |
AWS, Azure, GCP |
[PLACEHOLDER] |
[PLACEHOLDER] |
Open |
| API style |
REST only, REST + GraphQL |
[PLACEHOLDER] |
[PLACEHOLDER] |
Open |
| Multi-tenancy model |
Schema-per-tenant, Row-level isolation, Database-per-tenant |
[PLACEHOLDER] |
[PLACEHOLDER] |
Open |
| Containerization |
Docker + Kubernetes, Serverless (Lambda/Cloud Functions), Hybrid |
[PLACEHOLDER] |
[PLACEHOLDER] |
Open |
| Build inside NetSuite or external |
NetSuite Suitelet (rebuild), External standalone app |
External standalone app |
Avoid NS dependency & limitations |
Decided |