Shafaq Marquee — Booking Management System
Project Overview
Shafaq Marquee Management System is a production-grade, full-stack ERP platform built entirely in Python (Flask) for a live marquee/banquet hall business in Pakistan. The system is deployed at shafaqmarquee.com and runs on a cPanel shared host with SQLite as its database engine.
This is not a demo or prototype — it is actively used to manage real bookings, real payments, real salaries, and real accounting for a marquee hall business. The system handles everything from online customer inquiries on the public website to double-entry Journal Voucher closings in the admin panel, with ZKTeco biometric attendance integration from an office PC.
All 25+ Application Modules
Each module is a separate Flask Blueprint with its own URL prefix, routes, forms, and templates:
Complete Feature Modules
Booking Engine
Create and manage hall bookings with event type, date, time slots, guest count, and booking mode (whole hall / per-head). Conflict prevention and status tracking (pending → confirmed → completed).
Hall Management
Manage multiple halls with capacity, area (sqft), location, hall type (indoor/outdoor), amenities, base price, per-head pricing, and min/max guest limits.
Catering Orders
Standalone catering orders separate from bookings. Supports menu items, packages, external delivery services, discount logic, advance payments, and status tracking (pending → delivered).
Menu & Packages
Define individual menu items and pre-built packages with pricing, discounts, and quantities. Attach menu packages to bookings as BookingMenuItems with per-head calculation.
Employee HR Module
Full employee records with position, salary, hire date, ZKTeco device ID for biometric attendance sync. Supports regular employees and temporary workers (is_temp_worker flag).
Salary Processing
Monthly salary calculation: base × (attendance days / total days) + bonuses − deductions − advance deductions. Salary advance tracking with partial/full deduction logic.
Attendance System
Track daily attendance (present, absent, late, half-day) with check-in/out times. Biometric sync via ZKTeco bridge — office device pushes data to live server automatically.
Commission Tracking
Track commissions both payable (to employees/parties) and receivable. Commission can be percentage-based per booking or standalone. Linked to cash/bank account for payment.
Inventory & Stores
Multi-store inventory (general, meat, vegetables). Track current stock, min stock levels, daily consumption. Purchase orders from suppliers update stock automatically.
Daily Weight Records
Record morning/evening weights for food items. Track used weight and waste weight daily. Enables food cost analysis and consumption reporting per booking event.
Supplier Ledger
Full double-entry supplier accounts: purchases increase payable (credit), payments decrease payable (debit). Running balance, credit notes, debit notes, and payment allocation.
Partner / Investor Ledger
Track money received from investors, equity investments, profit share distributions, and repayments. Separate from operational accounts — partners are investors/owners/lenders.
Cash & Bank Accounts
Multiple cash/bank accounts with opening balances. Every financial transaction generates an AccountTransaction (debit = money out, credit = money in) for complete audit trail.
Double-Entry Accounting
Full chart of accounts with AccountTransaction ledger. Journal Vouchers (JV) with numbered entries (JV-202601-001). Monthly P&L closing with profit transfer to account or partner.
Financial Reports
Largest module (346KB routes file): Profit & Loss statements, Balance Sheet, Trial Balance, Supplier statements, Employee reports, Booking analytics, and Cash flow summaries.
Asset Management
Track physical assets (tents, chairs, generators, lights) by category, condition, location. Assign assets to bookings, track returns, record maintenance schedules and damage.
Role-Based Access Control
RBAC with Roles (Admin, Manager, Staff, Accountant) + granular Permissions per module. Users can have role-based AND direct permissions. Every admin route is permission-guarded.
Public Website CMS
Admin-controlled public website content: hall media gallery (images + YouTube videos), customer reviews (with approval workflow), inquiry form, and key-value website settings.
Complete Booking Workflow
Customer submits inquiry via the public website contact form — captured as an Inquiry record in the database.
Admin checks hall calendar for conflicts. Hall pricing fetched based on booking mode (whole hall vs. per-head).
Booking record created with hall, customer, event date/time, guest count, menu selection, fees (hall, menu, generator, AC), and discount calculation.
Payment record saved → AccountTransaction entry (credit) in the selected cash/bank account automatically.
Staff assigned via StaffAssignment, physical assets (chairs, tents) allocated via AssetAssignment, temporary workers added via TemporaryWorkerPayment.
EventPurchase records created for supplier purchases linked to this specific booking. Each updates the SupplierLedger.
Remaining balance collected, booking status set to completed. Commissions auto-generated. P&L closing includes this booking's revenue.
Database Architecture — Key Tables
The SQLAlchemy ORM models define 40+ database tables with full relational integrity. Key tables:
Double-Entry Financial System
The accounting engine implements proper double-entry bookkeeping — every financial transaction creates matching debit and credit entries across the system:
- Revenue Sources: Hall rental, menu pricing, generator fee, AC fee, catering orders, commissions received.
- Expense Tracking: Salaries, event purchases, supplier invoices, temp worker payments, manual expenses, commissions paid.
- Monthly Closing: One closing per month (unique constraint). Net profit transferred to a cash/bank account OR directly to a partner/investor ledger.
- Journal Vouchers: Auto-generated JVs for revenue closing, expense closing, and profit transfer — each must be balanced (debit == credit).
External Integrations
- ZKTeco Biometric Attendance: Office PC runs a bridge service (
integrations_attendance.py) that pollsAttendanceBridgeStateand pushes fingerprint attendance records from the ZKTeco device to the live server via HTTPS. Employees matched byzk_device_user_id. - Mobile Web App: A dedicated mobile blueprint serves a PWA-style web interface for staff/managers to access key functions from smartphones without installing an app.
- cPanel Deployment: The Flask application runs on shared cPanel hosting under
shafaqmarquee.com. SQLite database with automatic migrations via Flask-Migrate and Alembic. - Optional APK API: The system contains hooks for a mobile app API module (
/apk/api) that can be optionally enabled for native mobile app support.
Technical Architecture Decisions
- Application Factory Pattern:
create_app()function registers all 25+ blueprints, initializes extensions, and auto-patches the DB schema on startup for backward compatibility with existing databases. - SQLite on Production: Chose SQLite over MySQL for cPanel deployment simplicity — the system handles a single-venue marquee where concurrent write volume is low. The 258KB DB file stays fast.
- Auto Schema Migration: On startup, the app checks for missing columns (e.g.,
opening_balance_date,zk_device_user_id) and appliesALTER TABLEautomatically — zero-downtime upgrades on the live server. - Cache Strategy: Static assets (images, CSS, JS) cached for 1 year (
immutable). HTML pages cached for 1 hour with revalidation. Referrer-Policy header set for YouTube embeds. - Layered Permissions: Users can have role-based permissions + direct permissions. The
has_permission()method checks both layers — no bypass possible without explicit assignment.