Accounts, Financial Ledgers & User Identity Management

This comprehensive handbook governs all aspects of accounts across Eniceberny Bakery and Culinary Hub — spanning customer self-service accounts, staff role access accounts, financial accounting ledgers, cash drawer reconciliation, invoicing, and statutory tax compliance.

---

🧭 Architecture of the Accounts Subsystem

graph TD
    subgraph Identity & Access
        UA[User Accounts] --> CR[Customer Accounts /account]
        UA --> SA[Staff Accounts /admin/users]
        SA --> RBAC[Role-Based Access Control]
    end

    subgraph Commerce & Receivables
        CR --> CO[Storefront Orders]
        CO --> AR[Accounts Receivable / Invoices]
        Q[Catering Quotes] -->|Convert| CO
    end

    subgraph Financial Ledgers
        CO --> PT[Payment Transactions]
        POS[Counter POS] --> PT
        PT --> GL[(Unified Payment Ledger)]
        GL --> CRD[Cash Drawer Balancing]
        GL --> MMR[MoMo Reconciliation]
        GL --> PSR[Paystack Settlements]
        GL --> DSS[Daily Sales Summary]
    end

---

1. Customer User Accounts (/account)

Customer accounts provide our patrons with a personalized, secure commerce portal.

1.1 Account Dashboard (/account)

Upon logging in at /login, patrons land on the executive customer dashboard displaying live statistics:

• Total Orders: Lifetime count of orders placed across web and counter channels.
• Pending Orders: Orders currently being confirmed, baked, or en route.
• Completed Orders: Orders safely delivered or collected.
• Lifetime Spend: Total Ghanaian Cedis (GH₵) settled by the customer.
• Unpaid Balance Alert: If an active order or invoice balance is pending payment, an amber notification card is displayed with an instant "Settle Balance" link.

1.2 Address Book & GhanaPostGPS Coordinates (/account/addresses)

To eliminate delivery friction, the address book manages multi-location fulfillment profiles:

• Button: "Add New Address": Opens the address modal to capture:
  • Recipient Name & Primary Phone: Recipient at delivery location.
  • Street Address & Locality: House or office number, street name, suburb (e.g. Ahodwo, Kumasi).
  • Notable Landmark: Visual cues for dispatch couriers (e.g. Opposite Shell Station, blue gate).
  • GhanaPostGPS Digital Address: Official National Digital Address (e.g. AK-039-2311).
  • Geographic Coordinates: Latitude and Longitude for map-pin navigation.
  • Address Type: Delivery vs Billing.
  • Button: "Save Address": Persists the record and marks as default if it is the user's first address.
• Button: "Set as Default": Designates the primary address pre-filled during checkout.
• Button: "Edit" / "Delete": Updates or safely purges stale delivery addresses with audit logging.

1.3 Culinary & Dietary Preferences (/account/settings)

Patrons can configure tailored culinary profiles stored in JSON (customer_profiles.preferences):

• Dietary Tags: Select checkboxes for Vegetarian, Nut Allergy, Lactose Intolerant, Halal, or Gluten Sensitivity.
• Allergy Notes: Freeform textarea for kitchen instructions (e.g. "Severe peanut allergy — please sterilize bake trays").
• Delivery Instructions: Default delivery note (e.g. "Call when at security gate").
• Notification Preferences: Toggles for WhatsApp updates, SMS dispatch alerts, and Email order summaries.
• Button: "Update Culinary Preferences": Saves preferences atomically with audit logging.

1.4 Security & Password Changes

• Current Password Verification: Required to authorize any credential modification.
• Password Strength Rules: Minimum 8 characters, confirmed with matching repeat field.
• Automated Security Email: A notification email (PasswordChangedMail) is automatically dispatched to the customer's verified inbox immediately upon password update.
• Button: "Save New Password": Hashes the new credential with Bcrypt and terminates unauthorized sessions.

---

2. Staff Accounts & Granular Role Permissions (/admin/users)

Access to the administrative back-office and Point of Sale register is strictly governed by authenticated staff accounts.

