Worked example: Sales
Sales (af.sales) is a small sales tool: leads on a pipeline, meetings, follow-ups and the state of
each conversation, on web, desktop and phone. It was built only from core services, step by step;
the full plan is in the reference docs (meta/sales-plugin-plan.md).
Feature → core service → code
Section titled “Feature → core service → code”| Feature | Core service | Where |
|---|---|---|
| Own leads, managers see all | Permissions + per-record check | server/sales.repository.ts (visibleTo), sales.service.ts |
| Leads, timeline, meetings, follow-ups | PluginDb (schema sales, role af_sales) |
db/migrations/0000_init.sql, repositories |
| Owner names and photos, team picker | PluginPeople |
web/*, admin/SettingsPage.tsx |
| Reassign, delete, import, team changes recorded | PluginAudit |
sales.service.ts |
| “Assigned to you”, “follow-up due”, “meeting soon” | PluginNotifications + resolvers |
plugin.yaml, notifications/, server/notifications.ts |
| Reminders every minute, untouched leads | Temporal schedule, defineActivities |
workers/workflows.ts, workers/activities.ts |
| Board and lead page update live | PluginEvents (two events: people on the lead, managers) |
server/sales.events.ts, shared/live.ts |
| Currency, untouched days, round-robin, website form | PluginConfig |
config/, admin/SettingsPage.tsx |
| Discuss in Chat, “deal won” in #general | PluginContracts → Chat’s ChatApi |
sales.service.ts (discussInChat, announceWin) |
| Public website form | @Public() routes with spam traps and a limit |
server/capture.controller.ts, capture.ts |
| Open a lead from a notification or a list | Navigation route lead |
plugin.yaml, web/useSales.ts, mobile/* |
| Nav badge: follow-ups due | Shell badges | web/index.tsx (useDueFollowUps) |
| Phone: Today, leads, lead page | Mobile surface | mobile/HomeScreen.tsx, mobile/LeadScreen.tsx |
Patterns worth copying
Section titled “Patterns worth copying”- One visibility rule, used by every query — lists, single reads and writes cannot disagree.
- Events with ids only, to the right people — managers get a separate event guarded by
sales:manage, so nobody else learns a lead exists. - Send, then mark, with a key — reminders never get lost or doubled across crashes.
- Degrade when another plugin is missing —
settings.chathides the Chat button; a failing Chat never undoes a won deal. - Shared logic —
shared/live.ts,shared/csv.tsandshared/format.tsserve web and phone.
Try it
Section titled “Try it”pnpm demo:seed # Ada, Grace and Alan sell; 13 leads, follow-ups, meetingspnpm devSign in as ada@demo.test (Demo-Pass-1!) for a salesperson’s view, or admin@example.com for a
manager’s: every lead, Import, reassigning, and the owner table on the Dashboard.