How Maduuka Protects Your Business Data — Every Layer, Every Module

Your data is not ours to mishandle.

That sentence sits at the top of every internal conversation we have before adding a single feature to Maduuka. Not as a slogan. As a constraint — the kind that shapes decisions before the architecture is drawn, before the database schema is extended, before the first API endpoint is defined.

Maduuka holds some of the most sensitive records a small business ever creates. Every sale your till records. Every payroll run for every branch. Every supplier invoice, every customer credit balance, every prescription dispensed in a pharmacy, every folio in a hotel, every hand-off between your kitchen and your front of house. If that data leaks, gets tampered with, or simply disappears, your business stops.

This article explains — in plain terms — the specific protections we apply across every module of Maduuka. You will not find marketing phrases like "bank-grade security" here without the engineering to back them up.

Why Security Cannot Be an Afterthought

Many software teams treat security as something to bolt on after features are built. This is a serious mistake — and an expensive one to undo.

Vulnerabilities introduced at the architecture stage are extraordinarily difficult to fix once a system is in production. A missing authentication check on an API endpoint. A database query that concatenates user-supplied strings. A session token that never expires. Each takes 30 minutes to introduce and months to find, fix, and recover from.

We take the opposite approach. Before a line of Maduuka code is written for a new module, our team establishes the security architecture for it: how the data will be stored, how it will travel between the server and the Android app, who will have access, and what happens when something goes wrong. The POS, inventory, HR and payroll, accounting, pharmacy, restaurant, and hotel modules all sit on the same security foundation. Adding a new industry template — say, fashion or petrol stations — does not weaken that foundation. Every new module inherits it.

What Maduuka Actually Holds

Before describing the protections, it is worth being specific about what we are protecting. A typical Maduuka tenant (one business operating on our platform) stores:

• Sales history — every transaction, every line item, every cash-up, indexed by branch and cashier.
• Stock records — product catalogue, purchase costs, supplier relationships, stock movements between branches.
• Financial data — daily takings, expenses, profit-and-loss, VAT returns, customer and supplier balances.
• HR and payroll — employee records, salaries, loans, leave balances, NSSF and PAYE calculations.
• Pharmacy data — patient profiles, prescriptions, batch numbers, expiry dates, controlled drug logs.
• Hotel data — guest folios, passport details, city ledger debtors, night audit trails.
• Restaurant data — menu items, ingredient consumption, kitchen order tickets, table assignments.
• Payment references — MTN Mobile Money and Airtel Money transaction IDs, bank transfer references, credit sale balances.

Every one of those categories carries a different risk profile. The protections below apply across all of them — but where a specific module needs extra handling, we say so explicitly.

Payment Processing — What We Touch and What We Don't

Cardholder data is the single most dangerous thing a small-business application can hold. So we don't hold it.

Maduuka integrates with established third-party payment gateways on a per-client basis, tailored to the channels the business actually uses. Supported options include DPO Pay (Visa, Mastercard, regional cards), PesaPal (card and mobile money across East Africa), MTN Mobile Money, and Airtel Money. For Ugandan businesses, we also integrate EFRIS — the Uganda Revenue Authority's electronic fiscal receipt system — so VAT-registered clients remain tax-compliant at the point of sale.

Raw card data — PAN, CVV, expiry — never touches the Maduuka server. It is captured directly by the gateway's hosted page or SDK and tokenised before anything reaches us. What we store against the sale is the transaction outcome: amount, gateway reference token, method type, and status. Because Maduuka does not process or store cardholder data, the platform falls under the PCI DSS SAQ A category — the lowest-risk merchant tier, applicable where all card handling is fully outsourced to a PCI-certified gateway. The gateway providers we integrate with hold PCI DSS Level 1 certification and carry the PCI responsibility for card data itself.

All communication to and from payment gateways and EFRIS travels over HTTPS with TLS 1.2+. API credentials are stored server-side in environment variables — never committed to source control, never visible in the application code, never exposed to the browser.

Encrypted Data in Transit

All data moving between the Maduuka server and your Android app, your laptop browser, your office desktop, or a cashier's tablet travels over HTTPS with TLS 1.2 or higher. If someone intercepts the network traffic — through a public Wi-Fi access point in a hotel lobby, for example, or a compromised router in a branch — they see only encrypted, unreadable bytes.

