• 

• 

• 

• 

• 

• 

• 

• 

• 

BarButler: Your Shop's Digital Alfred

Inspiration

The Spark

It started with a beer in Nairobi. I was sitting at my local, watching the attendants close out their shift. In 2026, in a city buzzing with tech, they were still huddled over a notebook, using their phone calculators to subtract stock and balance M-Pesa till numbers.

I looked around and realized two other businesses on the same street were doing the exact same thing. The problem wasn't that they didn't have smartphones—they all did. The problem was that existing POS software was too expensive, too complex, and built for Western retail, not the dynamic, fast-paced reality of a Kenyan liquor store.

What it does

BarButler is an "Alfred" for the SME owner. It transforms a standard Android or iOS phone into a powerful inventory and audit terminal. It replaces the "Paper & Calculator" method with a system that is:

Vision-Powered: Attendants don't need to type in hundreds of numbers. They simply snap a picture of their physical stock sheet, and BarButler's AI digitizes the handwriting, populating the database instantly for verification.

Offline-First: Because internet in the shop isn't always reliable.

Fraud-Resistant: Using HMAC-hashed PINs and granular role-based access to prevent "shrinkage" (theft).

Intelligent: Instead of just recording sales, the "Alfred" AI analyzes variance trends to predict run-outs and detect anomalies.

How we built it

I architected this as a Monorepo using Melos, ensuring code sharing between the Client (Flutter) and Server (Serverpod).

The Backend: I chose Serverpod (Dart on the Server) to maintain a single language stack. This allowed me to share protocol classes (DTOs) directly between the backend and the app, guaranteeing type safety and eliminating JSON parsing errors.

The AI Vision: I integrated Google Gemini 3 Pro's Nano Banana to process images of handwritten stock sheets. The app compresses the image, sends it to the cloud, and the LLM returns structured JSON data matching our Product schema, turning a 20-minute data entry task into a 10-second scan.

The Database: We used PostgreSQL for the heavy lifting (ACID transactions for stock adjustments) and Redis for fast session management.

The Intelligence: I implemented a custom "Weighted Moving Average" algorithm in Dart to analyze historical stock_ledger data. This allows the app to predict, for example, that you need more Tusker Cider on a Friday based on the last 4 weeks of data.

The weighted moving average can be expressed as:

$$\text{WMA} = \frac{\sum_{i=1}^{n} w_i \cdot x_i}{\sum_{i=1}^{n} w_i}$$

where $w_i$ represents the weight for period $i$, and $x_i$ represents the sales data for that period.

The Frontend: Built with Flutter, focusing on a "God Mode" UI for owners (charts, insights) and a high-contrast, big-button UI for attendants working in low-light environments.

Challenges we ran into

Another hurdle was Authentication. SME owners often employ casual staff who don't have email addresses.

Solution: I built a custom Auth endpoint that generates internal handles (staff_uuid@internal) but allows employees to login purely via a secure 4-digit PIN paired to the shop's tenant ID.

Accomplishments that we're proud of

• The "Alfred" AI Vision: We successfully integrated Google Gemini 3 Pro's Nano Banana to solve a real-world friction point. Building a pipeline that takes a grainy photo of a handwritten book and converts it into structured database rows was a massive technical win that actually saves users hours of work.

• Full-Stack Type Safety: By using Serverpod (Dart on the server), we achieved end-to-end type safety. We shared our data models (DTOs) between the Flutter client and the backend, which eliminated an entire class of "JSON parsing" bugs and sped up development by 40%.

• The "God Mode" Dashboard: We built a high-performance analytics engine that aggregates millions of data points into a sleek, 60fps "Tycoon" dashboard. Using custom SQL aggregation instead of naive loops meant our dashboard loads instantly, even on slower networks.

• Solving the "No Email" Auth Problem: We engineered a custom authentication system that allows casual laborers to log in securely with just a PIN and a shop ID, while maintaining strict role-based access control (RBAC) in the backend.

What we learned

The "Inventory Reality Gap": We initially tried to build a standard POS with the formula:

$$\text{New Stock} = \text{Stock} - \text{Sales}$$

We quickly learned that in a busy bar, this never works due to breakage, theft, and freebies. We pivoted to a Shift-Based Audit System (Opening vs. Closing stock), which is technically harder to build but matches the actual workflow of Kenyan businesses.

The Power of Monorepos: Managing the Client, Server, and Shared Protocol in a single Melos workspace was a game-changer. It allowed us to iterate on features like "Stock Transfer" across the full stack in minutes rather than hours.

Auth is Hard: We struggled with a "Double Login" issue where our custom JWT scopes were being stripped by the default auth handler. Debugging this taught us deep lessons about how Serverpod handles sessions and headers, leading to a robust custom implementation.

What's next for BarButler

"Alfred" 2.0 (Predictive Ordering): We want to upgrade our "Weighted Moving Average" algorithm to factor in local events (e.g., "It's the Rugby Sevens weekend in Nairobi, double the stock of Tusker").

Offline-First Sync: While the app works well now, we plan to implement a full Conflict-Free Replicated Data (CRDT) layer using Drift, ensuring that shops in rural areas with zero connectivity can operate for weeks and sync seamlessly when they hit a Wi-Fi hotspot.

Hardware Integration: We plan to add support for Bluetooth Thermal Printers to print shift summaries and receipts directly from the attendant's phone.

Beta Launch in Westlands: We have lined up 3 shops in Nairobi to pilot the app next month, moving from "Hackathon Project" to "Revenue Generating SaaS."

Built With

• dart
• docker
• flutter
• postgresql
• redis
• serverpod