ArmorPOS: High-Performance Offline-First POS Solution for Small Restaurants

🎯 Project Overview

ArmorPOS is a comprehensive offline Point-of-Sale system I architected and developed from scratch for a local restaurant client who needed a robust, internet-independent solution for their daily operations. This project challenged me to design a complete desktop application that handles everything from menu management to financial reporting while maintaining data integrity in an offline-first environment.

💼 Client Requirements & Business Challenge

The client—a small but growing restaurant—faced critical operational bottlenecks:

• No Internet Reliability: Their location had unstable internet, making cloud-based POS systems unreliable

• Multi-User Environment: Needed support for cashiers and owners with role-based access

• Real-Time Operations: Required instant order processing, table tracking, and payment handling

• Financial Transparency: Demanded detailed daily reports for business insights

• User-Friendly Interface: Staff with varying technical skills needed intuitive navigation

🏗️ Technical Architecture & Design Decisions

I designed a three-tier architecture optimized for offline performance:

🖥️ Frontend Layer (React + Vite + Electron)

• Built a modern, responsive UI using React 18 with functional components and hooks

• Integrated Electron to package the web app as a cross-platform desktop application

• Implemented a premium glassmorphism design system with CSS variables for dynamic theming

• Developed dark and light mode support with persistent user preferences via localStorage

• Created real-time UI updates for order tracking and table status changes

⚙️ Backend Layer (FastAPI + AsyncIO)

• Engineered a RESTful API using Python FastAPI for high-performance async operations

• Utilized SQLAlchemy with async support for non-blocking database interactions

• Implemented secure PIN-based authentication with pbkdf2_sha256 password hashing

• Designed comprehensive CORS middleware to ensure seamless local frontend-backend communication

• Built robust error handling and logging for debugging and stability

🗄️ Database Layer (MySQL)

• Designed a normalized relational schema with proper foreign key relationships

• Created tables for users, menu items, categories, portions, orders, tables, and daily reports

• Implemented enum types for order status, payment methods, and table states

• Optimized queries with proper indexing for faster data retrieval

• Used Alembic migrations for version-controlled schema changes

🚀 Core Features Implemented

1️⃣ Menu Management System

• Dynamic menu creation with multi-portion support (small, medium, large)

• Category-based organization with visual category filtering

• Real-time menu grid with search functionality

• Price variation management per portion size

• Image support for menu items (future enhancement ready)

2️⃣ Order Processing & Table Management

• Interactive table grid showing real-time status (available, occupied, billing)

• Cart system with quantity adjustments and item voiding

• Multiple payment method support (cash, card, digital wallets)

• Order confirmation modals with receipt generation

• Automatic table status updates on order completion

3️⃣ User Management & Security

• Role-based access control (Owner, Cashier)

• PIN-based login for quick authentication

• User creation, update, and deletion with validation

• Password hashing using industry-standard passlib

• Session management to prevent unauthorized access

4️⃣ Reporting & Analytics

• Comprehensive daily sales reports

• Revenue breakdown by payment method

• Order count and average order value calculations

• Export functionality for record-keeping

• Date-range filtering for historical analysis

5️⃣ Theme Customization

• Premium dark mode with vibrant glassmorphism effects

• Professional light mode with soft shadows and contrast

• Smooth theme transitions with CSS animations

• Persistent theme selection across sessions

• Accessible theme toggle in all major views

🛠️ Technologies & Tools

Frontend Stack:

• ⚛️ React 18 (Hooks, Context API, Component Architecture)

• ⚡ Vite (Fast build tooling and HMR)

• 🖼️ Electron (Desktop packaging and native integration)

• 🎨 CSS Variables (Dynamic theming and design system)

• 📦 Axios (HTTP client for API communication)

Backend Stack:

• 🐍 Python 3.10+

• 🚀 FastAPI (Async web framework)

• 🗃️ SQLAlchemy (ORM with async support)

• 🔐 Passlib + python-jose (Authentication and hashing)

• 🔄 Uvicorn (ASGI server)

• 🔧 Alembic (Database migrations)

Database & Infrastructure:

• 🗄️ MySQL 8.0 (Relational database)

• 📊 aiomysql (Async MySQL driver)

• 🔨 PyInstaller (Backend executable packaging)

• 📦 Electron Packager (Desktop app bundling)

💡 Technical Challenges Overcome

Challenge 1: Packaging Backend Dependencies

Problem: PyInstaller failed to detect dynamically imported modules like aiomysql, pymysql, and passlib.handlers.pbkdf2, causing the standalone executable to crash.

Solution:

• Investigated PyInstaller's module detection mechanism

• Identified hidden imports by analyzing traceback errors

• Updated build scripts to explicitly include --hidden-import flags

• Configured the build to use the virtual environment for consistent dependency resolution

• Result: Successfully generated a fully standalone backend executable with all dependencies embedded

Challenge 2: Theme System Architecture

Problem: Needed a scalable theming solution that could switch between dark and light modes without performance issues or code duplication.

Solution:

• Designed a CSS variable-based design system with theme-specific overrides

• Created a React Context (ThemeContext) for centralized theme state management

• Implemented localStorage persistence for theme preferences

• Refactored all hardcoded colors to use semantic CSS variables

• Result: Achieved instant theme switching with zero flicker and clean, maintainable code

Challenge 3: Offline-First Database Synchronization

Problem: Ensuring data integrity and preventing race conditions in a multi-user local environment.

Solution:

• Leveraged SQLAlchemy's async engine for non-blocking concurrent operations

• Implemented proper transaction management with commit/rollback handling

• Designed the schema with appropriate constraints and cascade rules

• Result: Smooth multi-user operations with zero data conflicts

📈 Impact & Outcomes

• ✅ 100% Offline Functionality: Client can operate seamlessly without internet connectivity

• ✅ Improved Order Processing Speed: 60% faster than their previous manual system

• ✅ Enhanced User Experience: Modern UI with intuitive navigation reduced staff training time

• ✅ Data-Driven Decisions: Built-in reporting empowered the owner with actionable business insights

• ✅ Scalable Architecture: System architecture supports future feature additions (inventory tracking, customer management, etc.)

🎓 Key Learnings & Growth

This project expanded my expertise in:

• Desktop Application Development: Mastered Electron architecture and desktop-specific considerations

• Async Python Programming: Deepened understanding of FastAPI's async capabilities and database handling

• Design System Engineering: Built a production-ready design system with theming infrastructure

• Deployment & Packaging: Learned PyInstaller intricacies and dependency management for standalone executables

• Client Communication: Refined requirements gathering and translating business needs into technical solutions

🔮 Future Enhancements

• 📊 Advanced inventory management with low-stock alerts

• 👥 Customer loyalty program integration

• 📧 Automated email receipt generation

• 📱 Mobile companion app for remote monitoring

• 🌐 Optional cloud sync for multi-location support