We enforce this without exception. HTTP connections redirect to HTTPS automatically at the server edge, with HSTS headers telling the browser never to try HTTP again. For the Maduuka Android app, we apply certificate pinning on the authentication and payment endpoints: the app will only communicate with servers presenting the correct, verified certificate — not just any certificate that happens to be technically valid.

This closes an entire class of attacks where a malicious Wi-Fi hotspot issues its own certificate and quietly decrypts traffic in the middle. Maduuka's app refuses the trick outright.

Encrypted Data at Rest

Sensitive information stored on your Android device is held in encrypted storage. For login credentials and session tokens, we use Android's EncryptedSharedPreferences — backed by keys stored in the hardware-backed Android Keystore where the device supports it. A lost or stolen phone cannot simply have the app data dumped and read.

For the offline sales cache — the queue of transactions made while the device was offline, waiting to sync — we apply Room encryption via SQLCipher. If someone physically obtained the device's storage and tried to read the offline SQLite file, they would see encrypted pages, not cleartext sales records.

On the server side, sensitive fields are handled with the same discipline. Passwords are never stored in plain text. Payment references, national identification numbers, and similar identifiers are held in isolation from the general sales data so that a breach of one table does not automatically compromise the others. Encryption keys are managed through secure key stores and are never embedded in source code — one of the most common causes of accidental disclosure in the wider industry.

Authentication, Passwords and Sessions

We implement authentication carefully, with no shortcuts.

Password policy

• Hashing: bcrypt via PHP's password_hash() — the industry standard for password storage. No MD5, no SHA-1, no unsalted SHA-256 shortcuts.
• Strength rules: minimum 8 characters, maximum 72. Must contain an uppercase letter, a lowercase letter, a digit, and a special character. Enforced server-side, not just in the browser.
• Breach checking: at registration and on every password change, Maduuka checks the chosen password against the Have I Been Pwned compromised-password database using the k-anonymity model. Only the first five characters of a SHA-1 hash are ever sent — no plaintext, no username, no identifying information ever leaves the system. If the password has appeared in a public breach, the user is required to choose a different one.

Two-factor authentication (TOTP)

Maduuka supports standards-based TOTP two-factor authentication (RFC 6238). Users enrol by scanning a QR code with any standard authenticator app — Google Authenticator, Microsoft Authenticator, Authy, 1Password, and others. There is no lock-in to a specific third-party service and no cloud account is required; TOTP verification runs entirely on Maduuka's server. We strongly recommend 2FA for every administrator — particularly users with access to payroll, supplier payments, cash-up approval, and prescription dispensing.

Session management

• 30-minute idle timeout — inactive sessions are invalidated automatically.
• Session IDs rotate every 15 minutes — preventing session fixation attacks even if a token is intercepted.
• Session cookies are HttpOnly, SameSite=Strict, and Secure — locked against script-based theft, cross-site forgery, and non-HTTPS exfiltration.
• Logout invalidates the JWT immediately server-side — a logged-out token cannot be replayed.
• User-agent binding on every request — the token is bound to the device fingerprint it was issued for. A token suddenly appearing from a different browser or device is rejected.

Brute-force protection

• Maximum 10 login attempts per 15 minutes per IP address, enforced in application code.
• Exceeding the limit returns 429 Too Many Requests with a Retry-After header — not a silent failure.
• Every failed attempt is logged to the database with username, IP address, user agent, and timestamp. The per-user counter resets on successful login.

Account recovery

• Password reset happens via a secure, time-limited, single-use email token — not a security question, not a generated temporary password.
• In-store, supervisor PIN verification is available for escalated POS operations — so a clerk needing to override a discount limit can be authorised by the on-duty supervisor without sharing management credentials.

Protection Against Common Web Vulnerabilities

Maduuka's PHP back-end and JavaScript front-end are written with the OWASP Top 10 in mind at every step.

SQL Injection

Prevented through prepared statements and parameterised queries throughout. We do not construct SQL by concatenating user-supplied strings — ever. The product_search, customer_lookup, and every other endpoint that takes user input runs that input through parameter binding, not string interpolation. This single discipline eliminates the majority of the web-application breaches we still see reported in the region.

Cross-Site Scripting (XSS)

Blocked by escaping all output rendered in the browser. User-supplied content — product names, customer addresses, employee notes, prescription instructions — is validated at the server boundary before processing and HTML-escaped before display. A customer name like <script>steal(document.cookie)</script> shows up on the receipt as text, not as executable code.

