Deployment Model and Architecture

Makronexus uses local school continuity with governed cloud convergence. The School Server is the onsite ERP authority for school-owned operational domains when policy assigns those domains to it. Cloud remains the control plane for provisioning, fleet lifecycle, central visibility, compatible release policy, and convergence.

Runtime topology

The ordered data path

For a browser mutation made onsite:

browser/device
  → local API
  → School Server PostgreSQL commit
  → archive/file protection work
  → canonical School Server → Cloud push
  → Cloud apply
  → later Cloud → School Server pull

This ordering matters. The browser outbox is not the Cloud replication queue:

• a browser/device item has not yet reached the school database;
• a replication-queue item is already safely committed to the school database and is waiting for Cloud.

The footer and administration UI keep those concepts separate.

Authority is explicit, not inferred

Makronexus does not rely on “last writer wins” as the primary split-brain policy.

Per-school/domain authority determines who may accept governed writes. School-owned operational domains are assigned to the active primary School Server where applicable. Cloud-side editable paths and appliance replication both fail closed if authority cannot be established.

During server replacement, the candidate is deliberately non-primary and write-fenced until cutover. See Authority and Offline Semantics and Backup, Restore, and Server Replacement.

WAN offline is a normal operating state

When WAN connectivity disappears but the School Server remains reachable over the LAN:

1. users continue to open the local ERP;
2. governed writes commit locally if this appliance owns write authority;
3. committed changes accumulate for Cloud replication;
4. the footer reports Cloud unavailability without calling the local ERP unavailable;
5. when WAN returns, the coordinator converges from durable cursors.

This is different from a browser being unable to reach the School Server itself. Sensitive domains are not promised to be fully writable from a disconnected browser/device with no School Server connection.

Canonical replication safety

Machine replication is scoped by tenant, school, site, and enrolled appliance identity. Requests use API-key authentication plus HMAC, timestamp and nonce replay protection. Before school data is applied, Cloud can enforce application-version, replication-protocol, and database-schema compatibility.

The coordinator advances durable cursors only after safe outcomes. Blocking failures do not advance the cursor. Retried transport requests use deterministic mutation semantics so response loss does not create duplicate logical work.

Initial bootstrap is a verified snapshot, not blind history replay

A new or replacement appliance establishes an authoritative high-water checkpoint, reconciles the current source state, transfers the bounded snapshot, verifies payload/file integrity and expected manifest evidence, and then consumes post-checkpoint deltas.

For files, bytes are transferred and checked before corresponding metadata is treated as usable. A bootstrap must fail closed rather than report success with missing/corrupt file objects.

File protection

File records and bytes are separate concerns. The protection path verifies object size/checksum across transfer boundaries. Replication health must not claim the appliance is healthy while its required protection/archive/file stage is failing.

Runtime identity

A normal field appliance starts without tenant, school, or site UUID input. During zero-touch setup:

• the appliance generates its stable site identity;
• Cloud enrollment determines tenant and school identity;
• non-secret runtime identity is persisted under the appliance runtime directory;
• long-lived API/HMAC credentials are encrypted server-side;
• the browser receives only the short-lived setup capability needed to continue setup.

Updates preserve runtime identity, local CA, enrollment credentials, bootstrap state, cursors and conflict state.

LAN trust boundary

The canonical LAN origin is:

https://school.makronexus.local

The bundle creates an appliance-local CA and server certificate, publishes/discovers the LAN identity where host capabilities allow it, and performs renewal checks. Managed clients trust the appliance CA once; the server certificate can then renew under that stable trust root.

The HTTP surface is intentionally limited to bootstrap/redirect behavior such as obtaining the CA. Production ERP sessions use HTTPS.

Appliance health is multi-dimensional

A School Server is more than a replication worker. Health includes resource pressure, PostgreSQL, Redis, object storage, container supervisor freshness, backup age, LAN certificate, clock/NTP, bootstrap/setup readiness, write fencing, runtime/fleet telemetry and synchronization posture.

Cloud keeps fleet posture/history so operators can distinguish a WAN outage from a failing appliance.

Replacement safety

Replacement is a two-phase authority transfer:

If the old source is genuinely dead, cutover uses an explicit physical-decommission/offline confirmation path rather than assuming silence equals safety.

Deployment consequence

Field acceptance must prove local persistence, trusted LAN access, identity, bootstrap integrity, write authority, bidirectional convergence, WAN-offline continuity, monitoring, update persistence, recovery and replacement readiness. A green webpage alone is not appliance certification.