2.1 Role Hierarchy & Permissions Matrix

Role Enum (UserRole)	Display Label	Scope & Permissions	Target Personnel
super_admin	Super Administrator	Full platform control: settings, financial reports, user provisioning, database audits, secret keys	Managing Director, Lead Software Architect
admin	Administrator	Catalog management, customer accounts, order processing, quote approval, broadcasts	Store General Manager, Operations Head
manager	General Manager	Kitchen queue oversight, inventory adjustments, quote drafting, daily reports	Floor Supervisor, Assistant Manager
order_manager	Order Fulfillment Manager	Kitchen display dispatch, order status progression, rider assignments	Dispatch Lead, Kitchen Expediter
cashier	Cashier / POS Operator	Counter register (/admin/pos), cash tender calculation, receipt printing, customer lookup	Front Desk Cashiers
kitchen_staff	Chef / Kitchen Staff	Read-only kitchen display, preparation status flags, recipe notes	Pastry Chefs, Line Cooks
content_manager	Content & Media Manager	CMS homepage sections, banners, gallery uploads, FAQs, blog articles	Marketing Officer, Graphic Designer
customer	Valued Customer	Public storefront browsing, cart, checkout, personal invoice payment, account settings	Patrons, Corporate Clients

2.2 Staff Account Provisioning Workflow

1. Navigate to /admin/users and click "Create Staff Account".
2. Complete the staff profile form:
   • Full Name: Legal name of employee.
   • Work Email: Official email address for authentication and OTP verification.
   • Phone Number: Primary mobile contact for urgent operational escalations.
   • Assigned Role: Select from the dropdown menu (e.g. Cashier / POS Operator).
   • Initial Temporary Password: Strong generated password.
   • Active Status: Set to Active (toggle switch).
3. Click "Save Staff Member".
4. The system logs user.created in audit_logs including operator ID and IP address.

2.3 Staff Offboarding & Deactivation

• To immediately revoke back-office and POS terminal access, open the staff member profile and toggle Active Status to Inactive or click "Suspend Account".
• All active sessions for the user are invalidated instantly. Soft deletes preserve historical sales attribution.

---

3. Financial Accounting, Ledgers & Reconciliation

Eniceberny maintains an immutable, multi-channel financial ledger tracking every pesewa across Cash, Mobile Money, Bank Cards, and Invoices.

3.1 Daily Cash Drawer Float & Balancing SOP

sequenceDiagram
    autonumber
    actor Cashier
    participant Terminal as POS Terminal (/admin/pos)
    participant Supervisor as Shift Supervisor
    participant Ledger as Reports & Ledgers (/admin/reports)

    Cashier->>Supervisor: Receive Starting Cash Float (GH₵ 200.00)
    Cashier->>Terminal: Sign in to POS Register
    Note over Cashier,Terminal: Process walk-in sales throughout shift
    Cashier->>Cashier: Count physical cash drawer at shift close
    Cashier->>Supervisor: Present Cash Drawer Handover Slip
    Supervisor->>Ledger: Compare Physical Cash vs System total_cash
    alt Variance == 0.00
        Supervisor->>Ledger: Sign off Balanced Shift
    else Variance != 0.00
        Supervisor->>Ledger: Record Discrepancy Note in Shift Audit
    end

Step-by-Step Balancing Protocol:

1. Shift Opening (07:30 GMT):

   • The Shift Supervisor dispenses a standard physical cash float of GH₵ 200.00 in small denominations:
     • 10 × GH₵ 5 notes (GH₵ 50.00)
     • 10 × GH₵ 10 notes (GH₵ 100.00)
     • 2 × GH₵ 20 notes (GH₵ 40.00)
     • 1 × GH₵ 10 coin pack (GH₵ 10.00)
   • Cashier verifies the count and signs the Register Opening Log.

2. Mid-Shift Petty Cash Payouts:

   • If emergency cash is disbursed from the register (e.g. local supply run or ice delivery), a formal Petty Cash Voucher must be signed by the Supervisor and placed inside the cash drawer.

