docs: full specs for automation engine, sender policy, activity log, privacy monitor, UI overhaul

Clean.Email-parity feature build-out plus a Stripe/Notion-style UI rebuild on Tailwind + shadcn-style primitives. Locks the hybrid-automation, Gmail-only, light+dark, incremental-rollout decisions and lays out the backend/frontend build sequence. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-30 23:04:52 +02:00
parent 64f835f719
commit be6cbf90d7
7 changed files with 922 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Build Plan — sequencing & commits
+
+Two tracks run in parallel and rarely touch the same files: **Backend (automation)** and
+**Frontend (UI overhaul)**. Backend can progress regardless of palette sign-off; the new
+feature *pages* wait for the design system (Increment F1).
+
+Each step ends with a build (`dotnet build` and/or `npm run build`) and a commit, per the
+established pattern.
+
+## Backend track (B)
+
+| Step | Deliverable | Key files | Migration |
+|------|-------------|-----------|-----------|
+| **B1** | Automation core domain + engine skeleton | enums, `AutomationRule`, `AutomationAction`, `SenderPolicy`, `Email.IsPinned`, `MailThread.IsMuted`, `User.Screener*` | `AddAutomationCore` |
+| **B2** | `EnsureLabelAsync` on Gmail service + label cache | `IGmailService`, `GmailApiService` | — |
+| **B3** | `AutomationEngine.RunAsync` (matching, safe-apply, propose) + `Matches()` unit tests | `AutomationEngine`, `RuleMatcher` | — |
+| **B4** | `IRuleService` + `AutomationController` (rules CRUD + preview) | service, controller, `AutomationDtos` | — |
+| **B5** | Approval queue + activity + undo (`IAutomationActionService`) | service, controller endpoints | — |
+| **B6** | `ISenderPolicyService` + Screener + policy controller | service, controller | — |
+| **B7** | `AutomationWorker` + hook engine into incremental sync; `AutomationOptions`; DI wiring | worker, `SyncService`, `DependencyInjection`, `Options`, `appsettings` | — |
+| **B8** | Activity Summaries + Cleanup Reminders into `DigestService` | `DigestService` | — |
+| **B9** | Privacy Monitor (provider, service, controller, options, Null provider) | `Privacy/*`, DI, `appsettings` | `AddPrivacyFields` |
+
+> Commit boundaries roughly per step (B1–B2 may bundle; B3 stands alone with tests).
+
+## Frontend track (F)
+
+| Step | Deliverable | Notes |
+|------|-------------|-------|
+| **F0** | Tailwind + PostCSS + Radix + cva/lucide installed; `index.css` tokens; `darkMode:class`; `ThemeToggle`; build green | no page swaps yet |
+| **F1** | `components/ui/*` primitive set | button/card/input/dialog/sheet/dropdown/tabs/tooltip/toast/table/badge/switch/skeleton |
+| **F2** | App shell (`Layout`) on new system + theme toggle in topbar | biggest visual win |
+| **F3** | Dashboard | theme chart.js colors via tokens |
+| **F4** | Senders (+ policy dropdown, wired to B6) | |
+| **F5** | Unsubscribe (confidence meter) | |
+| **F6** | Search / Folders / Cleanup | |
+| **F7** | New pages: Rules editor, Review queue, Screener, Activity, Read-Later, Privacy | depends on B4–B9 |
+| **F8** | Landing polish; delete `styles.css` | |
+
+## Suggested interleave
+
+```
+B1+B2 ─▶ B3 ─▶ B4 ─▶ B5 ─▶ B6 ─▶ B7 ─▶ B8 ─▶ B9
+F0 ─▶ F1 ─▶ F2 ─▶ F3 ─▶ F4 ─▶ F5 ─▶ F6 ─▶ F7(needs B4–B9) ─▶ F8
+```
+
+Practical order to actually build in: **F0 → F1 → F2** (get the app looking modern fast
+and de-risk the stack), then **B1→B3** (the engine core), then alternate
+feature-by-feature (B4+F7-rules, B5+F7-review, B6+F7-screener, …), finishing with B8/B9
+ their pages, then F3–F6 restyles and F8 cleanup.
+
+## Definition of done (per feature)
+
+- Backend builds (0 errors), unit/integration tests for engine logic pass.
+- Frontend builds; page works in light **and** dark.
+- Every new endpoint scoped to `UserId`; destructive paths go through approval.
+- Spec checklist items ticked.
+- Committed (push remains blocked by the known `git.cesnimda.uk` credential issue — local only).
+
+## Open items to confirm before/while building
+
+1. **Accent color** sign-off (indigo proposed; alternatives listed in `ui-overhaul.md`).
+2. Whether Activity Summaries need a **separate toggle** from the analytics digest (default: fold in).
+3. First-match-wins vs all-matching-rules for rule evaluation (default: **first-match-wins** by priority).