# Locker Management System — Enhanced Feature Specification **Scope:** Admin Panel Only (staff use only — members never log in) **Hardware:** Physical lockers with traditional keys held by clients **Notifications:** Email + SMS + WhatsApp **Payments:** Cash / Manual + Local Bangladesh gateways (bKash, Nagad, SSLCommerz) **Stack:** React (frontend) + Laravel (backend) + MySQL This document takes your original feature list and adds the missing pieces a production-ready gym locker system needs. New features I'm suggesting are marked **[ADDED]**; features you already had are kept as-is or lightly expanded. --- ## 1. Client Management Module ### 1.1 Client Registration Add new clients with complete details: Full Name, Phone Number, Email Address, National ID / Passport (optional), Address, Notes / Remarks. **[ADDED] — recommended fields:** - Profile photo upload (so staff can identify clients at the desk) - Gender — important because gym lockers are zone-segregated (men's / women's / family) - Date of Birth — useful for age-based pricing or analytics - Emergency contact (name + phone) - ID document photo upload (NID/Passport scan) - Client signature capture (for terms acceptance) - Membership/Plan tier reference if the gym uses tiered memberships - Registration date (auto) - Referred by (optional — useful for marketing analytics) ### 1.2 Client Profile Management Edit client information, update contact details, delete or deactivate client accounts, view complete client history. **[ADDED]:** - Soft-delete (deactivate) vs. hard-delete — for compliance and audit, never permanently delete client records. Use status: Active / Inactive / Banned. - Client blacklist / ban flag with reason (for clients who repeatedly lose keys, damage lockers, etc.) - Tags/labels (e.g., "VIP", "Corporate", "Long-term") - Internal notes timeline (staff can leave dated notes on a client) ### 1.3 Client Search & Filtering Search by Name, Phone, Email, Locker Number. Advanced filters. **[ADDED]:** - Search by NID/Passport number - Filter by status (Active / Inactive / Banned) - Filter by gender / zone - Filter by registration date range - Filter by payment status (has dues / paid / overdue) ### 1.4 **[ADDED]** Bulk Import / Export - Import existing client list from CSV/Excel during initial setup - Export filtered client list to Excel/CSV --- ## 2. Locker Management Module ### 2.1 Locker Creation & Configuration Create unlimited locker entries, assign unique locker numbers/IDs, define category/type (Small, Medium, Large). **[ADDED]:** - **Locker Zone / Section** — Men's, Women's, Family, Staff, VIP. This is essential for a gym and should drive which clients can be assigned (filter by client gender). - **Floor / Room location** — useful for multi-floor gyms - **Physical key identifier** — every locker has a key tag/number. Track which physical key belongs to which locker. - Custom category beyond S/M/L (e.g., Day-use, Premium, Standard) - Configurable pricing per category × duration ### 2.2 Locker Assignment Assign lockers to specific clients, set assignment date and duration, auto-link locker with client profile. **[ADDED] — Key Handling Workflow (critical for your physical-key setup):** - **Key issued to client** — record that the physical key was handed over (timestamp + staff who handed it over) - **Key returned by client** — record return on cancellation/expiry - **Key deposit collected** — many gyms charge a refundable deposit for keys (e.g., ৳500). Track deposit amount and refund on key return. - **Lost key reporting** — if client loses key, log incident, deduct from deposit or charge replacement fee, mark old key as compromised, issue new key/lock. - Assignment requires gender-zone match (men's locker can only go to male client) — soft warning with override ### 2.3 Locker Status Tracking Real-time availability: Available, Assigned, Expired, Maintenance. **[ADDED]:** - **Reserved** — held for a client who hasn't yet paid - **Out of Service** — distinct from Maintenance (e.g., damaged beyond repair) - **Cleaning** — short-lived status while cleaning between rentals ### 2.4 Visual Locker Dashboard Grid-based locker visualization, color-coded status indicators, quick overview. **[ADDED]:** - Filter grid by zone, floor, size, status - Click locker → see current client + history without leaving the grid - Quick-action context menu on each locker tile (Assign / Release / Mark Maintenance) - Optional floor-plan layout view (Phase 2) ### 2.5 Locker History & Audit Track previous assignments, view client usage history, full activity records. **[ADDED]:** - Time-on-locker analytics (how long each rental lasted) - Number of distinct clients per locker (turnover rate) ### 2.6 **[ADDED]** Bulk Locker Operations - Bulk create lockers (e.g., "create 50 lockers, prefix M-, numbered 001-050, zone Men's, size Medium") - Bulk status change (e.g., mark a whole row as Maintenance) ### 2.7 **[ADDED]** Maintenance & Incident Log - Open a maintenance ticket against a locker (description, photo, priority) - Track ticket status: Open / In Progress / Resolved - Damage/incident report linked to client if applicable - Maintenance history visible from locker detail page ### 2.8 **[ADDED]** Lost & Found / Abandoned Items Log When a rental expires and the client doesn't return, staff need to open the locker and inventory the contents. Track: - Items found (description + photos) - Date locker was cleaned out - Storage location for items - Claim / disposal date --- ## 3. Expiry & Renewal Management ### 3.1 Expiry Date Management Set custom expiry dates, auto-calculate rental duration. **[ADDED]:** - Standard duration presets: Daily, Weekly, Monthly, Quarterly, Half-yearly, Yearly - Custom duration in days ### 3.2 Locker Renewal System Renew anytime, extend expiry instantly, maintain renewal history. **[ADDED]:** - One-click renew (uses same duration as last term) - Bulk renew for multiple clients at once - Renewal carries over discount/pricing rules ### 3.3 Expired Locker Monitoring Separate list for expired lockers, easy ID of overdue clients. ### 3.4 Upcoming Expiry Alerts Dashboard alerts, automated reminder system. **[ADDED]:** - Configurable reminder schedule (e.g., 7 days before, 3 days before, on the day, 3 days overdue) - Per-channel reminder rules (e.g., email at 7 days, SMS at 3 days, WhatsApp on day-of) ### 3.5 **[ADDED]** Grace Period - Configurable grace period after expiry (e.g., 3 days) before locker is considered abandoned and contents moved to Lost & Found --- ## 4. Payment & Billing Module ### 4.1 Locker Pricing Management Configure rental fees, different pricing per category. **[ADDED]:** - Pricing matrix: Category × Zone × Duration - Discount rules (e.g., 10% off for yearly, 5% off for corporate clients) - Promotional/coupon codes with expiry - Tax/VAT configuration ### 4.2 Payment Tracking Statuses: Paid, Due, Partial Paid, Overdue. **[ADDED]:** - Refunded - Cancelled - Pending (for online gateways awaiting confirmation) ### 4.3 Payment Collection Reports Daily / monthly / yearly summaries. ### 4.4 Due Payment Reports Pending dues, outstanding balance tracking. ### 4.5 Invoice & Receipt Generation Professional invoices, printable receipts, PDF download. **[ADDED]:** - Configurable invoice numbering (prefix, starting number, format) - Company logo, address, VAT/BIN number on invoice - Bengali + English bilingual invoice support - Auto-email invoice to client after payment ### 4.6 **[ADDED]** Payment Gateway Integration - **Cash / Manual** — staff records cash received, system prints receipt - **bKash Merchant API** — payment from client's bKash to gym's merchant account, with verification callback - **Nagad** — similar merchant flow - **SSLCommerz** — gateway aggregator covering cards + mobile banking + internet banking in Bangladesh - Each transaction stores: gateway, transaction ID, reference number, status, raw response (for audit) ### 4.7 **[ADDED]** Deposit & Refund Management - Separate ledger for key deposits (deposit is a liability, not revenue) - Auto-prompt to refund deposit on key return - Deduct lost-key fee from deposit before refund ### 4.8 **[ADDED]** Partial Payments & Payment Plans - Accept partial payment with auto-tracking of remaining balance - Optional installment schedule for long-duration rentals --- ## 5. Notification & Alert System ### 5.1 Client Registration Notification Automatic email after registration. **[ADDED]:** Also send welcome SMS / WhatsApp with gym info, hours, locker rules. ### 5.2 Locker Assignment Notification Email upon assignment. **[ADDED]:** Multi-channel — Email + SMS + WhatsApp with locker number, key number, expiry date, and gym hours. ### 5.3 Expiry Reminder Notifications Automated reminders before expiry. **[ADDED]:** - Multi-stage reminders (configurable: 7d, 3d, 1d, on expiry, 3d overdue) - Per-channel templates (SMS short, WhatsApp rich with payment link, email formal with invoice) ### 5.4 Admin Dashboard Alerts Real-time expiry and due payment notifications. ### 5.5 **[ADDED]** Notification Templates Management - Editable templates for each notification type (registration, assignment, reminder, payment, overdue) - Variables/placeholders ({{client_name}}, {{locker_number}}, {{expiry_date}}, {{amount}}) - Bilingual templates (Bengali + English) with auto-selection based on client preference ### 5.6 **[ADDED]** Notification Delivery Log - Track every notification sent (channel, recipient, content, status: sent/failed/delivered) - Retry failed notifications - Cost tracking for SMS/WhatsApp (these have per-message fees) ### 5.7 **[ADDED]** Gateway Configuration - SMS gateway settings (e.g., SSL Wireless, Banglalink, Robi) - WhatsApp Business API credentials - SMTP / email settings --- ## 6. Reports & Analytics ### 6.1 Dashboard Statistics Total Lockers, Assigned, Available, Expired, Due Payments, Total Revenue. **[ADDED]:** - Occupancy rate (%) overall and by zone - Monthly revenue trend chart - New clients this month - Renewal rate (% of expiring rentals that get renewed) - Top 10 longest-tenured clients ### 6.2 Report Export System Export to Excel, PDF, CSV. ### 6.3 Financial Reporting Revenue reports, payment history, due collection summaries. **[ADDED]:** - Revenue breakdown by zone / size / duration - Payment method breakdown (cash vs. bKash vs. Nagad vs. SSLCommerz) - Deposit ledger report - Refund report - Tax/VAT report (if applicable) ### 6.4 **[ADDED]** Operational Reports - Locker utilization heatmap (which lockers get the most use) - Maintenance frequency per locker (which lockers need replacement) - Lost-key incidents per client (identifies problem clients) - Average rental duration ### 6.5 **[ADDED]** Client Reports - Client retention rate - Inactive clients (eligible for re-engagement) - Top-paying clients --- ## 7. Security & System Management ### 7.1 Activity Log System Track all admin activities, login history, changes. **[ADDED]:** - IP address logging - Browser/device info - Filterable activity log (by user, by action type, by date range) - Export activity log to CSV for audit ### 7.2 Data Backup & Recovery Automatic database backup, restore functionality. **[ADDED]:** - Configurable backup schedule (daily/weekly) - Offsite backup option (cloud storage upload) - One-click restore from a backup point - Backup retention policy (keep last N backups) ### 7.3 Secure Authentication Admin login protection, password encryption, session management. **[ADDED]:** - **Two-Factor Authentication (2FA)** via SMS or authenticator app for admin login — strongly recommended even for admin-only systems - Failed login attempt lockout (e.g., 5 failed → lock for 15 min) - Password complexity rules + expiry policy - Forced logout of all sessions on password change ### 7.4 Role-Based Access Control Multiple admin roles, permission-based access. **[ADDED] — recommend including in MVP, not as future upgrade:** - Suggested roles: - **Super Admin** — everything including settings, user management, financial reports - **Manager** — everything except super-admin settings - **Front Desk / Receptionist** — register clients, assign lockers, collect payments, view their own activity - **Accountant** — view financial reports, no client/locker modification - Granular permissions per module (view / create / edit / delete) ### 7.5 **[ADDED]** Data Privacy - Client data export on request (NID, photos, all PII) - Client data deletion request workflow with retention rules - Consent log (when client agreed to T&Cs) --- ## 8. Additional Advanced Features ### 8.1 Responsive Admin Panel Mobile, tablet, desktop friendly. ### 8.2 Dark / Light Mode UI ### 8.3 Advanced Search & Sorting Smart filtering for clients, lockers, payments. ### 8.4 System Settings Panel Configure: Company info, Currency, Email settings, Notification settings. **[ADDED] settings:** - Default timezone (Asia/Dhaka) - Default language (Bengali / English) - Working hours / holiday calendar - Default locker rental durations + prices - Reminder schedule (days before expiry) - Grace period after expiry - Key deposit amount - Lost-key fee - Tax/VAT rate - Invoice numbering format ### 8.5 Multi-Branch Support (Future) Manage multiple locations. ### 8.6 **[ADDED]** Quick Actions / Keyboard Shortcuts For front-desk speed: "Cmd/Ctrl+K" → quick search any client, locker, payment. Front-desk staff handle dozens of clients an hour; this saves real time. ### 8.7 **[ADDED]** Bilingual UI (Bengali + English) Toggle between Bengali and English in the admin panel. Important for Bangladeshi gyms where some staff are more comfortable in Bengali. ### 8.8 **[ADDED]** Printable Client Card Generate a printable / QR-coded client card with name, photo, member ID, locker number — useful for the gym to issue as a physical card. ### 8.9 **[ADDED]** Terms & Conditions / Liability Waiver Configurable T&C text shown at registration with a captured signature/timestamp for legal protection. --- ## 9. Suggested Module Structure (Backend) This is the Laravel module organization that maps to the features above: 1. **Authentication Module** (Sanctum-based admin auth + 2FA) 2. **Dashboard Module** 3. **Client Management Module** 4. **Locker Management Module** (lockers, zones, keys, maintenance, lost & found) 5. **Rental & Renewal Module** (assignment lifecycle, expiry, grace period) 6. **Payment & Billing Module** (pricing, invoices, gateway integrations, deposits) 7. **Notification Module** (templates, multi-channel dispatcher, delivery log) 8. **Reports Module** (financial + operational + client reports + exports) 9. **Settings Module** (company info, pricing rules, reminder rules, gateways) 10. **User & Role Management Module** (RBAC) 11. **Activity Log Module** 12. **Backup Module** --- ## 10. Recommended Tech Stack (aligned with your project) - **Frontend:** React 18 + Vite + TailwindCSS + a component library (recommend **shadcn/ui** or **Ant Design** — both have excellent admin/dashboard primitives) - **State management:** React Query (server state) + Zustand or Context (UI state) - **Forms:** React Hook Form + Zod for validation - **Charts:** Recharts or Chart.js for analytics dashboards - **Backend:** Laravel 11+ with PHP 8.2+ - **API:** REST JSON, versioned (`/api/v1/...`) - **Authentication:** Laravel Sanctum (cookie-based SPA auth — see research doc for rationale) - **Database:** MySQL 8 (or MariaDB) - **Queues:** Laravel Queues (Redis driver) — essential for sending SMS/WhatsApp without blocking the UI - **PDF Generation:** **barryvdh/laravel-dompdf** (simpler) or **Spatie Browsershot** (better Bengali font rendering — recommended) - **Excel/CSV Export:** **Maatwebsite/Laravel-Excel** - **Email:** SMTP or transactional service (SendGrid, Mailgun) - **SMS:** SSL Wireless / Banglalink / Robi gateway integration via simple HTTP - **WhatsApp:** WhatsApp Business Cloud API (Meta) or a BSP like Twilio - **Payments:** Direct SDK integration for bKash Merchant API, Nagad, SSLCommerz - **Backup:** **Spatie/Laravel-Backup** package — covers DB + files + cloud upload + scheduling - **Activity Log:** **Spatie/Laravel-Activitylog** - **RBAC:** **Spatie/Laravel-Permission** (Your original list mentioned "PHP Laravel or Node.js" and "HTML, CSS, Bootstrap/Tailwind" — I've aligned everything above with your project setting of **React + Laravel**.) --- ## 11. Recommended Build Sequence Don't build everything at once. Suggested phases: **Phase 1 — Core MVP (4–6 weeks)** Auth + RBAC, Clients, Lockers, Locker assignment + key tracking, Manual cash payments, Invoice/receipt PDF, Basic dashboard, Email notifications, Activity log. **Phase 2 — Operations (2–3 weeks)** Renewals + expiry reminders, SMS + WhatsApp notifications, Maintenance + Lost & Found, Bulk operations, Advanced reports + exports. **Phase 3 — Online Payments (2 weeks)** bKash + Nagad + SSLCommerz integration, deposit ledger, refunds. **Phase 4 — Polish (1–2 weeks)** Dark mode, bilingual UI, keyboard shortcuts, backup automation, 2FA, printable client cards. **Phase 5 — Future** Multi-branch, floor-plan view, smart-lock hardware (if ever needed), member self-service portal. --- ## Summary of What I Added The most important suggested additions to your original list: The first and biggest is **physical key management** (deposit, issue, return, lost-key handling) — your business model uses physical keys, so this needs its own first-class workflow. Second, **gender-segregated zones** for lockers since this is a gym — without this, the system can't correctly enforce men's vs. women's locker rooms. Third, **multi-channel notifications** (Email + SMS + WhatsApp) with delivery logging and templates, since you confirmed all three channels matter for the Bangladeshi market. Fourth, **local payment gateways** (bKash, Nagad, SSLCommerz) properly integrated with transaction logging and deposit ledger separated from revenue. Fifth, **RBAC in MVP** rather than future scope — even a small gym has more than one staff member, and you don't want the receptionist seeing financial reports or deleting clients. Sixth, operational features your list was missing: **maintenance tickets, lost & found, bulk operations, grace period, partial payments, 2FA, bilingual UI, and printable client cards** — all things a real gym front desk needs day-to-day.