3. Shift Closing & Drawer Count (21:30 GMT):

   • Total physical banknotes and coins are counted and recorded.
   • The formula for reconciliation is: $$\text{Expected Physical Cash} = \text{Opening Float (GH₵ 200.00)} + \text{Total Cash Sales} - \text{Authorized Petty Cash}$$
   • Open /admin/reports?source=pos&payment_method=cash for the current date to obtain the exact total_cash system figure.
   • Variance Resolution:
     • Balanced: Expected Cash matches actual count.
     • Cash Over (Surplus): Excess cash is booked as unallocated revenue.
     • Cash Short (Deficit): Shortage requires cashier incident report and managerial sign-off.

---

4. Multi-Channel Payment Ledgers & Reconciliation

The platform records all settlements in the payment_transactions table:

SELECT 
    pt.transaction_reference,
    pt.gateway,
    pt.amount,
    pt.currency,
    pt.status,
    pt.paid_at,
    o.order_number,
    o.customer_name
FROM payment_transactions pt
JOIN orders o ON pt.order_id = o.id
ORDER BY pt.paid_at DESC;

4.1 Payment Gateway Channels & Reconciliation Procedures

Channel	Gateway Key	Settlement Window	Verification Method	Reconciliation Frequency
Physical Cash	cash	Instant (In drawer)	Physical count vs POS cash sales	Daily at shift handover
MTN Mobile Money	momo / paystack	Instant to 24 hours	Telecom merchant portal SMS + Paystack transaction ID	Daily at 22:00 GMT
Telecel Cash	momo / paystack	Instant to 24 hours	Telecel merchant portal + Paystack reference	Daily at 22:00 GMT
Visa / Mastercard	card / paystack	T+1 Business Day	Paystack payout settlement batch to Stanbic/GCB bank account	Daily bank statement sync
Corporate Wire / Cheque	invoice	7 – 14 Days Net	Official bank credit advice / cleared cheque	Weekly on Fridays

4.2 Paystack Automated Settlement Verification

