{"id":48057911,"url":"https://github.com/kulkarnishub377/cafe-system-architecture","last_synced_at":"2026-04-04T14:29:44.333Z","repository":{"id":342485013,"uuid":"1136345568","full_name":"kulkarnishub377/cafe-system-architecture","owner":"kulkarnishub377","description":"A production-ready, full-stack Point-of-Sale and cafe management system built on Django REST Framework (backend) and vanilla HTML/CSS/JS (frontend). Designed for small-to-medium cafes with dine-in, takeaway, and delivery workflows.","archived":false,"fork":false,"pushed_at":"2026-03-06T09:25:43.000Z","size":341,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T09:55:15.590Z","etag":null,"topics":["architecture","dijango","fullstack-development","python","sql","web-development"],"latest_commit_sha":null,"homepage":"https://kulkarnishub377.github.io/cafe-system-architecture/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kulkarnishub377.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T14:22:32.000Z","updated_at":"2026-03-06T09:25:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kulkarnishub377/cafe-system-architecture","commit_stats":null,"previous_names":["kulkarnishub377/cafe-system-architecture"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kulkarnishub377/cafe-system-architecture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2Fcafe-system-architecture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2Fcafe-system-architecture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2Fcafe-system-architecture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2Fcafe-system-architecture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kulkarnishub377","download_url":"https://codeload.github.com/kulkarnishub377/cafe-system-architecture/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kulkarnishub377%2Fcafe-system-architecture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31402553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","dijango","fullstack-development","python","sql","web-development"],"created_at":"2026-04-04T14:29:44.232Z","updated_at":"2026-04-04T14:29:44.310Z","avatar_url":"https://github.com/kulkarnishub377.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# # SK cafe — Full-Stack Cafe Management System  `v3.0`\n\nA **production-ready, full-stack** Point-of-Sale and cafe management system built on **Django REST Framework** (backend) and **vanilla HTML/CSS/JS** (frontend). Designed for small-to-medium cafes with dine-in, takeaway, and delivery workflows.\n\n---\n\n## 📋 Table of Contents\n\n1. [Features Overview](#features-overview)\n2. [Architecture](#architecture)\n3. [Quick Start](#quick-start)\n4. [Backend API Reference](#backend-api-reference)\n5. [Customer Experience (IP-based, No Login)](#customer-experience)\n6. [Staff Authentication](#staff-authentication)\n7. [QR Code Management](#qr-code-management)\n8. [Behaviour Tracking \u0026 Suggestions](#behaviour-tracking--suggestions)\n9. [Database \u0026 SQL Schema](#database--sql-schema)\n10. [Frontend Pages](#frontend-pages)\n11. [Admin Panel](#admin-panel)\n12. [Testing](#testing)\n13. [Configuration](#configuration)\n14. [Deployment](#deployment)\n\n---\n\n## Features Overview\n\n### 🍽️ Menu Management\n- Full CRUD for menu items (name, price, category, image, emoji, veg/non-veg, calories, allergens)\n- 7 categories: Coffee, Burgers, Pizza, Mains, Desserts, Drinks, Snacks\n- One-click **toggle stock** and **toggle trending** actions\n- Filter by category, stock status, trending; full-text search\n- Sort order control for custom display ordering\n\n### 🪑 Table Management\n- 12+ configurable dining tables with capacity and location info\n- Status lifecycle: Available → Occupied → Reserved → Maintenance\n- **QR code generation** per table (PNG stored as base64 data URI)\n- **Print QR code sheets** — bulk-print all table QR codes from admin\n- `GET /api/tables/{id}/qr_code/` — on-demand QR image generation via API\n\n### 📋 Order Sessions\n- Dine-in, Takeaway, and Delivery session types\n- Customers add items to a session; kitchen auto-notified\n- Discount code application with real-time validation\n- Bill generation with subtotal / discount / tax / total breakdown\n- Mark bill as printed; close session → archives to SalesRecord\n\n### 👨‍🍳 Kitchen Display System (KDS)\n- Real-time kitchen order tickets auto-created when items are ordered\n- Priority levels: Normal / High / Urgent\n- Status flow: Pending → Preparing → Completed\n- Bulk status update endpoint\n- Estimated preparation time tracking\n\n### 📅 Reservations\n- Table reservation with date, time, party size, customer phone\n- Conflict detection (no double-booking same table+time)\n- Status lifecycle: Pending → Confirmed → Seated → Completed / Cancelled\n- Staff actions: confirm, seat, cancel via API or admin\n\n### 💰 Discounts \u0026 Promotions\n- Promo codes (percentage or fixed INR discount)\n- Date range validity, min order amount, max uses cap\n- `POST /api/discounts/validate/` — check code before applying\n\n### 📊 Sales \u0026 Analytics\n- Every closed session archived as a `SalesRecord` with full item snapshot\n- `GET /api/stats/` — today's revenue, orders, avg order, active tables, feedback rating\n- `GET /api/stats/top_items/` — top 10 best-sellers by quantity\n- `GET /api/stats/hourly/` — revenue by hour for today\n- `GET /api/stats/category_breakdown/` — revenue per food category\n- 3 SQL database views: `v_daily_revenue`, `v_popular_items`, `v_table_status`\n\n### ⭐ Customer Feedback\n- Post-visit ratings (1–5 stars) for overall experience, food, and service\n- \"Would recommend\" flag\n- Linked to closed SalesRecord for traceability\n\n### 👤 Customer Experience (No Login Required)\n- Customers are identified **by IP address only** — no account needed\n- `CustomerVisit` model stores: IP, preferred name, visit count, first/last seen\n- **Behaviour tracking**: previous orders, personal top picks, trending suggestions\n- **Welcome-back message**: \"Welcome back, Alice! 👋\" for returning customers\n- `GET /api/customer/suggestions/` — Zomato-style personalised recommendation feed\n\n### 🔐 Staff Authentication (Token-based)\n- `POST /api/auth/login/` — username/password → auth token\n- `POST /api/auth/logout/` — revoke token\n- `GET /api/auth/me/` — current user profile + role\n- `POST /api/auth/toggle_duty/` — toggle on-duty status\n- 3 roles: **Admin**, **Kitchen**, **Waiter**\n- Admin-only: settings, discount management\n- Kitchen-or-Admin: kitchen order updates\n\n### ⚙️ Cafe Settings (Singleton)\n- Cafe name, phone, address, GST number\n- Tax rate, currency symbol, UPI ID, Instagram URL\n- Opening/closing times, total tables count\n\n---\n\n## Architecture\n\n```\ncafe-system-architecture/\n├── backend/                    # Django REST Framework API\n│   ├── cafe/\n│   │   ├── models.py           # 13 models (BaseModel mixin)\n│   │   ├── views.py            # 10 ViewSets, 40+ endpoints\n│   │   ├── serializers.py      # All serializers\n│   │   ├── urls.py             # URL routing\n│   │   ├── admin.py            # Full Django admin\n│   │   ├── permissions.py      # IsAdminStaff, IsKitchenOrAdmin, IsStaffMember\n│   │   ├── filters.py          # django-filter FilterSets\n│   │   ├── exceptions.py       # Custom API exceptions\n│   │   ├── signals.py          # Post-save signals\n│   │   ├── utils.py            # calculate_bill, QR generation, IP extraction\n│   │   ├── tests.py            # 105+ tests\n│   │   ├── migrations/         # 3 migrations\n│   │   └── management/\n│   │       └── commands/\n│   │           ├── seed_menu.py       # Seed 27 menu items\n│   │           ├── seed_tables.py     # Seed 12 tables\n│   │           └── create_staff.py    # Create default staff accounts\n│   ├── cafe_backend/\n│   │   ├── settings.py         # Django settings\n│   │   └── urls.py             # Root URL conf + Swagger\n│   ├── schema.sql              # Full SQL DDL documentation\n│   └── requirements.txt\n├── frontend/                   # API-connected frontend\n│   ├── index.html              # Landing/welcome page\n│   ├── customer.html           # Customer ordering page\n│   ├── kitchen.html            # Kitchen display system\n│   ├── admin.html              # Staff management dashboard\n│   ├── data.js                 # API layer (30+ async methods)\n│   └── styles.css              # Shared styles\n└── README.md\n```\n\n---\n\n## Quick Start\n\n### 1. Install dependencies\n```bash\ncd backend\npip install -r requirements.txt\n```\n\n### 2. Run migrations\n```bash\npython manage.py migrate\n```\n\n### 3. Seed the database\n```bash\npython manage.py seed_menu       # Creates 27 menu items + 12 tables\npython manage.py create_staff    # Creates admin, kitchen1, waiter1 accounts\n```\n\n### 4. Start the server\n```bash\npython manage.py runserver\n```\n\nAPI available at `http://127.0.0.1:8000/api/`  \nSwagger UI: `http://127.0.0.1:8000/api/docs/`  \nAdmin panel: `http://127.0.0.1:8000/admin/`\n\n### 5. Open the frontend\nOpen `frontend/index.html` in your browser (or serve with any static file server).\n\n---\n\n## Backend API Reference\n\nBase URL: `http://127.0.0.1:8000/api/`\n\n| Resource | Endpoints |\n|---|---|\n| Menu | `GET/POST /menu/` · `GET/PUT/PATCH/DELETE /menu/{id}/` · `POST /menu/{id}/toggle_stock/` · `POST /menu/{id}/toggle_trending/` |\n| Tables | `GET/POST /tables/` · `GET/PUT/PATCH/DELETE /tables/{id}/` · `GET /tables/{id}/session/` · `GET /tables/{id}/qr_redirect/` · `GET /tables/{id}/qr_code/` |\n| Sessions | `GET /sessions/` · `GET/POST /sessions/{table_num}/` · `POST /sessions/{table_num}/close/` · `POST /sessions/{table_num}/mark_bill_printed/` · `GET /sessions/{table_num}/generate_bill/` |\n| Kitchen | `GET /kitchen/` · `GET/PATCH /kitchen/{id}/` · `PATCH /kitchen/{id}/status/` · `POST /kitchen/bulk_update/` |\n| Reservations | `GET/POST /reservations/` · `GET/PUT/PATCH/DELETE /reservations/{id}/` · `POST /reservations/{id}/confirm/` · `POST /reservations/{id}/seat/` · `POST /reservations/{id}/cancel/` |\n| Sales | `GET /sales/` · `GET /sales/{id}/` |\n| Discounts | `GET/POST /discounts/` · `GET/PUT/PATCH/DELETE /discounts/{id}/` · `POST /discounts/validate/` |\n| Feedback | `GET /feedback/` · `GET /feedback/{id}/` · `POST /feedback/` |\n| Stats | `GET /stats/` · `GET /stats/top_items/` · `GET /stats/hourly/` · `GET /stats/category_breakdown/` |\n| Auth | `POST /auth/login/` · `POST /auth/logout/` · `GET /auth/me/` · `POST /auth/toggle_duty/` |\n| Customer | `GET /customer/me/` · `GET /customer/orders/` · `POST /customer/update_name/` · `GET /customer/suggestions/` |\n| Settings | `GET /settings/` · `POST /settings/` |\n\nFull interactive documentation: **`/api/docs/`** (Swagger UI) or **`/api/redoc/`**\n\n---\n\n## Customer Experience\n\nCustomers **never need to log in**. They are identified by their **IP address**, which is automatically captured on every order.\n\n| Feature | Detail |\n|---|---|\n| Visit tracking | `CustomerVisit` row per IP: name, visit count, first/last seen |\n| Order history | All past orders linked to the customer's IP via `SalesRecord.ip_address` |\n| Preferred name | Customer can set `POST /api/customer/update_name/` — persists across visits |\n| Suggestions | `GET /api/customer/suggestions/` — personalised feed (see below) |\n\n---\n\n## Staff Authentication\n\n```bash\n# Login\nPOST /api/auth/login/\n{ \"username\": \"admin\", \"password\": \"\u003cyour-admin-password\u003e\" }\n→ { \"token\": \"abc123...\", \"role\": \"admin\", \"is_on_duty\": true }\n\n# All subsequent staff requests:\nAuthorization: Token abc123...\n```\n\nDefault accounts created by `python manage.py create_staff`:\n\n| Username | Env Variable | Role |\n|---|---|---|\n| `admin` | `ADMIN_PASSWORD` | Admin / Manager |\n| `kitchen1` | `KITCHEN1_PASSWORD` | Kitchen Staff |\n| `waiter1` | `WAITER1_PASSWORD` | Waiter |\n\nSet the environment variables before running the command, or passwords will be\nauto-generated and printed to stdout on first run.\n\n\u003e ⚠️ Always set strong passwords via environment variables before deploying to production.\n\u003e Auto-generated passwords are printed once to stdout on first run — treat that output as a secret\n\u003e and change passwords immediately using `python manage.py changepassword \u003cusername\u003e`.\n\n---\n\n## QR Code Management\n\n### Via Admin Panel\n1. Go to **Admin → Tables**\n2. Select tables → Action: **🔲 Generate / refresh QR codes** → Execute\n3. Action: **🖨️ Print QR code sheet** → Opens a print-ready HTML page with all QR codes\n4. Each QR code scans to the customer ordering URL for that table\n\n### Via API\n```\nGET /api/tables/{id}/qr_code/\n→ { \"table_number\": 5, \"qr_url\": \"...\", \"qr_data_uri\": \"data:image/png;base64,...\" }\n```\nThe QR image is auto-generated on first access and cached on the `Table` row.\n\n---\n\n## Behaviour Tracking \u0026 Suggestions\n\n`GET /api/customer/suggestions/` returns a rich payload with zero login required:\n\n```json\n{\n  \"ip_address\": \"192.168.1.10\",\n  \"is_returning\": true,\n  \"visit_count\": 7,\n  \"preferred_name\": \"Alice\",\n  \"welcome_message\": \"Welcome back, Alice! 👋 Great to see you again.\",\n  \"reorder_items\": [\n    { \"id\": 3, \"name\": \"Caramel Macchiato\", \"price\": 220, \"qty\": 2 }\n  ],\n  \"top_picks\": [\n    { \"id\": 3, \"name\": \"Caramel Macchiato\", \"qty\": 14, \"price\": 220 },\n    { \"id\": 12, \"name\": \"Margherita\", \"qty\": 8, \"price\": 350 }\n  ],\n  \"trending_now\": [\n    { \"id\": 1, \"name\": \"Iced Latte\", \"price\": 180, \"emoji\": \"🧊\", \"category\": \"coffee\" }\n  ],\n  \"suggested_items\": [ ... ],\n  \"previous_orders\": [ ... ]\n}\n```\n\nThe **customer ordering page** (`frontend/customer.html`) reads this on load and:\n- Shows a personalised welcome banner\n- Pre-fills a \"Reorder\" quick-add section for the last order\n- Displays \"Your favourites\" based on order history\n- Shows globally trending items\n\n---\n\n## Database \u0026 SQL Schema\n\nSee [`backend/schema.sql`](backend/schema.sql) for the full DDL.\n\n### Tables\n`cafe_menuitem` · `cafe_table` · `cafe_reservation` · `cafe_tablesession` · `cafe_sessionitem` · `cafe_kitchenorder` · `cafe_kitchenorderitem` · `cafe_discount` · `cafe_salesrecord` · `cafe_orderfeedback` · `cafe_customervisit` · `cafe_staffprofile` · `cafe_cafesettings`\n\n### SQL Views (created by migration)\n| View | Description |\n|---|---|\n| `v_daily_revenue` | Daily revenue aggregation (order count, total, avg, discounts) |\n| `v_popular_items` | Items ranked by total quantity sold, with revenue |\n| `v_table_status` | Table occupancy: status, current customer, minutes occupied |\n\n---\n\n## Frontend Pages\n\n| File | Description |\n|---|---|\n| `frontend/index.html` | Welcome / landing page with navigation |\n| `frontend/customer.html` | Customer ordering page — browse menu, add to cart, apply discount, checkout |\n| `frontend/kitchen.html` | Kitchen Display System — live order tickets, status updates |\n| `frontend/admin.html` | Staff dashboard — tables, sessions, sales, menu management, analytics |\n| `frontend/data.js` | Complete async API layer (30+ methods covering all endpoints) |\n\nThe frontend auto-detects the API URL from `window.SK_API_BASE` (defaults to `http://127.0.0.1:8000`).\n\n---\n\n## Admin Panel\n\n`http://127.0.0.1:8000/admin/` — Django Admin with:\n\n| Section | Features |\n|---|---|\n| **Menu Items** | Inline edit price/stock/trending; bulk trending/stock actions |\n| **Tables** | Quick status edit; **Generate QR codes**; **Print QR code sheet**; QR preview in change form |\n| **Reservations** | Date hierarchy; bulk confirm/cancel |\n| **Kitchen Orders** | Priority filter; bulk complete; inline order items |\n| **Sales Records** | Read-only; date hierarchy; tax amount display |\n| **Discounts** | Code management; validity tracking |\n| **Feedback** | Rating filters |\n| **Staff Profiles** | Role + on-duty status management |\n| **Customer Visits** | IP browse; visit counts; preferred names |\n| **Cafe Settings** | Singleton — tax rate, name, branding, UPI ID |\n\n---\n\n## Testing\n\n```bash\ncd backend\npython manage.py test cafe\n```\n\n**105 tests** covering:\n- All model validations and business logic\n- All API endpoints (CRUD, actions, filters)\n- Staff authentication (login, logout, me, toggle_duty)\n- Customer IP tracking (me, orders, update_name, suggestions)\n- Permission enforcement (admin-only, kitchen-or-admin, public)\n- Discount validation (percentage, fixed, expired, exhausted)\n- Reservation conflict detection\n- Bill calculation (subtotal, discount, tax, rounding)\n- Kitchen order bulk updates\n- Stats and analytics endpoints\n- QR code utilities\n\n---\n\n## Configuration\n\nKey `settings.py` options (override via environment variables):\n\n| Setting | Env Variable | Default |\n|---|---|---|\n| Secret key | `DJANGO_SECRET_KEY` | insecure dev key |\n| Debug mode | `DJANGO_DEBUG` | `True` |\n| Allowed hosts | `DJANGO_ALLOWED_HOSTS` | `localhost 127.0.0.1` |\n| CORS origins | `CORS_ALLOWED_ORIGINS` | localhost:3000, 8080 |\n| Database | — | SQLite `db.sqlite3` |\n| Time zone | — | `Asia/Kolkata` |\n| Tax rate | — | 5% (via CafeSettings singleton) |\n\nFor **PostgreSQL** in production, update `DATABASES` in `settings.py`:\n```python\nDATABASES = {\n    'default': {\n        'ENGINE': 'django.db.backends.postgresql',\n        'NAME': os.environ['DB_NAME'],\n        'USER': os.environ['DB_USER'],\n        'PASSWORD': os.environ['DB_PASSWORD'],\n        'HOST': os.environ.get('DB_HOST', 'localhost'),\n        'PORT': os.environ.get('DB_PORT', '5432'),\n    }\n}\n```\n\n---\n\n## Deployment\n\n1. Set `DJANGO_DEBUG=False` and a strong `DJANGO_SECRET_KEY`\n2. Set `DJANGO_ALLOWED_HOSTS` to your domain\n3. Configure PostgreSQL (recommended for production)\n4. Run `python manage.py collectstatic`\n5. Serve with **gunicorn** + **nginx**\n\n```bash\ngunicorn cafe_backend.wsgi:application --bind 0.0.0.0:8000 --workers 4\n```\n\nSet `window.SK_API_BASE = 'https://your-api.example.com'` in the frontend HTML before loading `data.js`.\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| Backend framework | Django 6.0.3 |\n| REST API | Django REST Framework 3.16.1 |\n| API docs | drf-spectacular (Swagger / ReDoc) |\n| Filtering | django-filter 25.2 |\n| CORS | django-cors-headers |\n| QR codes | qrcode 8.2 + Pillow 12.1.1 |\n| Database (dev) | SQLite 3 |\n| Database (prod) | PostgreSQL (recommended) |\n| Frontend | HTML5 / CSS3 / Vanilla JS |\n| Auth | DRF Token Authentication |\n\n---\n\n*# SK cafe Management System — built with ☕ and Django*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkulkarnishub377%2Fcafe-system-architecture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkulkarnishub377%2Fcafe-system-architecture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkulkarnishub377%2Fcafe-system-architecture/lists"}