[DOSSIER 01] · NOREOS CORE · 2024 – PRESENT

NoreOS — Offline-First Retail Operating System

"A retail store must never lose a customer transaction, corrupt inventory state, or stall register checkout when the internet drops."

System Metric	Engineering Scope	Architecture Layer
Role & Ownership	Founder & Solo System Architect	End-to-end design & delivery
Core Stack	TypeScript, Flutter, React, PostgreSQL, Docker, SQLite/IndexedDB	Edge client + Cloud core
Verification Gate	80% mandatory coverage gate (535 unit tests + 396 E2E flows)	Deterministic CI gate
Data Isolation	Schema-per-tenant physical isolation in PostgreSQL	Zero shared rows

01 // Context: Intermittent Connectivity at Retail Edge

SEC. 01

In developing and emerging retail markets across South Asia and the Middle East, high-speed broadband is an intermittent convenience rather than a stable utility. Merchant terminals regularly face sudden fiber cuts, local power brownouts, and volatile 4G cellular dongles during peak evening trade.

Traditional software-as-a-service (SaaS) point-of-sale architectures assume uninterrupted HTTP request-response cycles. When the WAN partitions, cloud-dependent cash registers freeze: barcode scanners fail to look up pricing, carts stall halfway through cash payment, paper receipts cannot print, and inventory counts drift into unreconcilable negatives.

NoreOS was engineered on a strict invariant: the register counter is sovereign. Every cash transaction, barcode lookup, invoice generation, discount calculation, and shift turnover must execute locally with zero latency, regardless of WAN state.

Domain Invariant: The physical customer standing at the counter cannot be held hostage by a cloud timeout. If the database server in Frankfurt is unreachable, the terminal in Islamabad must still complete the sale in under 150 milliseconds.

02 // Constraints: Physical Isolation & Multi-Locale Diversity

SEC. 02

Building an offline-capable system for multi-tenant retail imposes strict architectural boundaries that rule out conventional web patterns:

Constraint	Technical Boundary	Reasoning
Schema-per-Tenant	Strict separate PostgreSQL schema per retail merchant; zero shared tables.	Eliminates row-level leak risk and enables per-merchant point-in-time restores.
Zero WAN Synchrony	All register mutations commit to local durable disk storage before any network attempt.	Allows infinite offline duration without memory exhaustion.
Multi-Vertical Engine	One core supporting pharmacy batch/expiry dates, apparel matrix sizing, and grocery scales.	Avoids bespoke code forks across merchant verticals.
Script-Correct RTL	10 locales including bidirectional RTL typography for Arabic and Urdu.	Essential for cashier adoption in regional retail corridors.

03 // Decisions: Append-Only Mutation Log & Reconciliation Protocol

SEC. 03

Rather than attempting distributed two-phase commit or naive table replication, NoreOS models all register state transitions as an append-only mutation log. When a cashier adds an item, applies a voucher, or closes an invoice, the event is stamped with a deterministic UUID and committed locally to durable storage.

FIGURE 1.0 // BIDIRECTIONAL MUTATION LOG & SCHEMA ROUTING PROTOCOL: CHUNKED BATCH SYNC

Figure 1.0: NoreOS edge mutation ingestion and schema-routed reconciliation. Transactions commit first to local append-only storage before syncing over HTTP batches. The central ingestion layer routes mutations to merchant-specific PostgreSQL schemas without row contention.

Key architectural decisions made during core implementation:

Compensating transactions over distributed locks: If an item sells concurrently on two registers during an offline partition, both sales are honored, receipts are issued, and a compensating stock reconciliation audit entry is registered upon synchronization.
Deterministic UUID v7 keys: Primary keys encode microsecond timestamp ordering alongside device entropy, enabling causal sorting without distributed time synchronization.
Explicit tombstone deletions: Deletions are never physical removals; they are append-only soft tombstones with monotonic sequence markers to prevent resurrected items upon reconnect.

Tradeoff Analysis: Running schema-per-tenant requires automated migration tooling across hundreds of PostgreSQL schemas during release cycles. We accepted this operational migration overhead in exchange for total data boundary security, zero row-level security policy bugs, and isolated per-tenant backup snapshots.

04 // Failure Modes: Real Production Hazards & Edge Recovery

SEC. 04

Offline architectures fail in subtle ways that normal unit tests cannot detect. NoreOS was tested against real network corruption scenarios:

Hazard / Failure Mode	Immediate Impact	Engineered Recovery Protocol
WAN Cut Mid-Payload	Cloud receives 60% of batch; client TCP timeout triggers before ACK.	Ingest reconciler uses deterministic transaction hashes. Re-pushed batches deduplicate at database insert with zero double-charge risk.
Terminal Clock Skew	Register battery dies; CMOS clock resets to Jan 1, 1970.	Reconciliation ignores client wall clock for causal ordering, relying on monotonic sequence counters generated by the local SQLite event log.
Concurrent Stock Collision	Two cashiers sell the final unit of medicine simultaneously while offline.	Both transactions complete with physical receipts. When synced, inventory dips to -1, triggers an immediate audit alert, and creates an audit dispute entry.
Stale Client Migrations	A register remains disconnected for 4 weeks while cloud schema is updated.	Batch sync endpoints maintain schema version adapters. The server validates the mutation envelope version, transforming legacy payloads before schema commit.

05 // Outcome: Verification Gate & Production Metrics

SEC. 05

NoreOS is deployed live in production (noreos.com). The core system was architected and verified under a mandatory 80% code coverage gate in automated CI pipelines:

Coverage Gate 80% Mandatory CI threshold

E2E Flows 396 API integration scenarios

Unit Tests 535 287 Flutter + 248 React

Lines of Code 100K+ Solo-architected core

Locales 10 Script-correct (Arabic/Urdu RTL)

The system was built by Mustafa Shaikh utilizing agentic AI engineering workflows — maintaining dynamic code knowledge graphs, specialized sub-agents, and checkpointed loop verification. This demonstrates how modern senior backend engineers leverage AI as operational leverage while maintaining absolute ownership over schemas, state boundaries, and failure modes.