← Back to all projects

Retail POS System — Offline-First Point of Sale

A Django-based, offline-first point-of-sale system built for small retail businesses. It handles sales recording, inventory management, and returns, and uses a phone's camera for barcode scanning for stock taking, and inventory management, and completing sales instead of requiring dedicated scanner hardware.

Client
Multiple
What I did
Full stack Django development, architecture design, testing, deployment.
Year
2026
Live project
See the Project on Github
POS system homepage

The problem

Small retail businesses often lose sales during internet outages, since most POS systems are cloud-dependent and stop working the moment connectivity drops.

In addition, manual inventory counts are slow and error-prone, and dedicated barcode scanner hardware adds cost most small shops can't justify.

What I built

Offline-First Architecture

Built on a dual-database setup with SQLite as the default local store, PostgreSQL as the sync target so the system keeps recording sales locally even when the internet is down, then automatically syncs once connectivity returns. A live status widget shows staff their current connection state.

Phone-Camera Stock Taking

Uses the browser's BarcodeDetector API, with a fallback to Html5QrcodeScanner for unsupported devices, so any phone camera becomes a barcode scanner. There's no extra hardware needed for inventory management or sales recording.

Separate manager, staff, and super admin accounts

Separate accounts for managers, staff, and super admins to ensure proper access control and security. Each account type has different levels of access and permissions, and can only perform specific tasks and access different parts of the system.

Customer management

The cashier can add a customer at the time of sale. This way, the cashier can find the customer then next time they visit. Also, all customer purchases and refunds are stored for retrieval later.

Returns & Refunds

Built a dedicated returns module so staff can process refunds without manual database edits or workarounds.

Low Stock Alerts

Automated email notifications fire when inventory drops below a set threshold, so restocking happens before a shelf goes empty.

Management Dashboard

Built on Django Unfold with custom routing and Chart.js visualizations, giving owners date-range filtering and sales insight without needing a separate analytics tool.

POS Orders page
Orders Page
Pos Settings page
Settings Page

How it's built

Why Django, and why offline-first

A point-of-sale system can't stop working when the internet does. The shop keeps trading through outages, and a sale can't wait on a remote server.

So the system is built offline-first: SQLite is the main database on the device, so every sale is recorded locally and instantly. When a connection is available, it syncs both ways with PostgreSQL. Local sales are pushed up, and changes made elsewhere come back down.

Django gave us a mature ORM, built-in authentication, and an admin we could adapt rather than build from scratch, which kept the codebase small and easy to maintain.

Frontend and asset pipeline

The interface is server-rendered Django templates with Alpine.js for small interactions and HTMX for partial page updates, so there is no single-page-app framework to maintain.

Assets are bundled with Vite and wired into Django through django-vite. Python dependencies are managed with uv. Dashboards use Chart.js. Barcode scanning uses the browser's BarcodeDetector API, so cashiers can scan with a phone camera instead of dedicated hardware.

During development the app is tested on a real phone over the local network, since that is how it will be used.

Data and features

The core model covers products, sales, and stock, with low-stock alerts to prompt reordering. Returns and refunds are first-class features rather than manual adjustments, so the records stay accurate.

A sync widget shows staff whether the device is caught up, which makes the offline behaviour visible instead of mysterious. Back-office work happens in the Django Unfold admin, which gives managers a modern interface without a custom admin build.

Payments

The system supports M-Pesa and Airtel Money alongside cash, because that is how customers in Kenya actually pay.

Security and access

A custom user model with manager roles controls who can do what, such as who can issue refunds or change stock. Because every device keeps its own local copy and syncs with PostgreSQL, the shop's records exist in more than one place, so a failure in one doesn't take them all with it.

  • Python
  • Django
  • Alpine.js
  • SQLite / PostgreSQL
  • Django Unfold
  • HTMX
  • Chart.js

Results

Smooth SyncsData between local and central storage is always in sync
~40Retail stores using this system
Live sinceApril 2026
We love how easy this POS is to use, especially with the phone camera and barcode scanner. Now, all my employees can complete sales wherever they are in the store, and I can see sales and other data wherever I am. The email alerts help me keep track of my stock, and being able to see all transactions on my phone helps with financial management.Njoroge Muhia, Retail Partner, Njuwa Traders

Need a similar website, platform or tool for your business?

Tell me what you're building and I'll reply with next steps.

Start a project

Frequently Asked Questions

Getting started
What information do you need from me to get started on a project?

