Feature Spec — Notify Me & Categories

Status: Draft · Author: @relbns · ClickUp: CU-86c1p963g

Why this doc exists

We already have the Notification Service v1 DR — the notifications engine. But schema doubts (flat-vs-nested, labels/translation, aliases) kept surfacing because the feature was not pinned. This spec is the umbrella: it defines the feature scope, phasing, the one canonical category model + its governance, and the surfaces that read/write it — so the schema and each phase's Design Doc derive from it instead of being guessed.

1. TL;DR

Residents pick notification topics from one canonical category taxonomy, and get a daily digest of new events that match. BeWith owns the taxonomy (levels 1–2 are canonical, because we run analytics on them); organizations give aliases (their own display names) and request new categories (BeWith approves); level 3 is dynamic (org/community-defined). Everything runs behind the platform feature-flags system (already in production) so nothing is affected until we turn it on — and even then, per org/community/member, or super-admin-only for an internal pilot.

2. The model in one picture — one taxonomy, keys everywhere

There is one new taxonomy store. Everything else holds keys that point at it.

• notify-categories (one collection) = the definition (keys, labels, hierarchy, scope) plus each doc's embedded overrides (org/community aliases). Faceted: Main types × up to 3 levels. L1+L2 canonical (BeWith-owned, analytics dimensions, closed). L3 dynamic (org/community).
• users.notify_categories = what the resident picked (keys).
• groups.custom_filters_keys = what the event is tagged with (keys), alongside the legacy custom_filters free strings (non-destructive).
• Match = intersection of the two key-sets. Both reference the same canonical keys, so matching is faithful.
• Aliases are the opposite of duplication: one canonical key, many org/community display names — an embedded overrides: [{scope, scopeId, label}] array on the doc, resolved from cache at display time (community > org > canonical). This collapses today's fragmentation (one concept spelled 5 ways → one key + display overrides).

3. Surfaces — what reads/writes the taxonomy

Surface	Repo	Reads taxonomy?	Writes taxonomy?	Language	Aliases?	Phase
Resident notify-picker	bewith-consumer-frontend	reads active canonical list	writes users.notify_categories (keys)	community language	display-only (later)	A (minimal) → B (full)
Notify digest engine	backend-services	reads notify_categories + custom_filters_keys	no	n/a (keys)	no	A (DR)
Manual send + filter	organization-dashboard	reads canonical list for the picker	no (filters by notify_categories)	admin	display	A
Event tagging (create/edit + AI)	backend-services / PHP	reads canonical list	writes groups.custom_filters_keys	n/a (keys)	no	0 (backfill) → C (AI)
Taxonomy admin	organization-dashboard / support-tool	reads full tree	BeWith: canonical L1/L2 · org: aliases + L3 + requests	he/en	yes	B
Analytics / insights	organization-dashboard	reads canonical L1/L2 keys as dimensions	no	display	via alias	B
Phase 0 mapping	backend-services / migration	reads legacy strings	builds categories; backfills custom_filters_keys	he/en	no	0

The schema below is derived from this table — it must serve exactly these reads/writes, nothing more.

4. Phasing

Pivot (2026-07-19, pending Aviad): Gali asked that the category list be brand-new values, not derived from the existing categories. If approved, this obviates Phase 0's mapping — the taxonomy is greenfield, there is nothing to reconcile. Ariel is not committing to dropping Phase 0 until Aviad signs off, so Phase 0 stays below as conditional. Meanwhile we ship a POC of the whole mechanism using Gali's new categories, to show progress.

