admin/MCP-Frappe
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
MCP-Frappe/DINE360_ARCHITECTURE.md
MOHAN 2ee93048e1 feat: Add tools for managing server scripts, client scripts, translations, assignment rules, user permissions, webhooks, API keys, and workflows 
- Implemented server and client script management tools in `frappe_mcp/tools/scripts.py`
- Added translation and user permission management tools in `frappe_mcp/tools/translations.py`
- Created user and role management tools in `frappe_mcp/tools/users.py`
- Developed webhook and API key management tools in `frappe_mcp/tools/webhooks.py`
- Introduced workflow management tools in `frappe_mcp/tools/workflow_tools.py`
- Added `pyproject.toml` for project metadata and dependencies
2026-04-21 20:26:45 +05:30

348 lines
20 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink