🌌 Zero-G POS: Transactional Integrity in High-Fluctuation Gravity

A highly resilient, fault-tolerant Point of Sale system built for orbital boutiques and deep-space merchants. Capable of processing high-volume transactions even when the physical terminal—and the local network—are spinning out of control.

🏗️ Architecture Overview

The Zero-G POS is engineered around two core database principles designed to prevent double-charging and phantom inventory during power loss and latency spikes:

1. Multi-Version Concurrency Control (MVCC) We execute unindexed read-heavy queries (e.g., Year-to-Date Station Revenue) simultaneously with high-speed write transactions (e.g., Bulk Freight checkouts). The MVCC snapshot isolates read states, meaning intensive reporting never blocks the checkout queue via lock contention.
2. The Saga Pattern & Event Reconciliation Orbital network connections are unstable. If a payment is authorized but the network connection to the inventory database is severed due to a nebula or power surge, the backend's asynchronous Daemon detects the orphaned state and automatically triggers a compensating transaction (a programmatic void/refund), maintaining total ACID compliance.

📸 Visual Demo

Observe the stability of the software in highly unstable physical environments.

Photo 1: The Zero-Gravity Frontend (A screenshot / GIF of the POS interface running with the body dynamically rotated via transform: rotate(45deg); showing the anti-gravity visual effect while button alignment perfectly maintains interaction boundaries.)

Photo 2: Database Integrity Audit (A screenshot of the backend terminal catching the intentional race-condition test, explicitly showing the "409 Conflict" lock being successfully deployed to prevent a double-spend).

Photo 3: Portable Station Deployment (A photo of the system successfully running responsively on a mobile tablet connected to the local network http://192.168.x.x:5173).

🚀 Installation & Deployment

You can deploy the POS locally for station operations using standard npm or our orchestrated Docker containers.

Option A: Running Locally (Node.js)

# 1. Start the Backend API
cd backend
npm install && npm start

# 2. Start the Frontend Dev Server
cd ../frontend
npm install && npm run dev

Option B: Running via Docker-Compose

# Provisions the frontend, backend API, and database isolated instances instantly.
docker-compose up --build -d

📡 API Documentation (Local Endpoints)

By default, the backend listens on your local orbital network. Here are the core exposed ledgers:

Endpoint	Method	Payload	Function	Response
http://192.168.x.x:5000/api/v1/inventory	GET	None	Fetches current mass/stock	200 OK
http://192.168.x.x:5000/api/v1/checkout	POST	{ items[], payment_id }	Commits transaction sequence	201 Created
http://192.168.x.x:5000/api/v1/sync	POST	None	Reconciles state to QuickBooks	202 Accepted

🤝 Contributing

We welcome structural engineers and code-monkeys alike.

1. Fork the project.
2. Create your Feature Branch (git checkout -b feature/Quantum-Payments).
3. Commit your Changes (git commit -m 'Add quantum routing').
4. Push to the Branch (git push origin feature/Quantum-Payments).
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details. Free to use across the civilized galaxy.