I typically need a clear description of your project goals, target audience, any design preferences, technical requirements, and timeline expectations.

The more details you can provide, the better I can tailor my approach.

For larger projects, I'll provide a detailed questionnaire to help you articulate your vision.

I'm also happy to schedule an initial consultation call to discuss your needs more thoroughly.

Schedule a Consultation
Have you worked with businesses in my industry before?

I've worked with clients across diverse industries including healthcare, real estate, digital marketing, and others.

While each industry has unique requirements, my experience has taught me how to quickly adapt to different business domains.

For industries new to me, I invest time in research to understand your specific challenges and standards.

My portfolio includes examples of past work that demonstrate my versatility across sectors.

Contact Me
Project Planning and Execution
How do you prioritize features when working within budget constraints?

I use a value-driven approach to feature prioritization.

We'll collaborate to identify "must-have" versus "nice-to-have" features based on your business goals and user needs.

I will then implement core functionality first, then add enhancements as the budget allows. This approach ensures you get a functional product that delivers value, even with limited resources.

I'm transparent about what's achievable within your budget and can suggest phased implementations if needed. Please contact me to discuss this further

Contact Me
How long does a typical project take from start to finish?

Project timelines vary based on complexity and scope.

Simple websites typically take 1-2 weeks, while more complex web applications may require 1-3 months. E-commerce solutions generally take 1.5-3 months depending on customization needs.

After our initial consultation, I'll provide a detailed timeline with key milestones. I'm committed to meeting agreed-upon deadlines while maintaining quality standards.

How do you communicate progress throughout the development process?

I believe in transparent, consistent communication.

You'll receive weekly progress updates for longer projects and daily progress updates for shorter ones via email, and we'll have scheduled check-in calls at key milestones.

I also use project management tools that give you visibility into task completion and upcoming work. This approach ensures you're always in the loop.

For day-to-day communication, I'm available through your preferred channel (email, Discord, Slack, etc.). My goal is to keep you informed without overwhelming you with technical details unless neccessary.

Contact Me
Timelines and pricing
What is your pricing structure? Do you charge hourly, fixed-price, or use another model?

Add your typical timelines here, for example a custom theme in 3 to 5 weeks and a web application in 6 to 12.

How is pricing set?

I offer flexible pricing options tailored to your project needs:

  • Fixed-price contracts for well-defined projects with clear requirements
  • Hourly rates for exploratory work or projects with evolving scopes
  • Retainer arrangements for ongoing development needs

For most client projects, I prefer fixed-price agreements as they provide budget certainty.

After our initial consultation, I'll recommend the most appropriate pricing model and provide a detailed proposal.

All pricing options include regular milestones and deliverables to ensure transparency.

How do you handle change requests during a project?

I understand requirements can and do evolve as projects progress and minor adjustments are accommodated within the original agreement.

For substantial changes, I'll assess the impact on timeline and budget, then provide you with options before proceeding.

I document all change requests and maintain a change log that's accessible to you. This approach ensures transparency while allowing flexibility for your evolving needs.

Support and Maintenance
What is your availability for ongoing maintenance and support after project completion?

I offer several post-launch support options:

  • A 30-day warranty period for all projects to address any immediate issues
  • Monthly maintenance packages for regular updates and minor improvements
  • Priority support agreements for business-critical applications
  • Ad-hoc support at my standard hourly rate

I recommend discussing maintenance needs early in the project planning phase so we can build with long-term support in mind. My goal is to ensure your solution remains secure, performant, and up-to-date.

What's your process for handling urgent issues or emergency fixes?

For clients with support agreements, I provide a dedicated channel for reporting urgent issues with guaranteed response times (typically within 1-4 hours depending on your support tier).

For clients without support agreements, you can contact me at anytime and we will schedule a time to discuss the issue. My availability is flexible and I'll do my best to respond within one business day.

Do you offer any guarantees or warranties on your work?

Yes, all my work comes with a 30-day warranty period after project completion. During this time, I'll fix any bugs or issues at no additional cost.

I also guarantee:

  • Code that follows industry best practices
  • Cross-browser compatibility as specified in our agreement
  • Responsive design for mobile devices
  • Adherence to accessibility guidelines
  • Secure coding practices

My contracts clearly outline what's covered under warranty and what would constitute billable changes or enhancements. Contact me if you need further clarification or have a question about these guarantees.

Contact Me

Let's work together

Tell me what you're building and I'll reply with next steps.