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 / registration wizard | feat-registration-wizard-v2 | 9 |
| UI components / theme tokens | 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 |
| 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 |
| Open product questions | open-questions |
| Feature tracker / roadmap | feature-tracker |
| Local dev setup | local-setup |
| Architecture issues (infra proposals) | 1-event-bus |
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 / wizard flow | mobile/features/auth/feat-registration-wizard-v2.md |
| Theme / design system | 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 |
If no doc exists for the area → create one, then add it to this map.