Cross-Site Request Forgery (CSRF)

Applied to all state-changing requests through synchroniser token patterns. A malicious site cannot trick an authenticated Maduuka user's browser into silently creating a void sale or transferring stock — the request will fail the token check and be rejected.

File Uploads

Product images, receipt logos, employee photos, and supplier documents are all validated for MIME type, file size, and content — not just extension. Uploaded files are stored outside the web root and served through controlled handlers. A malicious upload masquerading as a PNG cannot execute directly through the web server.

Security response headers — on every response

Every HTTP response that leaves Maduuka carries a hardened set of security headers. The browser receives explicit instructions on what it is and is not allowed to do with the page:

• Strict-Transport-Security: max-age=31536000; includeSubDomains — never accept HTTP again.
• Content-Security-Policy — restricts script execution to same-origin and approved sources, neutralising many XSS payloads even if one slipped through.
• X-Frame-Options: SAMEORIGIN — prevents clickjacking via malicious iframes.
• X-Content-Type-Options: nosniff — blocks MIME sniffing tricks that turn uploads into scripts.
• Referrer-Policy: strict-origin-when-cross-origin — limits referrer leakage to third parties.
• Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=() — denies access to powerful browser APIs the app does not need.
• Cross-Origin-Resource-Policy: same-origin — isolates resources against cross-site attacks.

Server-version disclosure headers (X-Powered-By, Server) are removed — an attacker probing the platform does not get a free inventory of our stack.

Secure API Design

Maduuka's REST API — the backbone that connects the Android app, the web dashboard, and any future third-party integration — is designed on the principle of least privilege: every endpoint exposes only what is necessary, and nothing more.

• Every endpoint is audited. All of our v1 REST endpoints have been explicitly reviewed; the overwhelming majority require a valid JWT and reject unauthenticated requests outright. The very few unauthenticated routes are narrow, stateless utilities (health checks and similar) that expose no business data.
• JWT tokens carry expiry claims and scope restrictions. A token issued for the cashier mobile app cannot be used to call administrative payroll endpoints, even if someone extracts it from the device. The scope is enforced server-side on every request — not just by the front-end.
• High-risk operations enforce explicit, named permission checks at the API layer. Voids, refunds, purchase-order approvals, payroll runs, and role changes each require a specific named permission, not just "is the user logged in?".
• Rate limiting is applied to sensitive endpoints — login, password reset, 2FA verification, and bulk export. Brute-force attempts are throttled and logged. Repeated failures from a single IP trigger temporary blocks.
• All API activity is logged for audit. Who accessed what record, when, from which device — without logging the sensitive data itself. When a question comes up weeks later ("who voided that sale?"), the answer is in the log.

Multi-Tenant Data Isolation

This one matters more than any other, so it gets its own section.

Maduuka is a multi-tenant SaaS. Thousands of businesses share the same application server and database. In this model, strict tenant isolation is non-negotiable. One business must never, under any circumstance, see another business's data.

Every database query in Maduuka is scoped to the authenticated tenant's identifier. This is not a filter applied after the fact, nor a check sprinkled through the application code where a developer might forget. The tenant identifier is part of the query construction itself — baked into the query builder at the framework layer. A query that forgets its tenant scope fails at the framework level, not in production.

In practice this means:

• It is architecturally impossible for Shop A's query to return Shop B's sales records.
• A staff member of Shop A with the highest level of privilege cannot escalate their way into Shop B's data — the application simply has no code path that crosses that boundary.
• A compromised account from one tenant cannot be used to harvest data from another tenant.

Tenant isolation is verified during every code review and tested explicitly before any multi-tenant feature is released. This is the single most important promise Maduuka makes to every business on the platform.

Granular Permissions — What Your Cashier Can and Cannot Do

Maduuka's RBAC system is not a checkbox. It is a fully flexible, fully customisable permission model enforced at the API layer on every request. We ship standard roles out of the box — Clerk, Cashier, Manager, Admin, Super Admin — but any role can be renamed, deleted, or built from scratch, and any permission can be assigned to or removed from any role.

Permissions are fine-grained and named. A partial list of what we enforce:

• CREATE_SALE, VOID_SALES, PROCESS_REFUND, APPLY_DISCOUNT
• APPROVE_PURCHASE_ORDERS, APPROVE_STOCK_ADJUSTMENTS
• MANAGE_USERS, MANAGE_ROLES, MANAGE_PAYROLL, RUN_PAYROLL
• VIEW_FINANCIAL_REPORTS, SYSTEM_ADMIN

