Complete Feature Showcase

💡 About the Application

OneBill is a multi-tenant billing & inventory SaaS built for small retail shops, kirana stores, boutiques, and similar businesses. It gives every shop owner an end-to-end back-office — from product catalog and barcode scanning to checkout, inventory, expenses, multi-store reporting — wrapped in a role-based app with a Super Admin → Admin → Owner → Worker hierarchy.

🎯 What Owners Get

• A POS / checkout system that prints 58mm or 80mm thermal receipts.
• Catalog & inventory with GST, HSN, multi-store stock, and batch/expiry tracking.
• Customer ledger with loyalty points and reminders.
• Expenses, bank accounts, suppliers, and staff with attendance.
• Reports for sales, P&L, inventory, staff performance, and stores comparison.
• Multi-worker support with per-worker module grants.
• Subscription-gated modules so customers pay only for what they use.

🏗️ Who Uses It

• Super Admin — owner of the platform (manages admins & platform settings).
• Admin — onboarding operator who creates owner tenants & manages their plans.
• Owner — the shopkeeper / tenant running the business.
• Worker — cashier / staff at the shop counter.
• Public — visitors for registration, login, password reset.

🛠️ Design Goals

• Modular by design — every feature is a module that can be toggled per tenant.
• Multi-tenant safe — strict owner_id scoping across every query.
• Secure by default — JWT with server-side session revocation, bcrypt, Fernet at rest, CSRF, CSP, rate limiting.
• Fast at the counter — barcode scanning, atomic stock reservation, instant checkout.
• Operable — Docker-ready, async Motor, audit logs, admin activity logs.

📌 User Types at a Glance

👑 Super Admin Features

🔐 Authentication & Account

• Log in to the platform with bootstrap credentials.
• Forced first-run change-password flow.
• Manage personal profile, sessions, and password.

👥 Admin Management

🗺️ Tracking & Oversight

• Track Map — visual hierarchy: Super Admins → Admins → Owners → Workers.
• View all admins, all owners (with assigned admin), and all workers (with assigned owner).
• Owner / admin relationship graph for accountability.

⚙️ Platform Settings

• Default modules enabled for new owners.
• Platform branding / configuration.
• Global toggles and defaults (/super-admin/settings).

🧩 Admin Module Grants

• Grant / revoke admin-only modules to plain admins.
• owner_stats — detailed statistics drawer.
• alerts — send and manage alerts to owners.
• Plain admins only see owners they have been granted access to.

🔒 Permissions

• All system modules (auth, profile, subscription, sessions, dashboard).
• All business modules (full business bypass).
• All admin modules.

🛠️ Admin Features

🧑‍💼 Owner (Tenant) Onboarding

🧩 Manage Owner Module Access

• Enable / disable modules for any owner they manage.
• Toggle business modules: products, inventory, sales, customers, expenses, bank, reports, stores, suppliers, staff, alerts, batches.
• Audit log of all grant changes.

📊 Owner Statistics

• Detailed owner stats per owner.
• Sales totals, expenses, profit.
• Product count, customer count, worker count.
• Active sessions and subscription status.

🔔 Alerts Management

• Send alerts/notifications to their owners (requires alerts module).
• Configure alert rules and view history.
• Stock and business alerts dispatched via SMTP / WhatsApp.

💳 Subscription Management

• Grant subscription to an owner (plan, start, end date).
• Renew subscription for an owner.
• View subscription status: active · expired · grace.
• Invoices, plan tier, expiry date, grace window.

📜 Activity & Tracking

• Personal admin activity log.
• View list of owners they created and manage.
• View track map (admins → owners → workers).

🔒 Permissions (Default)

• All system modules + all business modules (business bypass).
• Does not automatically have admin modules — must be granted by Super Admin.

🏪 Owner Features

🖨️ Print Settings (58mm / 80mm)

• Header note, footer note, thank-you message on receipt.
• Paper size: 58mm or 80mm.
• Settings inherited by all workers (used at receipt printing).

🛡️ Security & Recovery

• Forced change-password-required flow on first login.
• Password reset via tokenized email link.
• Active session monitoring and revocation.

🔒 Permissions

• All system modules (always): auth, profile, subscription, sessions, dashboard.
• Business modules per module_grants (default = LAUNCH_CATALOG_KEYS for fresh accounts).

🧑‍💻 Worker Features

🚫 What Workers Cannot Access

🌐 Public / Guest Features

🔐 Authentication

🛡️ Security Layers Seen by Guest

• Login rate limiting (slowapi per-IP).
• Account lockout after failed attempts.
• CSRF protection (double-submit cookie pattern).
• CSP enforced; security headers applied.

🔒 Cross-Cutting System Features

These run across the platform regardless of role.

⚡ Database Operations / sec (Estimated)

Realistic per-shop baseline estimates for a single tenant operating at moderate retail throughput (one busy checkout counter). Values represent peak ops/sec against MongoDB (Motor async driver). Reads are separate from writes; totals include both.

📊 Per-Module Throughput

👤 Per-User Ops / sec

Each role drives a different mix of modules. Click a tab to see the DB load attributable to a single active user of each type, plus the per-endpoint breakdown of which APIs they primarily hit.

📦 User-to-Tenant Multiplier

🧮 Aggregate Throughput

🚀 Hotspot Write Collections

• sales — peak 2 – 4 writes/sec per shop. Indexed by owner_id, created_at, store_id, customer_id.
• stock_movements — 1 – 3 writes/sec per shop from atomic stock reservation.
• audit_log & admin_activity — bursty, low-rate but append-heavy.
• sessions — periodic refresh on every protected request.

🔌 Backend Mitigations

• Async Motor driver — non-blocking I/O across thousands of concurrent ops.
• Compound indexes on (owner_id, created_at) for tenant-scoped queries.
• React Query cache on the frontend — deduplicates reads within TTL.
• Rate limiting (slowapi) — bounds burst spikes per IP.
• Connection pooling on MongoDB Atlas.
• Webhook & alert dispatch moved off the request path where possible.

📋 Module Catalog (Reference)

Authoritative module list lives in backend/app/models/module.py.

System Modules (always on, FR-003)

Business Modules (per-tenant toggleable, FR-002)

Admin Modules (superadmin-grantable to plain admins)

🎬 Demo Flow Suggestions

A typical demo could walk through:

1. Public → Register / Login as a new user.
2. Super Admin → Bootstrap, create Admin, review Track Map.
3. Admin → Create Owner (tenant), grant modules, send welcome alert, renew subscription.
4. Owner → Add products, configure print settings, add workers, set per-worker modules, perform a sale, view reports.
5. Worker → Login, scan barcode, complete a sale, view own sales history.
6. Owner → View worker activity in reports, run P&L, manage inventory alerts.