• When an online or invoice payment completes, Paystack dispatches a cryptographically signed HMAC SHA512 webhook to /webhooks/paystack.
• The webhook payload updates payment_transactions to status = 'success', updates orders.payment_status to 'paid', and stamps paid_at = now().
• If an unverified transaction occurs (e.g. customer's network drops before redirect), the admin can click "Verify Gateway Transaction" on /admin/orders/{id} to query Paystack's REST API /transaction/verify/:reference directly.

---

5. Accounts Receivable, Public Invoices & Debt Collection (/invoices)

For telephone orders, corporate catering, or delayed settlements, Eniceberny provides an online billing and invoice collection portal.

5.1 Public Invoice Lookup (/invoices)

Patrons or corporate procurement officers can retrieve invoices without requiring a user password:

1. Visit https://enicebakerygh.com/invoices.
2. Enter the Order Number (e.g. EB-20260927-1402) or the billing Phone Number.
3. Click "Search Invoice".
4. The system renders the invoice summary card detailing:
   • Line items with portion sizes and quantities.
   • Subtotal, delivery charges, discounts, and VAT/levy totals.
   • Total Amount Settled (GH₵) and Outstanding Balance Due (GH₵).

5.2 One-Click Digital Balance Settlement

• If an invoice has an outstanding balance, the customer clicks "Pay Online Now".
• The system routes the user to the secure Paystack checkout modal where they can settle via MTN MoMo, Telecel Cash, or Visa/Mastercard.
• Upon successful payment, the invoice updates instantly to PAID, issues an official receipt PDF with embedded QR code, and sends an SMS/Email receipt.

---

6. Catering & Banquet Deposit Schedules (/admin/quotes)

Corporate and high-volume catering bookings adhere to a structured 2-phase milestone schedule:

stateDiagram-v2
    [*] --> InquiryReceived: Patron submits /catering form
    InquiryReceived --> ProposalDrafted: Admin creates Quote (/admin/quotes/create)
    ProposalDrafted --> QuoteSent: Quote sent via PDF / Email
    QuoteSent --> DepositPaid: Client pays 50% Milestone Deposit
    DepositPaid --> OrderConverted: One-click conversion to Order
    OrderConverted --> KitchenPrep: Staging & Chef Prep
    KitchenPrep --> FinalSettlement: Remaining 50% paid 48h prior to event
    FinalSettlement --> EventDelivered: Banquet execution
    EventDelivered --> [*]

1. Phase 1: Milestone Deposit (50%):
   • Required upon client quotation acceptance to lock kitchen capacity and reserve event dates.
   • Recorded as a partial payment on the converted catering order.
2. Phase 2: Final Balance (50%):
   • Due 48 hours prior to event staging.
   • Payable via the public invoice portal (/invoices/{orderNumber}) or bank transfer.

---

7. Financial Reporting, Analytics & CSV Export (/admin/reports)

The reporting suite empowers management with actionable intelligence and automated audit exports.

7.1 Key Analytical Metrics

• Gross Revenue: Total monetary value of all orders marked payment_status = paid.
• Average Order Value (AOV): Calculated as: $$\text{AOV} = \frac{\text{Total Paid Revenue}}{\text{Total Paid Orders}}$$
• Mobile Money Share (%): Percentage of gross revenue captured via MTN MoMo and Telecel Cash versus Cash and Card.
• Channel Breakdown: Revenue split between Online Storefront (web) and In-Store Counter (pos).
• Top 10 Bestselling Delicacies: Volume and revenue ranking to drive kitchen prep planning.

7.2 Automated Daily Sales Summary (daily_sales_summaries)

At the conclusion of each trading day, an automated ledger job aggregates daily performance into daily_sales_summaries:

• summary_date: Date of trading.
• total_orders: Number of completed tickets.
• total_sales: Gross daily revenue.
• total_cash: Total cash tendered.
• total_momo: Total mobile money transactions.
• total_card: Total card transactions.
• total_pos: Total in-store sales volume.
• total_online: Total storefront web volume.

7.3 Streaming CSV Export for Accounting Software

Financial accountants can export raw transaction records for import into QuickBooks, Sage, or Microsoft Excel:

1. Open /admin/reports.
2. Select desired date filters: From Date and To Date.
3. Filter by Channel (All, Web, POS), Payment Method (Cash, MoMo, Card), or Payment Status (Paid, Pending).
4. Click "Export CSV" (/admin/reports?export=csv).
5. The system streams a high-speed UTF-8 BOM CSV response with the filename format: eniceberny-sales-report-YYYY-MM-DD-HHMMSS.csv.
6. Includes full column breakdown: Order Number, Date, Customer Name, Phone, Channel, Order Type, Payment Method, Payment Status, Subtotal, Discount, Delivery Fee, and Line-by-Line Total.

---

8. Ghana Tax & Regulatory Compliance (GRA & Act 843)

8.1 Ghana Revenue Authority (GRA) Tax & Levies

Eniceberny's financial parameters in /admin/settings (Card 6) allow dynamic configuration of statutory levies:

• Value Added Tax (VAT): Configurable standard rate applied to catering and retail goods.
• National Health Insurance Levy (NHIL): 2.5% statutory contribution.
• Ghana Education Trust Fund (GETFund): 2.5% statutory contribution.
• COVID-19 Health Recovery Levy: 1.0% statutory levy where applicable.
• Itemized tax amounts are stored in orders.tax_amount and rendered on all formal PDF invoices and receipts.

8.2 Data Privacy & Financial Audit Trail (Act 843)

• Under the Data Protection Act, 2012 (Act 843), all payment details (such as Mobile Money numbers and customer addresses) are stored securely with encrypted communication.
• Audit logs capture every financial status change, refund, and price modification in audit_logs with the operator ID, timestamp, and client IP address.

---

For technical integration details or payment gateway webhooks, consult the Payment Systems Guide and REST API Guide.