Skip to main content
Version: Current

LAN, Offline Operation, and Synchronization

The School Server is designed so the school can keep working when the internet is unavailable, provided the local appliance and LAN remain available and this server owns write authority.

Canonical school URL​

Use:

https://school.makronexus.local

Managed clients must trust the appliance CA. HTTP is a bootstrap/redirect surface, not the normal ERP origin.

If .local discovery is not available in the school network, configure managed DNS/DHCP to resolve the same canonical name rather than teaching users changing IP addresses.

What “offline” means​

WAN offline​

Cloud/internet is unavailable but the School Server is reachable. This is a supported normal continuity state.

School Server unavailable​

The browser cannot reach the local API. This is a local service/LAN incident and is more serious for onsite workflows.

Device-held changes​

A permitted browser outbox item has not yet reached the School Server database. It must not be counted as a Cloud replication item.

Cloud queue​

A pending replication item is already committed safely on the School Server and is waiting for Cloud convergence.

The local/hybrid shell has a thin status footer. It is not a dashboard or card; it is an operational truth surface.

Typical states:

School Server · Saved to school server · Cloud sync healthy · Synced 2m ago
School Server · Saved to school server · 3 changes waiting for cloud
School Server · Saved to school server · Cloud unavailable
School Server · 2 changes held on this device · Cloud unavailable
School Server · Writes fenced for replacement · Cloud sync healthy
School Server · Write authority not ready · Ready to synchronize

Open the footer popover for the detailed local-save, write-authority and Cloud-replication facts.

Local save semantics​

  • Saved to school server — no browser/device changes are waiting to reach the local database.
  • Saving N changes… — browser-held work is being committed locally.
  • N changes waiting to save — queued on the device, not yet committed to the School Server.
  • N changes held on this device — local API is unreachable; those items have not reached PostgreSQL.
  • Local save needs attention — failed/blocked local queue work needs investigation.

Never describe a device-held item as “safely in the Cloud queue.”

Write-authority semantics​

  • Ready — this appliance is permitted to accept governed school writes under the current control state.
  • Writes fenced for replacement — reads may remain available, but governed writes are intentionally locked while replacement/cutover is in progress.
  • Write authority not ready — authority cannot currently be established; governed writes fail closed.

Authority takes precedence over a reassuring save label. A fenced server must not present itself as a normal writable primary.

Cloud replication semantics​

  • Cloud sync healthy — latest cycle succeeded and no local changes are waiting to upload.
  • Synchronizing with cloud… — canonical replication is active.
  • N changes waiting for cloud — already committed locally; waiting for Cloud.
  • Cloud unavailable — School Server remains local operating node; replication retries later.
  • Synchronization needs attention — conflicts or another governed issue needs administrator review.
  • Cloud sync off — Local only mode is intentional.
  • Sync service not running / Cloud not configured / role mismatch — configuration/runtime issue, not ordinary WAN loss.

The UI does not invent an incoming “N updates available” count when the backend cannot know that count before pull.

Normal WAN outage procedure​

  1. Confirm users can still open the trusted local URL.
  2. Confirm the footer reports School Server reachable and write authority ready.
  3. Continue school work normally.
  4. Do not switch to Local only merely because WAN is down.
  5. Record the outage if required by operations policy.
  6. Restore WAN/DNS/proxy connectivity when practical.
  7. Allow Automatic sync to converge or use authorized Sync now in Manual mode.
  8. Verify pending Cloud queue drains and conflicts are reviewed.

Manual synchronization​

An authorized user can trigger the canonical School Server → Cloud replication cycle. The result reports actual pushed/pulled/conflict counts from the backend operation.

Do not repeatedly click Sync now when the system reports a blocking authority/compatibility/integrity condition. Fix the condition first.

Reconnect convergence test​

For field acceptance:

  1. create a harmless controlled local test record while WAN is available and confirm sync;
  2. disconnect WAN but leave LAN intact;
  3. create/update an eligible local record;
  4. confirm it commits to the School Server and becomes waiting-for-Cloud work;
  5. verify users can navigate other local ERP areas;
  6. reconnect WAN;
  7. wait/trigger sync;
  8. verify the Cloud copy receives the local change;
  9. create/update a different eligible Cloud record where authority permits it;
  10. verify the School Server pulls/applies it;
  11. verify no duplicate mutation/conflict was introduced by transport retry.

Browser disconnected from the School Server​

The browser outbox intentionally has stricter rules than the School Server's durable database. Sensitive domains may require a live local API and are not promised to work fully disconnected from the appliance.

This protects school/student/finance data from being casually persisted into a general browser queue. If a use case requires a teacher device to leave campus and transact without both WAN and School Server connectivity, treat that as a separate encrypted edge-device product requirement.

File behavior​

Local file access depends on the School Server/MinIO being available. Replicated file transfers verify bytes before dependent metadata is considered usable. If a file record exists but the object cannot be opened, treat it as an integrity/storage incident rather than a harmless sync delay.

WAN-offline acceptance checklist​

  • A second LAN device uses https://school.makronexus.local without a certificate warning.
  • School Server footer reports LAN reachability.
  • Write authority is ready before testing writes.
  • WAN can be removed without taking down LAN routing.
  • Local login/navigation continue.
  • Eligible local transaction commits during WAN loss.
  • Footer distinguishes local commit from Cloud queue.
  • No sensitive browser-only operation is falsely promised while local API is unreachable.
  • Reconnect drains Cloud queue.
  • Bidirectional convergence is verified where authority permits.
  • Final conflict/pending state is understood.

Next: Validation, Updates, and Rollback.