A default Clerk can process sales. Voids, refunds, discounts above a configurable threshold, and stock adjustments each require separate, explicitly assigned permissions that are not part of the default Clerk role — enforcing separation of duties. Per-franchise role configurations are supported so multi-branch businesses can run different permission sets in different locations.

For in-store escalation, Supervisor PIN verification allows a cashier to momentarily perform a higher-privileged action (for example, overriding a discount limit) without the supervisor handing over their password. The action is logged against both users.

Audit Trail — Every Data Change, With Before and After

Every data-changing action in Maduuka is written to tbl_audit_logs. Each entry records:

• User ID, franchise ID, IP address, user agent, session ID
• Action type — CREATE, UPDATE, DELETE, VOID, LOGIN, LOGOUT, and more
• Full before/after value snapshots as JSON — you can see exactly what changed, not just that something changed
• Server-side timestamp

This covers every transaction, refund, void, stock movement, user-account change, permission change, role change, and login/logout event. When you need to know who voided a sale at 14:27 last Tuesday, the answer is one filter away.

On top of the application-level log, Maduuka uses database triggers as an independent tamper-evident secondary log. Stock movements and financial balance changes are recorded at the database layer, independent of the application code, by dozens of triggers — so an attempt to bypass the application and modify the database directly still leaves a trail.

Audit logs can be exported to CSV via the platform UI (Admin role), filterable by date range, user, action type, and record. They are available for compliance review at any time.

Hosting and Server Hardening

Maduuka runs on ISO 27001-certified tier-1 cloud infrastructure, hosted in a jurisdiction with strong data-protection law, redundant Tier 1 network upstreams, and built-in network-level DDoS protection. The data centres operate under 24/7 physical security, biometric access controls, CCTV, and fire suppression.

On the server side, we apply the same hardening discipline as in the application:

• Firewall rules restrict inbound access — only HTTPS (port 443) and SSH with key-based authentication from whitelisted administrator IPs. Passwords are not accepted over SSH.
• The database server is on a private network — not publicly reachable from the internet. It accepts connections only from the application server.
• PHP-FPM runs as a restricted system user with no interactive shell and no access beyond the application directory.
• SSL/TLS termination at the web server with automatic HTTPS redirect enforced — no code path serves plaintext HTTP in production.
• Server-version disclosure headers are suppressed — scanners probing the platform get no free reconnaissance data.

Backup and Disaster Recovery

Backups are not an afterthought — they are the last line of defence when something really goes wrong.

• Automated database backups every 3 hours. Your maximum data loss in a worst-case scenario is therefore bounded by three hours.
• Backups are uploaded automatically to a separate, offsite cloud infrastructure — an entirely different provider from the primary hosting environment. No backup is stored only on the primary server.
• Restoration is possible onto a new server — a different region or a different cloud provider — without relying on the original hosting environment. Complete loss of the primary environment does not mean loss of your data.
• 30-day retention by default. Longer retention can be arranged for clients with specific compliance requirements.
• RTO target: under 4 hours for full system restoration. Restoration from backup has been tested and documented.

Secure Development Stack

Maduuka is built on actively maintained, security-supported components — not legacy runtimes accumulating unpatched CVEs.

• PHP 8.2+ — with declare(strict_types=1) enforced across the backend. Strict typing eliminates an entire class of type-juggling security bugs that have historically plagued PHP applications.
• MySQL 8.0+ — every one of our data tables is accessed via PDO prepared statements or stored procedures. No raw string interpolation into queries, anywhere.
• Composer with composer.lock — every PHP dependency pinned to an exact version. Silent upstream upgrades cannot sneak into a deploy. composer audit runs on demand against the PHP Security Advisories database.
• Locked JavaScript dependencies — same discipline on the front-end side.
• Enforced code style — PHP CS Fixer and ESLint catch unsafe patterns before they reach review.

Dependency and Supply Chain Security

Third-party libraries introduce risk when they are not managed carefully. A popular open-source package that gets hijacked can push a malicious update into thousands of applications overnight — this has happened to well-known PHP, JavaScript, and Android libraries in recent years.

We maintain an updated inventory of every dependency across the Maduuka codebase, monitor public vulnerability databases, and replace libraries that fall out of maintenance or carry unpatched vulnerabilities. Composer and npm lock files pin exact versions — a silent upgrade cannot sneak into a deploy. Security-relevant patches are prioritised and rolled out on a schedule measured in days, not months.

Our servers run minimal installations. Only the packages required for Maduuka are present. Unused services, ports, SSH shells, default accounts, and example applications are removed. A server that runs only what it needs has a dramatically smaller attack surface than one with a full stack of optional services left at default settings.

Security in the Development Process

Security is not reviewed only at the end of a release cycle. It is part of every stage.

Code reviews include a security checklist covering input validation, output encoding, authentication flows, permission boundaries, and data handling. Our developers follow documented secure-coding standards for PHP, Android/Kotlin, and JavaScript. Pull requests that touch authentication, payments, or tenant boundaries receive a second reviewer by policy.

New features that handle personal data — patient records in the pharmacy module, guest passports in the hotel module, employee national IDs in payroll — are subject to a privacy impact review before implementation begins. The review answers: what data are we collecting, why is it needed, how long will we keep it, who can access it, and how can it be deleted if the business requests that? Decisions made in that review are documented alongside the feature so the answers survive staff turnover.

We also conduct periodic security audits of our own platform using structured checklists covering configuration, authentication, authorisation, injection vulnerabilities, and incident readiness. When a finding turns up, it is fixed — not filed.

Incident Response Readiness

No system is entirely immune to incidents. What matters is how quickly and effectively an incident is contained and resolved.

We maintain documented incident response procedures for Maduuka, covering:

• Detection — through structured application and server logging that surfaces anomalous patterns, failed-login spikes, unusual data-export volumes, and other early-warning signals.
• Containment — specific, practised steps for credential compromise, unauthorised access, data exposure, and module-specific scenarios (for example, a cashier suspected of till fraud).
• Communication — protocols for notifying affected businesses promptly, with the specific information they need to act — not vague "an incident occurred" emails.
• Post-incident review — to close the underlying vulnerability, update the checklist, and prevent recurrence.

If something ever goes wrong, you will not be left to discover it from a customer or a newspaper. You will hear from us first, with specifics.

Honest Gaps — What We Are Still Improving

Every serious software team has a list of things that are good but not yet finished. We believe you are better served by a vendor who names those items directly than by one who hides them behind marketing language. So here they are.

• Transparent database-level encryption for PII fields. Passwords are already individually bcrypt-hashed. Full column-level transparent encryption for other PII (customer contact fields, employee national IDs) is the next major security milestone on our hardening roadmap — not a distant ambition, an active piece of work.
• Self-service GDPR / DPPA tooling. In the current release, data-subject requests and right-to-erasure actions are executed by a system administrator on receipt of a validated request. Automated self-service workflows are on the near-term roadmap; the manual process meets the letter of the law in the interim.
• External penetration test. Maduuka has undergone extensive internal security review throughout development. An independent third-party penetration test by a qualified security firm is scheduled as part of our compliance maturation work. We will publish a summary of findings and remediations once complete.
• ISO 27001 / SOC 2 certification. We already operate on ISO 27001-certified hosting infrastructure and apply controls aligned with both frameworks. Formal certification of Maduuka as an organisation is on the roadmap.
• Automated SAST/DAST in the CI pipeline. Dependency auditing via Composer and manual review currently cover this ground. Continuous automated scanning is a planned addition.

None of these items compromises the core security posture today — data in transit is fully encrypted, passwords are bcrypt-hashed, RBAC is enforced on every request, audit trails capture every change, and offsite backups run every three hours. But we name them explicitly so you can make an informed decision and so there are no surprises later.

Compliance Posture

Maduuka is designed to help the businesses on it meet their own compliance obligations, not just ours. In practical terms:

• Uganda's Data Protection and Privacy Act (2019) — we operate on the principles the Act codifies: lawful collection, purpose limitation, data minimisation, secure storage, and breach notification.
• URA and tax reporting — the reports Maduuka generates for VAT, PAYE, and NSSF are designed to match the formats URA and NSSF actually expect.
• NDA and pharmacy compliance — the pharmacy module logs controlled-drug dispensing, batch tracking, and expiry management in a form suitable for regulator inspection.
• Payment-related controls — for tenants processing card payments through integrated gateways, we align with PCI DSS scope-reduction practices by routing card data through certified processors rather than touching it ourselves.