MCP-Frappe/DINE360_ARCHITECTURE.md

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.