Appearance
Management
The Management module is the operations dashboard — the homepage every logged-in user lands on. It rolls up live CRM, Accounting, Debtors, Banking, Subscriptions and (for superusers) Voice/Operations figures into stat cards, charts and recent-activity lists per business "site" tab, and carries a personal Tasks panel with start/stop time timers feeding a shared timesheet. It's used by everyone from front-line staff (their own tasks and timers) to admins and superusers (full pipeline/revenue visibility, layout and access controls).
What you can do
- Site tabs — switch between the platform's configured Frappe/ERPNext tenants (or local sites), each with its own set of stat cards.
- Category sub-tabs — CRM, Accounting, Banking & Payments, Debtors, Subscriptions, Meta Ads, Google SEO, Chat, Creditors, and (superuser-only) Voice and Operations.
- Stat cards — live counts/amounts (leads, quotations, orders, invoices, outstanding balances, collection rate, etc.), each deep-linking back to the matching record list in the source system (ERP desk, CRM SPA, or customer portal).
- Charts & tables — period breakdowns (e.g. leads by status, leads by week) and comparison tables (e.g. services vs. subscriptions), each also deep-linkable.
- Targets — a formula-driven goal line per card/chart (1.25× the trailing 3-month average), or a manually saved company-wide target.
- Color rules — per-user rules that recolor a card's accent (blue/green/amber/red/slate) based on its live value crossing a threshold.
- Card layout controls — drag-to-reorder cards and sections, group cards under custom headings, hide a card for yourself, or (admin+) hide/rename/permanently delete a card or section for everyone.
- Free-form canvas view — switch a panel to a drag-and-resize board where every card/chart gets a saved position and size.
- Tasks panel — a flat, cross-board list of open tasklist cards with one-click Start/Stop timers; only one personal timer runs at a time.
- Timesheet — a shared per-user/per-day report of all tracked time (dashboard timers and tasklist timers combined).
- Per-person dashboard tabs — optionally group the category sub-tabs under named tabs per staff member, with an automatic "Other" tab for anything unclaimed.
- Public/shareable dashboard — a password-gated, read-only, no-login view of the same cards/charts (minus Voice and Operations) for external sharing.
- Stale-record cleanup — admins can bulk-cancel every stale quote (no order after 2 weeks) or stale sales order (unpaid after 3 weeks) straight from its card.
Common tasks
Read the day's numbers Pick a site tab, then a category sub-tab. Cards update for the selected period (
daysquery, default 30); click any card or chart to open the matching records in the source system. A site that's down or unconfigured still loads with empty cards and an error note instead of failing the page.Track time on a task Open the Tasks panel and press the play button on a task to start its timer — this stops any other timer you have running so time is never double-counted. Press stop when you're done, or start a different task's timer to switch. Card timers and tasklist timers all feed the same tenant timesheet.
Review the timesheet Open the time report to see time spent per user per day, including running (not-yet-stopped) entries counted live, optionally filtered to a date range.
Set a goal or color rule on a card Open a card's menu to set a manual target value (visible to the whole tenant) or a color rule (e.g. "red when below 50", scoped to just you). Rules are evaluated in order, first match wins, with an optional default color.
Rearrange or customize the layout Drag cards/sections into a new order, drag a card into a different group heading, or switch a panel to Canvas view and freely position/resize each widget. Admins can additionally hide, rename, or permanently delete a card/section for every user on that tab.
Share a read-only snapshot externally Give the viewer the public dashboard link and the shared password; they see the same site/category cards and charts (excluding Voice and Operations) with no login and no deep-links into the source ERP.
Data model
The dashboard doesn't own its own business data — it aggregates live from other modules and external systems, and persists only layout/preference state locally:
| Source | Feeds |
|---|---|
Frappe/ERPNext sites (app.services.erp_client) or local site DB (app.services.erp_local) | CRM, Accounting, Banking & Payments, Debtors, Subscriptions, Creditors category cards |
app.models.accounting (AccQuotation, AccSalesOrder) | Stale-quote/stale-order counts and the bulk-cancel action |
app.services.social_metrics (tc site's ad accounts) | Meta Ads tab (spend/clicks/conversions + Facebook-sourced lead pipeline) |
app.services.google_seo_metrics / app.models.google (GoogleListing, GoogleReview) | Google SEO tab (listing completeness, SEO score, rating, reviews) |
app.services.chatwoot_metrics (Chatwoot REST API) | Chat tab (open/unassigned conversations, volumes, response times) |
app.services.voice_metrics (CloudTools PBX REST API) | Voice tab — superuser-only |
app.services.operations_metrics (PBX wholesale billing + portal-wide services/balances) | Operations tab — superuser-only, carries GP/GP margin data |
app.services.dashboard_card_snapshot | Daily snapshot store used to compute a card's movement (up/down vs. prior period) for cards with a color rule |
Kanban boards/cards/time entries (app/api/kanban.py) | Tasks panel and the shared timesheet |
Local (non-Frappe) preference tables, all keyed by a layout_key such as "<site>:<category>" or "erp-canvas:<site>:<category>":
| Table | Purpose |
|---|---|
AppSetting (erp_dashboard_tab_groups, erp_dashboard_tasks_enabled) | Per-person tab groupings and the Tasks-feature on/off toggle, one row per site. |
DashboardCardOrder | Per-user drag-to-reorder order for cards/sections. |
DashboardCardTarget | Company-wide saved goal values per card/chart. |
DashboardCardColor | Per-user color rule sets per card. |
DashboardCardGroup | Per-user card→group heading overrides. |
DashboardCardHidden | Per-user hidden-card list (self-service, restorable). |
DashboardCardAdminHidden | Site-wide hidden-card list (admin-managed, restorable). |
DashboardCardDeleted | Site-wide permanently-deleted card list (admin-managed, not restorable). |
DashboardSectionTitle | Site-wide custom section title overrides. |
DashboardCanvasLayout | Per-user free-form {x,y,w,h} widget positions for Canvas view. |
DashboardConnectionSetting | Per-connection frontend URL overrides used to build card deep-links. |
Configuration & integrations
- ERP site credentials — resolved server-side per site (
app.services.erp_credentials); the dashboard never exposes ERP keys to the browser. A site missing credentials shows as "not configured" and its non-external categories (CRM, Accounting, etc.) return empty. - Deep-link targets — each card/chart resolves a URL into the source system's own UI (Frappe desk list view, CRM SPA, or customer portal grid), using
DashboardConnectionSettingfrontend-URL overrides where set, else the ERP site's own URL or the portal's default web base. - Tasks feature toggle —
erp_dashboard_tasks_enabled(default on) turns off the Tasks tab, Timesheet button, and card timers for a site that doesn't use tasklists. - Per-person tab groups —
erp_dashboard_tab_groups; empty/absent means the flat all-apps tab row is shown. Non-superusers only ever receive their own group; superusers see everyone's. - Public dashboard password —
settings.PUBLIC_DASHBOARD_PASSWORD, sent as theX-Public-Passwordheader; an empty configured password disables the gate entirely. - Operations tab access — restricted to superusers only, since it carries wholesale PBX margin (GP/GP%) figures that must never reach a non-superuser login.
- External systems read live, not synced into local tables: Chatwoot (helpdesk), the CloudTools PBX portal (Voice/Operations), and the tc site's Meta Ads accounts (Meta Ads tab).
API reference
Management is a dedicated API, not generic grid CRUD, mounted at /erp (dashboard endpoints) and /kanban (Tasks/timer endpoints):
| Method & Path | Purpose |
|---|---|
GET /erp/sites | The ERP site tabs (id, label, configured). |
GET /erp/categories | The category sub-tabs. |
GET /erp/sites/{site}/stats?category=&days= | Live cards + items + charts + targets for one site × category; operations is superuser-only. |
GET /erp/public/sites | Configured sites for the public dashboard (also the password-check endpoint). |
GET /erp/public/categories | Public category list (excludes Voice/Operations). |
GET /erp/public/sites/{site}/stats?category=&days= | Password-gated equivalent of the internal stats endpoint. |
GET/PUT /erp/tab-groups | Read/replace per-person dashboard tab groupings (PUT is superuser-only). |
PUT /erp/tasks-enabled | Turn the Tasks feature on/off for this site (superuser-only). |
GET /erp/tab-groups/users | Active users assignable to a tab group (superuser-only). |
GET/PUT /erp/card-order | Read/save a user's stat-card or section drag order for a layout key. |
GET/PUT /erp/card-target | Read/merge company-wide card/chart target values. |
GET/PUT /erp/card-color | Read/merge a user's card color rules. |
GET/PUT /erp/card-group | Read/merge a user's card→group heading overrides. |
GET/PUT /erp/card-hidden | Read/replace a user's self-hidden card list. |
GET/PUT /erp/card-admin-hidden | Read/replace the site-wide hidden card list (PUT admin+). |
GET/PUT /erp/card-deleted | Read/replace the site-wide permanently-deleted card list (PUT admin+). |
GET/PUT /erp/section-title | Read/replace custom section title overrides (PUT admin+). |
GET/PUT /erp/canvas-layout | Read/save a user's free-form Canvas widget positions. |
DELETE /erp/stale-records | Bulk-cancel every stale quote or stale sales order behind a stale-item card (admin+). |
GET /kanban/track/status | The current user's running dashboard timers. |
POST /kanban/track/start | Start a timer on a task (stops any other timer the user has running). |
POST /kanban/track/stop | Stop a running timer. |
GET /kanban/tasks?include_done= | Flat list of open (or open+done) tasklist cards for the Tasks panel. |
GET /kanban/time-report/detailed?date_from=&date_to= | The tenant-wide timesheet, grouped by user and day. |