|
| 1 | +# Social Knowledge Building & Competition |
| 2 | + |
| 3 | +> Vision: A federated knowledge graph where each learner has their own evolving |
| 4 | +> view. Graphs grow as you learn; you can browse how others structure the same |
| 5 | +> concepts, selectively adopt relationships, compete on quiz items, and |
| 6 | +> negotiate "ground truth" collaboratively. |
| 7 | +
|
| 8 | +## Core Principles |
| 9 | + |
| 10 | +1. **Personal graph is sovereign** — your concepts, relationships, quiz items, |
| 11 | + and FSRS scheduling state belong to you. Your devices sync automatically |
| 12 | + via the CRDT layer (Phase 4, row-level LWW). |
| 13 | +2. **Concepts are shared, opinions differ** — a concept like "Docker" exists |
| 14 | + once in a shared pool, but the *relationships* around it ("Docker is |
| 15 | + prerequisite of Kubernetes" vs "Docker is related to Kubernetes") are |
| 16 | + per-user opinions that can diverge intentionally. |
| 17 | +3. **Adoption by choice, not automatic merge** — when you see someone's |
| 18 | + different relationship structure, you can inspect it, compare it to yours, |
| 19 | + and adopt it with a tap. This is explicit, not background sync. |
| 20 | +4. **Quiz formats evolve** — flash cards are the starting point. The quiz item |
| 21 | + model should be extensible toward multiple-choice, visual quizzes, and |
| 22 | + diagram-based questions without breaking the knowledge graph or FSRS state. |
| 23 | + |
| 24 | +## Data Model Evolution |
| 25 | + |
| 26 | +### Current (Personal Graph) |
| 27 | + |
| 28 | +``` |
| 29 | +User A's graph: |
| 30 | + concepts: [Docker, Kubernetes, Pods] |
| 31 | + relationships: [K8s --prerequisite--> Docker, Pods --composition--> K8s] |
| 32 | + quizItems: [personal FSRS state per item] |
| 33 | +``` |
| 34 | + |
| 35 | +### Future (Federated Graph) |
| 36 | + |
| 37 | +``` |
| 38 | +Shared concept pool: |
| 39 | + concepts: [Docker, Kubernetes, Pods, ...] (canonical definitions) |
| 40 | +
|
| 41 | +User A's view: |
| 42 | + relationships: [K8s --prerequisite--> Docker] (A's opinion) |
| 43 | + quizItems: [A's FSRS state] |
| 44 | + adoptedFrom: {r42: userB} (tracking provenance) |
| 45 | +
|
| 46 | +User B's view: |
| 47 | + relationships: [K8s --enables--> Docker] (B's opinion) |
| 48 | + quizItems: [B's FSRS state] |
| 49 | +``` |
| 50 | + |
| 51 | +### Key Schema Changes |
| 52 | + |
| 53 | +1. **`owner_id`** on relationships, quiz items — distinguishes "mine" from |
| 54 | + "theirs" without separate tables |
| 55 | +2. **`provenance`** on adopted relationships — tracks who you adopted from and |
| 56 | + when, enabling "undo adoption" and social credit |
| 57 | +3. **`quiz_format`** enum on quiz items — `flashcard | multipleChoice | visual | |
| 58 | + diagramLabel` — extensible without schema migration |
| 59 | +4. **`alternatives`** JSON on multiple-choice quiz items — stores distractor |
| 60 | + options alongside the correct answer |
| 61 | +5. **Concept deduplication** — shared concept pool uses content-addressable IDs |
| 62 | + (hash of name + source) or server-assigned canonical IDs after merge |
| 63 | + |
| 64 | +## Social Features |
| 65 | + |
| 66 | +### Browse & Compare |
| 67 | + |
| 68 | +- View another user's relationship graph overlaid on yours (different edge |
| 69 | + colors) |
| 70 | +- Diff view: "User B has 3 relationships you don't, you have 2 they don't" |
| 71 | +- Tap any foreign relationship to preview, then adopt or dismiss |
| 72 | + |
| 73 | +### Selective Adoption |
| 74 | + |
| 75 | +- One-tap adopt: copies a relationship into your graph with provenance metadata |
| 76 | +- Batch adopt: "adopt all of User B's relationships for this concept cluster" |
| 77 | +- Undo adoption: removes the relationship and its provenance record |
| 78 | + |
| 79 | +### Competition |
| 80 | + |
| 81 | +- Challenge a friend: "quiz me on your mastered concepts" (existing mechanic) |
| 82 | +- Leaderboard: who has the most stable (high-retrievability) graph? |
| 83 | +- Concept coverage race: who can master a topic cluster first? |
| 84 | + |
| 85 | +### Negotiation |
| 86 | + |
| 87 | +- Propose a relationship change to another user (like a PR) |
| 88 | +- Vote on contested relationships within a wiki group |
| 89 | +- "Ground truth" emerges from consensus, not authority |
| 90 | + |
| 91 | +## Quiz Format Evolution |
| 92 | + |
| 93 | +### Phase 1: Current (Flash Cards) |
| 94 | + |
| 95 | +```dart |
| 96 | +QuizItem(question: 'What is Docker?', answer: 'A container runtime') |
| 97 | +``` |
| 98 | + |
| 99 | +### Phase 2: Multiple Choice |
| 100 | + |
| 101 | +```dart |
| 102 | +QuizItem( |
| 103 | + question: 'What is Docker?', |
| 104 | + answer: 'A container runtime', |
| 105 | + format: QuizFormat.multipleChoice, |
| 106 | + alternatives: ['A programming language', 'An operating system', 'A database'], |
| 107 | +) |
| 108 | +``` |
| 109 | + |
| 110 | +Distractors can be: |
| 111 | +- **AI-generated** — Claude generates plausible wrong answers from nearby |
| 112 | + concepts in the graph |
| 113 | +- **Graph-derived** — siblings of the correct concept (same parent, same |
| 114 | + relationship type) make natural distractors |
| 115 | + |
| 116 | +### Phase 3: Visual Quizzes |
| 117 | + |
| 118 | +- "Which node in this subgraph represents Docker?" (highlight the correct node) |
| 119 | +- "Draw the missing relationship" (given two concepts, name the edge) |
| 120 | +- "Label this diagram" (given a subgraph, fill in concept names) |
| 121 | + |
| 122 | +### Phase 4: Concept Splitting Quizzes |
| 123 | + |
| 124 | +- "Docker was split into Docker Images, Docker Containers, and Docker Networks. |
| 125 | + Which sub-concept does this description belong to?" |
| 126 | +- Tests understanding at the sub-concept level after a split |
| 127 | + |
| 128 | +## Implementation Phases |
| 129 | + |
| 130 | +### Phase S1: Shared Concept Pool |
| 131 | + |
| 132 | +- Server-side concept deduplication (name + source hash → canonical ID) |
| 133 | +- Personal graphs reference shared concept IDs |
| 134 | +- No relationship sharing yet — just concepts |
| 135 | + |
| 136 | +### Phase S2: Relationship Browsing |
| 137 | + |
| 138 | +- API to fetch another user's relationships for a given concept cluster |
| 139 | +- Overlay UI on the knowledge graph (foreign edges as dashed/colored lines) |
| 140 | +- Diff computation (your edges vs theirs) |
| 141 | + |
| 142 | +### Phase S3: Selective Adoption + Provenance |
| 143 | + |
| 144 | +- `adoptRelationship(fromUser, relationshipId)` — copies into personal graph |
| 145 | +- Provenance tracking on adopted relationships |
| 146 | +- Undo adoption |
| 147 | + |
| 148 | +### Phase S4: Multiple Choice + Visual Quizzes |
| 149 | + |
| 150 | +- `QuizFormat` enum on `QuizItem` |
| 151 | +- AI distractor generation during extraction |
| 152 | +- Graph-derived distractors from sibling concepts |
| 153 | +- New quiz UI widgets per format |
| 154 | + |
| 155 | +### Phase S5: Negotiation + Consensus |
| 156 | + |
| 157 | +- Relationship proposals (like PRs) |
| 158 | +- Wiki-group voting on contested edges |
| 159 | +- Consensus threshold for "ground truth" relationships |
| 160 | + |
| 161 | +## Dependencies |
| 162 | + |
| 163 | +- **CRDT sync (Phase 4, #41)** — personal graph sync must work first |
| 164 | +- **Concept embeddings (#39)** — enables smart deduplication and distractor |
| 165 | + generation |
| 166 | +- **Local-first Drift (#40)** — all social features read from local DB, server |
| 167 | + pushes updates via changeset sync |
| 168 | + |
| 169 | +## Open Questions |
| 170 | + |
| 171 | +1. Should concept *definitions* (description field) also be per-user, or is |
| 172 | + the shared pool's definition canonical? |
| 173 | +2. How to handle concept splits in a shared pool — does splitting create new |
| 174 | + shared concepts, or personal sub-concepts? |
| 175 | +3. Should FSRS state ever be shared (e.g., "this concept is hard for 80% of |
| 176 | + learners")? |
| 177 | +4. How to prevent spam in relationship proposals / voting? |
0 commit comments