Phase	ClickUp	Ships	Depends on
POC — end-to-end mechanism	CU-86cafrhcy	Seed Gali's new categories in categories + minimal resident picker + tag a few events + run the digest → a resident gets the right notification. Minimal UI, all behind FF, fully deletable.	FF (in prod)
Phase 0 — category consolidation (CONDITIONAL — pending Aviad)	CU-86cahy31f	Map today's community_tags/custom_filters/preferred_categories into the canonical list + backfill groups.custom_filters_keys. Obviated if greenfield is approved.	Aviad decision
Phase A — notify engine (Track B)	CU-86cafrhcy	Productionise the POC: digest engine + users.notify_categories + minimal resident picker + manual-send filter, behind FF	FF (done) + a category list (greenfield or Phase 0)
Phase B — taxonomy & preferences	—	Full resident preference screen (types × levels) + taxonomy admin (aliases, requests, L3) + org-dash per-user view/filter + profile + insights	Phase A
Phase C — AI auto-tagging	—	Auto-tag events with canonical keys on create/edit (AI + admin override); API to PHP	a category list

Key sequencing truth: the engine needs both sides to speak the same keys — resident notify_categories and event custom_filters_keys. Greenfield makes this cheap (seed new categories, tag events directly, no legacy mapping); Phase 0 was the expensive path (reconcile ~5,000 legacy values). The engine is identical either way — only where the keys come from differs, and that source is swappable without touching the engine. So the POC proves the mechanism now; the greenfield-vs-Phase-0 source decision is Aviad's and does not block it. Worst case, the POC's seeded categories are deleted and replaced with the chosen list.

5. Feature flag — use the platform feature-flags system (NOT a bespoke collection)

The platform now has a full feature-flags system (live in production) — this supersedes the notification-feature-settings collection proposed in the DR.

• Where: apps/authorization/src/feature-flags (collection featureFlags); managed from the support tool via internal-gateway (GET/CREATE/UPSERT/RESOLVE_FEATURE_FLAG, RESOLVE_EFFECTIVE_FEATURE_FLAGS).
• Shape: { key, defaultEnabled, rules: [{scope, scopeId, enabled}], status, audience }.
  • scope = org | community | member (precedence member > community > org > default) — exactly our org/community/user gating.
  • audience = everyone | super-admin. super-admin = super-admins resolve normally, everyone else forced OFF — a safe internal pilot in prod. Flip to everyone to roll out.
  • status = active | archived; full audit trail.
• How the engine uses it: define a flag key (e.g. notify.event-digest); resolve it per resident (resolve-feature-flag.helper with {memberId, communityIds, orgId, isSuperAdmin}) before dispatch. Off by default → no one affected until turned on.
• Send-time config: the FF is boolean gating only. The digest send-time (default 09:00, org timezone) is a separate small concern — for v1 default it; a per-org configurable send-time can live in a tiny settings doc or the platform-jobs schedule later (not on the FF, and no longer on notification-feature-settings).

6. The notify-categories schema — one collection (derived from §3)

One collection: notify-categories (Aviad prefers fewer collections; aliases live inside it as embedded overrides, requests as status:pending docs — no separate stores). Small, stable reference data (~6 types × ≤20 × ≤20 ≈ a few thousand nodes, rarely written). Levels = level + parentKey (flat nodes). Reading the tree is one find (the small active set) + build parent→child in memory + cache — NOT a per-request $graphLookup/aggregation. (Alternative: nested storage — one doc per type with children embedded — whole tree in one read.) L3 dynamic stays flat, read on-demand per community. The key on events/users is storage-shape-independent.

