What this file is
This is the attention mechanism of the Flow knowledge base. Read this before any other doc. It tells you exactly which documents to load based on what you are working on — and in what order. Never load docs at random; always use this map.
Weight scale: 10 = always load · 8–9 = load for related task · 5–7 = reference if needed · 1–4 = legacy/history
Always Load (Weight 10) — Every Session
These docs are the foundation. Read them at the start of every session regardless of task.
| Doc | What it contains | Tokens |
|---|---|---|
| overview | Full tech stack, all architectural decisions, what does NOT exist and why | ~120 |
| database-schema | All ~30 tables, RLS pattern, key views (public_profiles), known tech debt | ~300 |
| 2026-04-27-architecture-refactor-master-guide | Pre-task checklist, DB standards, RLS mandatory pattern, tech debt register (§4), security rules — read §1 checklist before any DB/schema work | ~800 |
Load By Task (Weight 8–9)
Read the matching row before writing any code.
| Task area | Load this doc | Weight |
|---|---|---|
| Any DB schema / migration / RLS | 2026-04-27-architecture-refactor-master-guide §1 checklist | 10 |
| Auth screens visual design | auth-screens | 9 |
| Auth / registration wizard logic | feat-registration-wizard-v2 | 9 |
| UI components / theme tokens / icons | refactor-theme-tokens | 9 |
| Supabase Edge Functions | services | 9 |
| Tag system / recommendations | feat-registration-wizard-v2 + this file’s tag section below | 9 |
| Localization / i18n | localization | 8 |
| Error handling / logging | feat-unified-error-handling | 8 |
| Push notifications | crash-reporting-settings | 8 |
| Event discovery / feed | feat-event-discovery-live | 8 |
| Event details screen (v3, May 2026) | feat-event-details-v3 | 9 |
| Event series (recurring events) | feat-event-series | 8 |
| Social / crews / friends | feature-crew-chat | 8 |
| Web admin portal | overview | 8 |
| Deployment | guide | 8 |
| Branch / commit workflow | branch-strategy | 7 |
Quick Reference (Weight 5–7)
Load only when you need to verify a specific fact.
| Need to check… | Load this |
|---|---|
| Intentional RLS / service_role bypasses | security-bypass-log |
| API endpoints / PostgREST contracts | api-documentation |
| Supabase migration history | database-schema (migration log section) |
| Gamification rules (XP, badges, karma) | feature-xp-karma-score |
| Brand identity / colors / voice | brand-identity |
| Instagram strategy (algorithm, pillars, 90d plan) | instagram-strategy |
| Instagram voice + caption templates + format mapping | instagram-voice-and-templates |
| Open product questions | open-questions |
| Feature tracker / roadmap | feature-tracker |
| Local dev setup | local-setup |
| Architecture issues (infra proposals) | 1-event-bus |
| Recent change / release & handoff history | project/changelog/ — dated entries; latest 2026-06-23-develop-editorial-redesign-handoff |
Tag & Recommendation System (inline — Weight 9)
Tables: tags (id, name, category ENUM, parent_id, usage_count), tag_affinity (tag_a_id, tag_b_id, weight FLOAT, co_occurrences, computed_at)
Weight formula: P(B|A) = co_occurrences(A,B) / count(profiles_with_A) — asymmetric conditional probability.
Flutter providers:
tagListProvider— all tags, global singleton, prefetched at wizard mounttagAffinityProvider(tagId)—FutureProvider.autoDispose.family, per-tag affinity weights fromtag_affinity
orderedTags(allTags, selectedNames, lastSelectedName, {affinityWeights}):
- Selected (in selection order)
- Neural path if
affinityWeightsnon-empty → sort unselected byP(B|lastSelected)desc - Structural fallback if empty → same
parentIdorcategory, sorted byusageCount - Rest by
usageCountdesc
Edge Function: compute-tag-affinity — daily cron 03:00 UTC, reads profiles.interests[], builds co-occurrence matrix, upserts into tag_affinity. Deployed 2026-04-27.
Do Not Load (Weight 1–4) — Legacy / History
These are archived. Never update them. Reference only if explicitly asked about history.
| Doc | Reason |
|---|---|
legacy/ folder | Archived microservices era, pre-Supabase migration |
| 2-redis-socketio | Resolved by Supabase-only migration |
| database-audit-2026-03-24 | Historical audit, superseded by live schema |
After Finishing Code — Update Protocol
After any code change, update the matching doc immediately (do not batch):
| Changed | Update |
|---|---|
| Any Flutter screen | mobile/features/<area>/<feature>.md |
| Supabase schema | backend/database-schema.md |
| Edge Function | architecture/services.md + backend/api-documentation.md |
| Auth screen visual design | mobile/features/auth/auth-screens.md |
| Auth / wizard logic | mobile/features/auth/feat-registration-wizard-v2.md |
| Theme / design system / icons | mobile/features/ui/refactor-theme-tokens.md |
| New tag/recommendation logic | This file (tag section above) + feat-registration-wizard-v2.md |
| Architecture decision | architecture/overview.md |
| New l10n keys | mobile/features/localization.md |
| Branch / worktree changes | mobile/setup.md |
develop advanced / branch integration / release | New dated entry in project/changelog/ |
If no doc exists for the area → create one, then add it to this map.