Technical Specifications & System Requirements

1 Platform overview

Ritzy One is a browser-based ERP suite, a re-platform of the long-running Ritzy desktop application. It is a single Node.js API process talking to a PostgreSQL database, with a React single-page application for the desk and a family of installable phone apps (PWAs) for the field.

2 Technology stack

Deliberate exclusions

• No native npm modules. Pure-JavaScript equivalents are used throughout, so an install never needs a build toolchain.
• No ORM. SQL is written directly against PostgreSQL, which keeps the ported business logic comparable line by line with the desktop application it replaces — the posting engines were verified to produce identical results.
• No business logic in the database. The desktop application's stored procedures and triggers (posting, ledger balances, stock costing) were ported to TypeScript services with regression tests; the database holds data, constraints and a few read-only SQL functions.
• No message broker, no Redis, no separate job runner. Scheduled work — alert digests, licence heartbeat, support-reply sweeps — runs as timers inside the API process.

3 Architecture

There is exactly one API process. Every front end — the desk application and all twelve phone apps — is a separate static bundle that nginx publishes on the one address — the desk application at /, each phone app under its own path (/track/, /crm/ …) — proxying /api/ back to that single process. One host name and one certificate cover them all. Adding a phone app adds a static site, not a service.

Packages

State and scaling

The API keeps no session state in memory — authentication is a signed token and session records live in the database — so it can be restarted without logging anyone out. Scaling is nonetheless vertical by design: the bottleneck in this workload is database I/O rather than Node CPU, and one PostgreSQL server per customer is ample. The multi-customer answer is one instance per customer, not a shared cluster.

4 Data layer & database design

One database per install

Every company in an install lives in one PostgreSQL database. The companies table is the company registry and drives the login page's company dropdown. Every business table starts with company_id, and Row-Level Security limits each connection to the company it was opened for; consolidated group reports switch it to read every company. Attachments and scanned documents are held in the same database rather than in a separate file.

Schema and upgrades

On start the application creates its own database, schema, application login and upgrades from PG_URL, so there is no separate database-setup step. The schema is a baseline; later changes are numbered SQL migrations applied in order, each in its own transaction and recorded with a checksum in schema_migrations. The same runner upgrades an existing install when a new build is deployed, so the database and the application version stay in lockstep. A new company is seeded with its chart of accounts and defaults in one transaction, and adding a module is a data change, not a schema change.

Business logic in TypeScript

The desktop application kept much of its logic in Firebird stored procedures and triggers. In Ritzy One that logic — voucher posting, ledger and party balances, bill allocation, inventory costing and stock posting — runs in TypeScript services, inside the same database transaction as the document it posts, and is covered by regression tests against the desktop application's results. Only a few read-only queries remain as SQL functions.

Engineering notes

• Test as the application login, never as the superuser: a superuser bypasses Row-Level Security and would see every company.
• PostgreSQL is I/O- and latency-sensitive. Keep the data directory on local SSD/NVMe, never on a network share.
• Keep the database local to the API server (port 5432 is never published); if it is on a separate host, use TLS and a private network.

Why PostgreSQL

PostgreSQL is open-source with no per-seat or per-core licence cost, runs identically on Windows, Linux and in containers, and is supported by every cloud provider as a managed service. Exact numeric types, real foreign keys and Row-Level Security give the data stronger guarantees than the desktop schema had, and standard tools — pg_dump, pg_restore, streaming replication — cover backup and standby.

Moving from the Ritzy desktop application

Desktop customers' data is in Firebird .FDB files. A one-off import converts each company into the PostgreSQL database: from the administration console (Import from Firebird, as a new company or replacing an existing one) or with npm run pg:convert. Problem rows are logged rather than silently dropped. This import is the only part of Ritzy One that reads Firebird; the running server does not need Firebird installed.

5 API design

• REST over JSON, everything under /api, across 67 registered route modules (/api/auth, /api/accounts-tran, /api/reports, /api/realestate, /api/payroll and so on).
• Bearer-token authentication on every route except the first-run setup router and the version endpoint.
• Four middleware layers ahead of the handlers: authentication, module entitlement, per-form rights, and a central error handler that turns typed application errors into proper HTTP status codes.
• Reporting endpoints return { rows, totals } — a fixed contract the grid components rely on.
• GET /api/version is unauthenticated and reports the running build marker. It is the canonical way to confirm which build is live after a deployment.

Module gating

A gated module must be both installed in the company database and entitled by the subscription licence before its routes answer, and the check is on the server rather than only in the menu. It deliberately fails open if the entitlement lookup itself errors, so an infrastructure problem can never lock a paying customer out of their own data.

6 Security model

7 Licensing & entitlement

Licensing is a signed-token scheme. A licence is issued by the vendor-side Ritzy License Server, signed with a private key, and verified locally against the matching public key — so entitlement checks keep working with no internet connection.

• Seats are per device, not per named user: each browser registers a device token and counts against the licensed concurrent maximum. The phone apps are seat-exempt.
• Modules are entitled individually — the ten add-on modules each carry their own entitlement; the Accounts core is always included.
• A heartbeat (optional, for subscription customers) periodically confirms the licence is current and picks up renewals, plan changes and revocations.
• Companies are registered with the License Server, since billing is per company database. Creating a company (first-run wizard, New Company, DBA Console) sends its code, name and setup details — contact email and telephone, city, country, base currency, modules and the server's host name — and saving Settings → Company re-sends the stored details so the vendor's copy stays current. The License Server keeps these details per company (a blank never clears a stored value) and re-creates the customer if it is missing. Registration is best-effort: it runs after the save, and an unreachable server never blocks creating or saving a company.
• With licensing disabled, entitlement checks are inert — a perpetual on-premise install is never locked by the vendor. Company registration still runs; block outbound HTTPS to the License Server if even that must not leave the site.