Field	Type	Notes
key	string (unique)	stable join id (what notify_categories / custom_filters_keys hold)
type	enum	interest · audience · district · department · emergency · general (Gali's Main types)
level	1 | 2 | 3	not every type uses all (audience/emergency/general = L1 only)
parentKey	string?	ref to parent's key (null at L1)
labels	{ he, en, … }	display only — the key is language-independent, so this is deferrable (inline map, or reuse the platform getTranslation)
scope	system | org | community	L1+L2 = system (canonical) · L3 = org/community (dynamic)
organizationId? / communityId?	number	for org/community scope
source	canonical | requested	requested = org-asked, awaits approval
status	active | pending | rejected	v1 shows active only
order / enabled / catalogVersion		display + versioning
overrides?	[{ scope, scopeId, label }]	embedded org/community aliases (display names); precedence community > org > canonical; sparse; resolved from cache

Aliases (org/community display-name overrides) = embedded in each category doc as overrides: [{ scope, scopeId, label }] — one collection, no extra store (Aviad-friendly). Resolved from cache (the taxonomy is cached anyway) → no runtime lookup (Baruch's ask): the only read is the cached tree. Precedence: community > org > canonical — a community under an org overrides the org's alias, which overrides BeWith's canonical label. Scale: aliases are rare admin writes and tiny; 16MB is not a real risk (≈ a few thousand possible per category, ≪ limit). The one theoretical cost — many communities writing overrides on a single hot category doc — is negligible at rare-write frequency; if a specific category ever suffers, split that one out later (YAGNI). Requests = a status:pending doc in the same collection (no separate store); deferred to Phase B.

7. Data model summary (all new pieces)

Store	Where	New?	Holds
notify-categories	Mongo	NEW	the taxonomy + embedded overrides (aliases) — ONE collection
users.notify_categories	SQL (users)	NEW column, nullable	resident's chosen topic keys
groups.custom_filters_keys (+ custom_filter_groups_keys)	SQL (groups)	NEW columns	event's category keys, alongside legacy custom_filters
(aliases + requests)	—	—	folded into notify-categories (embedded overrides; requests = status:pending docs). No separate collections.
featureFlags	Mongo	EXISTING (in production)	the gate for everything
notification-digest-runs, EVENT_DIGEST type	Mongo / enum	NEW (Phase A / DR)	digest idempotency + campaign type

8. Governance rules (what the schema encodes)

• L1 + L2 = canonical, BeWith-owned (scope:system, source:canonical) — the analytics dimensions, a closed list. Orgs do not create them.
• L3 = dynamic (scope:org/community) — orgs/residents define freely.
• Org wants a new L1/L2 → request (a status:pending doc in notify-categories, no separate collection) → BeWith approves → active.
• Alias = an org's display name over a canonical key (the key + analytics stay single; only the label differs per org).
• v1 = only-what-exists: seed the canonical list, allow L3 dynamic, residents pick from active; no org create/alias/request UI yet (that's Phase B).

9. Safety — no customer is affected

• system-categories is NOT overwritten. It still feeds admin surfaces (org-dashboard quick-insights, the communities-categories admin modal, a public /system/categories/:language, leaders-app autocomplete, assistant-ai). We build the new taxonomy in a new notify-categories collection; Phase 0 reconciles/migrates system-categories in as a deliberate, planned step later.
• Legacy groups.custom_filters strings are kept (feeds, search, stats, PHP readers unchanged); we only add the keys columns.
• Everything is behind the FF (default OFF; super-admin audience for the internal pilot).

10. Open decisions

1. Labels / translation — inline {he,en} vs the platform translation system. Deferrable (key is language-independent).
2. Send-time config home — default 09:00 for v1; per-org configurable later (small settings doc / platform-jobs schedule).
3. Category source — greenfield (Gali's new list) vs Phase 0 mapping — Aviad's call. POC proceeds greenfield; swappable without engine changes.

Locked: one taxonomy = notify-categories (ONE collection · aliases embedded as overrides[] · flat+cache, no runtime lookup) · keys on both sides · empty notify_categories → no notifications (opt-in) · manual send filters by notify_categories · FF = the platform feature-flags system · don't overwrite system-categories.

11. What this changes in the existing DR

The Notification Service v1 DR should be updated to:

• Replace the proposed notification-feature-settings collection (§5/§6) with the platform feature-flags system (§5 here).
• Add the event-side groups.custom_filters_keys column to §5 (it currently mentions keys only conceptually in §18).
• Reference this spec as the umbrella; keep the digest engine, idempotency (notification-digest-runs), SMS cap, per-community, and dispatch reuse as-is.

---

The notifications engine lives in the Notification Service v1 DR. Phase 0 (CU-86cahy31f) builds the canonical list this spec depends on. This spec is the source of truth for the feature and the category model; the schema derives from §3–§8.