A virtualized dual-head point-of-sale system built with Electron, demonstrating enterprise-grade architecture patterns for high-volume retail environments.
| Platform | Download |
|---|---|
| macOS (Apple Silicon) | Zero.Crust-darwin-arm64-1.1.4.zip |
| macOS (Intel) | Zero.Crust-darwin-x64-1.1.4.zip |
| Windows | Zero.Crust-1.1.4.Setup.exe |
| Linux (Debian/Ubuntu) | zero-crust_1.1.4_amd64.deb |
| Linux (Fedora/RHEL) | zero-crust-1.1.4-1.x86_64.rpm |
Zero Crust is a POS simulator designed to explore and validate architectural patterns for quick-service restaurant operations. It features a dual-window architecture with synchronized state management, simulating separate cashier and customer-facing displays while maintaining data consistency across both. This is a reference implementation for studying distributed state management, secure IPC communication, and offline-first design patterns.
 |
 |
 |
|
 |
|
- Dual-Head Display Simulation - Separate cashier and customer windows with real-time synchronization
- Custom Titlebars - Native-feeling window controls with theme-matched colors on macOS, Windows, and Linux
- Offline-First Architecture - Local data persistence demonstrates continuous operation patterns
- Integer-Only Currency - All monetary values stored in cents to prevent floating-point errors
- Command Pattern IPC - Type-safe, auditable command system for all state mutations
- Simulated Payment Processing - Models async payment flows with retry logic and error handling
- Transaction Recovery - Automatic detection and voiding of pending transactions on restart
- Demo Loop - Auto-generates realistic order patterns for continuous operation
+-------------------+ +-------------------+
| Cashier Window | | Customer Window |
| (Renderer) | | (Renderer) |
+--------+----------+ +----------+--------+
| |
| contextBridge (IPC) |
v v
+--------------------------------------------------+
| Main Process |
| +-------------+ +------------+ +------------+ |
| | MainStore | | Payment | | Persistence| |
| | (State) | | Service | | Service | |
| +-------------+ +------------+ +------------+ |
+--------------------------------------------------+
| Principle | Implementation |
|---|---|
| Security Boundary | All business logic executes in the Main process. Renderers are sandboxed with contextIsolation: true and nodeIntegration: false. |
| Single Source of Truth | MainStore holds all application state. Changes broadcast the entire state to all renderers. |
| ID-Based Messaging | Renderers send only product SKUs. Main process looks up prices from the catalog, preventing price tampering. |
| Immutable Updates | State mutations use Immer for clean, predictable updates with automatic structural sharing. |
| Runtime Validation | All IPC commands validated with Zod schemas before processing. |
| Category | Technology |
|---|---|
| Framework | Electron 36 with Vite 6 |
| Language | TypeScript (strict mode) |
| UI | React 19 |
| Styling | Tailwind CSS 4 |
| State Updates | Immer |
| Validation | Zod |
| Persistence | electron-store |
| Testing | Vitest |
| Build | Electron Forge |
src/
├── main/ # Main process modules
│ ├── MainStore.ts # Centralized state management
│ ├── WindowManager.ts # Dual-head window orchestration
│ ├── PaymentService.ts # Mock payment gateway
│ ├── BroadcastService.ts # State synchronization
│ ├── PersistenceService.ts # Local data storage
│ ├── SecurityHandlers.ts # Electron security config
│ └── Logger.ts # Structured logging
├── renderer/ # React application
│ ├── views/ # Cashier and Customer views
│ ├── components/ # Reusable UI components
│ └── hooks/ # React hooks for state/commands
├── shared/ # Shared types and utilities
│ ├── ipc-types.ts # IPC command definitions
│ ├── schemas.ts # Zod validation schemas
│ ├── currency.ts # Integer currency utilities
│ └── catalog.ts # Product catalog
├── main.ts # Main process entry point
├── preload.ts # Secure IPC bridge
└── renderer.tsx # React entry point
- Node.js 20+
- pnpm (recommended) or npm
pnpm installpnpm startThis launches both the cashier and customer windows with hot module replacement enabled.
pnpm test # Run all tests
pnpm test:watch # Watch mode
pnpm test:coverage # With coverage reportpnpm makeGenerates platform-specific distributables in the out/make directory.
| Key | Action |
|---|---|
| F1-F12 | Quick-add products in current category |
| Ctrl+Enter | Process payment |
| Escape | Cancel current operation |
Models hardware segregation found in production POS deployments where customer displays run on separate hardware or HDMI outputs. Demonstrates distributed state management across isolated processes.
Financial transactions cannot tolerate floating-point rounding errors. Storing amounts in cents (e.g., $5.99 as 599) ensures accounting accuracy.
For carts with fewer than 50 items, sending the entire state object has negligible overhead compared to delta-sync complexity. This eliminates an entire class of synchronization bugs.
Retail environments often have unreliable network connectivity. This offline-first architecture ensures operations continue during outages, with data syncing when connectivity returns.
Decouples intent from execution. Every action becomes auditable, replayable, and testable. Forms the foundation for event sourcing if the system scales.
Security. The renderer is effectively a web browser and is vulnerable to injection attacks. Business logic and pricing must live in the privileged Main process, which acts as the trusted environment.
Type safety catches bugs at compile time, not in production. In a payments context, a type error could mean money errors. Strict mode ensures maximum safety.
Observability. When something goes wrong at 2am in a franchise 500 miles away, logs are how you diagnose it. Structured logs enable filtering, searching, and alerting.
Zero Crust implements Electron security best practices:
- Context Isolation - Renderer processes cannot access Node.js APIs directly
- Sandboxed Renderers - Each window runs in a restricted sandbox
- Validated IPC - All commands pass through Zod schema validation
- Navigation Control - Blocks unauthorized navigation and
window.opencalls - Permission Denial - Blocks all permission requests (camera, microphone, geolocation)
- Sender Verification - IPC handlers validate message origin
The simulator includes an automated transaction loop for continuous operation:
- Generate Order - Creates realistic order patterns (combos, family meals, single items)
- Verification Delay - Simulates cashier review time with randomized delays
- Payment Processing - Processes simulated payment with realistic success/failure rates
- Auto-Retry - Automatically retries failed payments with exponential backoff
- Transaction Completion - Opens receipt window and starts new transaction
Enable the simulation loop from the cashier interface to observe continuous transaction flow.
Real-time operational metrics displayed on the cashier screen:
- Transactions per minute (TPM)
- Average cart size
- Daily transaction count
- Daily revenue total
A real-time visualization tool for understanding and debugging the application's IPC message flow, state changes, and system health. This window is included in production builds as an observability tool.
Access: Window menu > Show Architecture, or keyboard shortcut Cmd/Ctrl+Shift+A
| Panel | Description |
|---|---|
| Graph | Interactive node diagram showing Main Process, Cashier, Customer, and Transaction History windows with animated edges that pulse when messages flow |
| Timeline | Virtualized event log with color-coded entries, expandable payloads, and filtering by event type |
| Stats | Live metrics including events/second, total events, state version, and connected window count |
| State Inspector | JSON tree view with diff highlighting showing what changed between state versions, plus a time-travel slider to navigate state history |
| Type | Color | Description |
|---|---|---|
| command_received | Blue | IPC command received from renderer |
| command_processed | Green | Command handler completed |
| state_broadcast | Amber | State synchronized to windows |
| ipc_send | Purple | IPC message sent to renderer |
| payment_start | Teal | Payment processing initiated |
| payment_complete | Emerald | Payment processing finished |
- Debugging: Trace command flow from UI action to state change
- Architecture Education: Visualize Electron's Main/Renderer process model
- Performance Analysis: Monitor event latency and throughput
- State Inspection: Examine state changes with diff highlighting
The architecture window uses lazy activation. When closed, there is zero overhead. When open:
- UI updates throttled to 60fps
- Virtualized lists handle high event volumes
- Circular buffer capped at 1000 events
MIT
Made with ❤️ by Cameron Rye