8 Server requirements

8.1 Supported platforms

8.2 Hardware

Component footprint on a lean install: idle Linux around 0.5–1 GB, the Node API 0.3–0.5 GB, and PostgreSQL with a useful cache 1–2 GB. A 3 GB tenant VM is comfortable and 4 GB generous — which is why a 32 GB host runs roughly six to eight fully isolated tenant VMs with headroom.

8.3 Software prerequisites

9 Client requirements

10 Ports & network

The installer opens these inbound TCP rules. For an internet-facing deployment, publish 443 only and put nginx in front of everything.

Outbound traffic is entirely optional and each item can be omitted: the licence heartbeat, company registration and the support assistant to the Ritzy License Server over HTTPS, SMTP for sending documents, the tax authority's endpoint where e-invoicing is in use, and the browser push services.

11 Deployment & updates

11.1 Traditional install

Deployment is a compiled bundle, not a source checkout. The build produces a deployment zip; extracting it over the install folder and restarting the process manager is the whole update. The installer installs PostgreSQL 18 when it is missing, sets up dependencies, writes the API's .env with the two database logins and a freshly generated secret, schedules a nightly pg_dump, registers the PM2 process and the Windows services, configures nginx and opens the firewall.

• First install: install.ps1 on Windows or install-linux.sh on Linux — it prompts once for the base folder (and, when PostgreSQL was already installed, its superuser password).
• Application-only update: install-app.ps1 — no prompts, no .env changes; the app applies any database upgrades itself on start. Or simply extract the zip and restart the service.
• An existing .env is never overwritten by a re-install.
• Verification: GET /api/version returns the live build marker.

11.2 Docker

For a new standalone install the container bundle is the simplest path: two services, postgres (PostgreSQL 18) and app, each with its own volume. Updates are pull then up -d. A Ritzy desktop customer, whose data is in Firebird, is moved onto a stack with docker/migrate/: the companies are converted on the Windows side by the importer and restored into the stack as a pg_dump.

11.3 First run

A brand-new server has no database and no company registry, so there is nothing to log in to yet. The install therefore starts in first-run mode: a setup wizard — reachable only while zero companies exist, and additionally protected by the support password — creates the first company in the database (which the app has already created, with its schema and upgrades) and seeds the chart of accounts and defaults. Once a company exists the wizard is gone for good.

12 Backup & recovery

• Use pg_dump. It reads one consistent snapshot of the running database. The Windows installer schedules it nightly (pg_dump -Fc, 14 days kept under <RITZY_ROOT>\Backups\PostgreSQL); the Docker bundle's backup-stacks.sh does the same per stack. One company is backed up and restored from the administration console (.pgbk: download to a PC, upload, restore).
• Do not rely on VM snapshots or hypervisor checkpoints of a running database server — they are not database-consistent and are no substitute for a backup.
• Copy backups offsite, ideally to a different provider or region.
• Recovery is a pg_restore plus a service restart. The application holds no state of its own outside the database and its .env — keep a copy of that file with the backups.

13 Integrations & external services

14 AI capabilities

The AI features use Anthropic's Claude models and are strictly opt-in. They fall into two groups with different privacy profiles.

• Data features — paste-to-form extraction on around twenty-five screens, CSV column mapping, visiting-card capture, lead capture and follow-up drafting, and the management briefing — require an API key in the install's own .env. The key is the customer's, requests go straight from their server to the model API, and they carry only the text or image being processed. With no key configured these features report that AI is not set up and everything else carries on unchanged.
• The product support assistant needs no key at the customer's site. The question is forwarded over the install's licence token to the Ritzy License Server, where the model key, the knowledge base and the manual catalogue live. It reads nothing from the company database.

The management briefing is deliberately constrained: the model chooses which figures to show, but every number is computed by the server from the database. The model never produces a figure itself.

15 Sizing, performance & limits

16 Configuration reference

Everything environment-specific lives in one file, packages\api\.env, which is why the same build runs unchanged on Windows, on Linux and in a container. The keys that matter most:

# Paths and database
RITZY_ROOT=C:\Ritzy Solutions      # the BASE folder -- not ...\Ritzy
PG_URL=postgres://postgres:********@localhost:5432/ritzy      # superuser: makes the database ready on start
PG_APP_URL=postgres://ritzy_app:********@localhost:5432/ritzy # the login every request uses
RITZY_BACKUP_DIR=

# API
PORT=3001
JWT_SECRET=<generated at install>
JWT_EXPIRES_IN=8h
JWT_REFRESH_EXPIRES_IN=7d
CORS_ORIGIN=https://erp.example.com

# Optional features
ANTHROPIC_API_KEY=                 # AI data features
VAPID_PUBLIC_KEY=                  # web push
VAPID_PRIVATE_KEY=
VAPID_SUBJECT=
SOFFICE_PATH=                      # LibreOffice, for PDF rendering
FATOORA_HOME=                      # ZATCA -- Saudi installs only

# Licensing (inert unless enabled)
LICENSING_ENABLED=false
LICENSE_PUBLIC_KEY=
LICENSE_HEARTBEAT_URL=