# Dine360 Architecture Plan > Generated: 2026-04-20 | Platform: Frappe 15.105.0 + ERPNext 15.104.3 > Instance: http://147.93.40.215:10009/ --- ## 1. Platform Foundation | Layer | Version | Notes | |-------|---------|-------| | Frappe Framework | 15.105.0 | Core DocType engine, workflow, notifications, scheduler | | ERPNext | 15.104.3 | CRM, Accounts, HR modules available for reuse | | Custom Module | Dine360 | Registered under `frappe` app | --- ## 2. Standard ERPNext DocTypes — Reuse Opportunities These exist out of the box and can be linked from Dine360 DocTypes rather than recreating: | ERPNext DocType | Dine360 Purpose | How Reused | |-----------------|-----------------|------------| | **Customer** | Advertiser billing account | Link from Advertiser → Customer for sales invoices | | **Supplier** | Restaurant Partner payout | Link from Restaurant Partner → Supplier for purchase invoices | | **Sales Invoice** | Advertiser billing | Create against Customer when campaign runs | | **Purchase Invoice** | Restaurant payout | Create against Supplier on settlement | | **Payment Entry** | Record actual payments | Link from Restaurant Settlement after payout | | **Address** | Branch physical location | Link from Restaurant Branch → Address | | **Contact** | Partner/advertiser contacts | Standard Contact linked to Restaurant Partner/Advertiser | | **Employee** | Internal operations staff | Assign campaigns, escalations | | **User** | Portal access | All 8 Dine360 roles assigned to Users | | **File** | Creative asset storage | Ad Creative links to File for media uploads | | **Communication** | Email/SMS log | Auto-logged on notification send | | **Activity Log** | Audit trail | Auto-logged on all document changes | | **ToDo** | Onboarding task reminders | Auto-created from Onboarding Checklist workflow | --- ## 3. Custom Dine360 DocTypes (19 Total) ### 3a. Child Tables (4) | DocType | Parent | Purpose | |---------|--------|---------| | **Screen Group Member** | Screen Group | Lists Screen Devices belonging to a group | | **Campaign Creative Item** | Ad Campaign | Creative assets (video/image) with duration per campaign | | **Campaign Target Item** | Ad Campaign | Target screen groups and time slots per campaign | | **Settlement Ledger Item** | Restaurant Settlement | Per-restaurant line items in a batch settlement | ### 3b. Master / Configuration DocTypes (6) | DocType | Submittable | Key Fields | Autoname | |---------|-------------|------------|----------| | **Restaurant Partner** | No | partner_name, contact_email, status (Active/Inactive/Suspended), linked_supplier | `field:partner_name` | | **Advertiser** | No | advertiser_name, contact_email, industry, linked_customer | `field:advertiser_name` | | **Restaurant Branch** | No | branch_name, restaurant_partner (Link), city, address, is_active | `BRANCH-.#####` | | **Ad Creative** | No | creative_name, advertiser (Link), media_type (Video/Image/HTML), file_url, duration_seconds, status (Draft/Approved/Rejected) | `CRTV-.YYYY.-.#####` | | **Screen Device** | No | device_name, restaurant_branch (Link), screen_group (Link), device_serial, status (Active/Inactive/Maintenance), last_heartbeat | `SCRN-.#####` | | **Screen Group** | No | group_name, description, screen_group_members (child table) | `field:group_name` | ### 3c. Transaction DocTypes (9) | DocType | Submittable | Key Fields | Autoname | |---------|-------------|------------|----------| | **Ad Campaign** | **Yes** | campaign_name, advertiser (Link), start_date, end_date, budget, status, campaign_creative_items (child), campaign_target_items (child) | `CAMP-.YYYY.-.#####` | | **Revenue Rule** | No | rule_name, advertiser (Link), restaurant_partner (Link), revenue_split_percent, effective_from, effective_to | `RULE-.YYYY.-.#####` | | **API Sync Log** | No | sync_type, sync_status (Success/Failed/Partial), synced_at, records_processed, error_message | `SYNC-.YYYY.-.#####` | | **Campaign Schedule** | No | ad_campaign (Link), screen_device (Link), scheduled_date, start_time, end_time, status (Pending/Confirmed/Cancelled) | `SCHED-.YYYY.-.#####` | | **Playback Log** | No | screen_device (Link), ad_campaign (Link), played_at, duration_played, completion_status | `PLAY-.YYYY.-.#####` | | **Device Heartbeat** | No | screen_device (Link), heartbeat_at, ip_address, cpu_load, memory_used, status (Online/Offline/Warning) | `HB-.YYYY.-.#####` | | **Revenue Ledger** | No | restaurant_partner (Link), ad_campaign (Link), revenue_rule (Link), period_start, period_end, gross_revenue, platform_share, partner_share, status (Draft/Calculated/Approved) | `RLGR-.YYYY.-.#####` | | **Restaurant Settlement** | **Yes** | settlement_name, settlement_period_start, settlement_period_end, total_payout, status, settlement_ledger_items (child) | `SETL-.YYYY.-.#####` | | **Onboarding Checklist** | No | restaurant_partner (Link), assigned_to, current_stage, lead_date, review_date, agreement_date, setup_date, go_live_date | `OB-.YYYY.-.#####` | --- ## 4. Entity Relationship Map ``` ┌─────────────────┐ │ Advertiser │──────────────────────────┐ └────────┬────────┘ │ │ 1 │ 1 ▼ N ▼ N ┌────────────────┐ ┌────────────────────┐ │ Ad Creative │ │ Revenue Rule │ └────────┬───────┘ └────────────────────┘ │ N │ ▼ M (via child table) │ ┌────────────────┐ │ │ Ad Campaign │─────────────────────────┘ └────┬───────┬───┘ │ │ via Campaign Target Items │ ▼ N │ ┌─────────────┐ ┌──────────────────┐ │ │ Screen Group│───────│ Screen Group │ │ └─────────────┘ │ Member (child) │ │ │ └──────────────────┘ │ │ N │ ▼ 1 │ ┌─────────────┐ ┌───────────────────┐ │ │Screen Device│───────│Restaurant Branch │ │ └──────┬──────┘ └────────┬──────────┘ │ │ │ N │ │ 1 ▼ 1 │ ┌──────┴──────┐ ┌──────────────────────┐ │ │ Playback │ │ Restaurant Partner │ │ │ Log │ └────────────┬─────────┘ │ └─────────────┘ │ 1 │ ▼ N │ ┌──────────────────────┐ └─────────────────────────►│ Revenue Ledger │ └──────────┬───────────┘ │ N ▼ 1 (via child) ┌──────────────────────┐ │Restaurant Settlement │ └──────────────────────┘ Device Heartbeat ──► Screen Device Campaign Schedule ──► Ad Campaign + Screen Device API Sync Log ──► (standalone audit log) Onboarding Checklist ──► Restaurant Partner ``` --- ## 5. Role Permission Matrix | Role | Masters | Campaigns | Revenue | Devices | Settlement | Onboarding | |------|---------|-----------|---------|---------|------------|------------| | **Dine360 Admin** | Full | Full | Full | Full | Full | Full | | **Campaign Manager** | Read | Full | Read | Read | None | None | | **Operations Manager** | Read | Read/Write | Read | Full | Read | Full | | **Finance Manager** | Read | Read | Full | None | Full | None | | **Support Executive** | Read | Read | None | Read | None | Read/Write | | **Restaurant Manager** | Own | Own | Own | Own | Own | Own | | **Restaurant Viewer** | Read-Own | Read-Own | Read-Own | None | Read-Own | None | | **Device Agent** | None | Read | None | Write-Own | None | None | --- ## 6. Workflow Map ### 6a. Campaign Approval Workflow (Ad Campaign) ``` Draft ──[Submit for Review]──► Pending Approval ──[Approve]──► Approved ──[Schedule]──► Scheduled │ │ │ [Reject] [Reject] [Activate] │ │ │ ▼ ▼ ▼ Rejected Rejected Running ──[Complete]──► Completed │ [Cancel] │ ▼ Cancelled ``` | Transition | From | To | Action | Roles | |------------|------|----|--------|-------| | Submit for Review | Draft | Pending Approval | Submit for Review | Campaign Manager | | Approve | Pending Approval | Approved | Approve | Dine360 Admin, Operations Manager | | Reject | Pending Approval | Rejected | Reject | Dine360 Admin, Operations Manager | | Schedule | Approved | Scheduled | Schedule | Campaign Manager, Operations Manager | | Activate | Scheduled | Running | Activate | Device Agent, Operations Manager | | Complete | Running | Completed | Complete | Device Agent, Operations Manager | | Cancel | Running | Cancelled | Cancel | Dine360 Admin, Operations Manager | ### 6b. Restaurant Onboarding Workflow (Onboarding Checklist) ``` Lead ──[Move to Review]──► Review ──[Sign Agreement]──► Agreement ──[Begin Setup]──► Setup ──[Go Live]──► Live ``` | Transition | From | To | Action | Roles | |------------|------|----|--------|-------| | Move to Review | Lead | Review | Move to Review | Operations Manager, Support Executive | | Sign Agreement | Review | Agreement | Sign Agreement | Operations Manager, Dine360 Admin | | Begin Setup | Agreement | Setup | Begin Setup | Operations Manager | | Go Live | Setup | Live | Go Live | Operations Manager, Dine360 Admin | ### 6c. Settlement Payout Workflow (Restaurant Settlement) ``` Draft ──[Calculate]──► Calculated ──[Approve Payout]──► Approved ──[Mark Paid]──► Paid │ │ │ [Hold] [Hold] [Raise Dispute] │ │ │ ▼ ▼ ▼ Held Held Disputed ──[Resolve]──► Paid ``` | Transition | From | To | docstatus | Action | Roles | |------------|------|----|-----------|--------|-------| | Calculate | Draft | Calculated | 0→0 | Calculate | Finance Manager | | Approve Payout | Calculated | Approved | 0→1 | Approve Payout | Finance Manager, Dine360 Admin | | Hold | Calculated | Held | 0→0 | Hold | Finance Manager | | Hold | Approved | Held | 1→1 | Hold | Finance Manager, Dine360 Admin | | Mark Paid | Approved | Paid | 1→1 | Mark Paid | Finance Manager | | Raise Dispute | Paid | Disputed | 1→1 | Raise Dispute | Restaurant Manager, Finance Manager | | Resolve Dispute | Disputed | Paid | 1→1 | Resolve Dispute | Finance Manager, Dine360 Admin | --- ## 7. Naming Series Reference | DocType | Series | Example | |---------|--------|---------| | Restaurant Branch | `BRANCH-.#####` | BRANCH-00001 | | Ad Creative | `CRTV-.YYYY.-.#####` | CRTV-2026-00001 | | Screen Device | `SCRN-.#####` | SCRN-00001 | | Ad Campaign | `CAMP-.YYYY.-.#####` | CAMP-2026-00001 | | Revenue Rule | `RULE-.YYYY.-.#####` | RULE-2026-00001 | | API Sync Log | `SYNC-.YYYY.-.#####` | SYNC-2026-00001 | | Campaign Schedule | `SCHED-.YYYY.-.#####` | SCHED-2026-00001 | | Playback Log | `PLAY-.YYYY.-.#####` | PLAY-2026-00001 | | Device Heartbeat | `HB-.YYYY.-.#####` | HB-2026-00001 | | Revenue Ledger | `RLGR-.YYYY.-.#####` | RLGR-2026-00001 | | Restaurant Settlement | `SETL-.YYYY.-.#####` | SETL-2026-00001 | | Onboarding Checklist | `OB-.YYYY.-.#####` | OB-2026-00001 | | Restaurant Partner | `field:partner_name` | Metatron Cubes | | Advertiser | `field:advertiser_name` | Coca-Cola India | | Screen Group | `field:group_name` | Zone A Screens | --- ## 8. Status Values Reference | DocType | Status Field | Allowed Values | |---------|-------------|----------------| | Restaurant Partner | status | Active, Inactive, Suspended | | Ad Creative | status | Draft, Approved, Rejected | | Screen Device | status | Active, Inactive, Maintenance | | Campaign Schedule | status | Pending, Confirmed, Cancelled | | Playback Log | completion_status | Completed, Partial, Failed | | Device Heartbeat | status | Online, Offline, Warning | | Revenue Ledger | status | Draft, Calculated, Approved | | API Sync Log | sync_status | Success, Failed, Partial | --- ## 9. Notification Map (5 Active Notifications) | Notification | DocType | Trigger | Recipients | |-------------|---------|---------|-----------| | Campaign Submitted for Review | Ad Campaign | workflow_state → Pending Approval | Dine360 Admin, Operations Manager | | Campaign Approved | Ad Campaign | workflow_state → Approved | Campaign Manager | | Campaign Rejected | Ad Campaign | workflow_state → Rejected | Campaign Manager | | Settlement Approved for Payout | Restaurant Settlement | workflow_state → Approved | Finance Manager | | Campaign Ending Soon | Ad Campaign | end_date within 3 days | Campaign Manager | --- ## 10. Dashboard & Reporting Map ### 10a. Existing Dashboard Charts (6) | Chart | Type | DocType | X-Axis | Y-Axis | |-------|------|---------|--------|--------| | Campaigns by Status | Donut | Ad Campaign | — | status (count) | | Active Screen Devices | Donut | Screen Device | — | status (count) | | Restaurant Partners by Status | Donut | Restaurant Partner | — | status (count) | | Monthly Revenue Ledger | Bar | Revenue Ledger | period_start (monthly) | partner_share (sum) | | Settlements Over Time | Bar | Restaurant Settlement | settlement_period_start (monthly) | total_payout (sum) | | Playback Log Volume | Line | Playback Log | played_at (daily) | name (count) | ### 10b. Recommended Future Reports (Phase 2) | Report | Type | Purpose | |--------|------|---------| | Campaign Performance Summary | Query Report | Impressions, completion rate, revenue per campaign | | Revenue Split Breakdown | Script Report | Per-partner revenue vs platform share over period | | Device Uptime Report | Query Report | Heartbeat-based uptime % per device/branch | | Settlement Audit Trail | Query Report | Full ledger→settlement→payment chain | | Advertiser Billing Statement | Script Report | Invoice-ready summary for advertiser | | Onboarding Pipeline | Query Report | Checklist stage distribution + SLA | --- ## 11. Server-Side Automation Map (Phase 2) | Automation | Type | Trigger | Action | |------------|------|---------|--------| | Revenue Split Calculator | Server Script | On Playback Log save | Calculate partner_share in Revenue Ledger | | Device Offline Alert | Scheduled Job | Every 5 min | Flag Device Heartbeat > 10 min old as Offline | | Campaign Auto-Complete | Scheduled Job | Daily | Set Running campaigns past end_date → Completed | | Settlement Auto-Batch | Scheduled Job | Monthly | Batch Calculated Revenue Ledgers → new Settlement | | Creative Auto-Expire | Scheduled Job | Daily | Flag Ad Creatives not updated in 90 days | | Device Sync API | API Endpoint | REST POST | Accept heartbeat + playback data from devices | --- ## 12. Phase 2 Implementation Order All 19 DocTypes, 3 workflows, 5 notifications, 6 charts, and 1 workspace are **already live**. Phase 2 items in recommended build order: ``` Step 1 — Server Scripts (business logic) 1.1 Revenue split auto-calculation on Playback Log save 1.2 Settlement batch-creation script (aggregate Revenue Ledger → Settlement) 1.3 Campaign status auto-complete (scheduled) 1.4 Device offline detection (scheduled heartbeat check) Step 2 — Query / Script Reports 2.1 Campaign Performance Summary (Query Report) 2.2 Revenue Split Breakdown (Script Report) 2.3 Device Uptime Report (Query Report) 2.4 Settlement Audit Trail (Query Report) Step 3 — Print Formats 3.1 Settlement Payout Slip (Restaurant Settlement) 3.2 Advertiser Campaign Summary (Ad Campaign) Step 4 — Portal / Role Permissions 4.1 Tighten user permissions per Role Permission Matrix (Section 5) 4.2 Configure Restaurant Manager portal view 4.3 Configure Advertiser self-service portal (if needed) Step 5 — API Endpoints 5.1 Device heartbeat sync endpoint (POST /api/method/dine360.heartbeat) 5.2 Playback log ingestion endpoint (POST /api/method/dine360.playback) 5.3 Campaign schedule fetch endpoint (GET /api/method/dine360.schedule) Step 6 — Integration 6.1 Link Restaurant Partner → Supplier (for Purchase Invoice on settlement) 6.2 Link Advertiser → Customer (for Sales Invoice on campaign billing) 6.3 Auto-create Payment Entry on Settlement marked Paid ``` --- ## 13. Key Design Decisions & Constraints 1. **Dine360 is a custom module** on the `frappe` app — not a separate installable app. Upgrade-safe as long as customizations live in DocType/Server Script/Client Script records. 2. **Submittable DocTypes**: Only `Ad Campaign` and `Restaurant Settlement` are submittable. Revenue Ledger uses a status field (not docstatus) to allow edits through the approval cycle. 3. **Workflow docstatus rule**: Frappe forbids transitions from submitted (docstatus=1) → draft (docstatus=0). All dispute/hold states in the Settlement workflow are docstatus=1. 4. **ERPNext accounting integration** is optional but available: Settlement → Purchase Invoice → Payment Entry chain uses native ERPNext accounting. Disable if a simpler ledger-only approach is preferred. 5. **Device authentication**: Screen Devices should authenticate via API key (generate one API key per device via `frappe_generate_api_key`). The Device Agent role limits read access to only Campaign Schedule. 6. **Revenue Rule priority**: If multiple Revenue Rules match an Advertiser + Partner pair, use the most recently effective rule. Overlap validation should be enforced via server script.