# orionsheep/wordlink architecture

> Architecture diagram of the GitHub repository orionsheep/wordlink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orionsheep/wordlink
- Repository: https://github.com/orionsheep/wordlink

## Overview

WordLink is a vocabulary workspace centered on a typed word-neighborhood graph, with quizzes, reading, ambient study, custom word books, community notes, and AI features around it. The graph shows the documented user-facing stages and sampled API-to-service relationships; database-backed behavior is summarized where the excerpts show Prisma use. The README also describes a separate WordLink-Edge training and evaluation pipeline. Some UI-to-route and unsampled feature wiring is not shown, so those connections are omitted rather than inferred.

Main entry points: [`src/lib/prisma.ts`](https://github.com/orionsheep/wordlink/blob/main/src/lib/prisma.ts) (PostgreSQL Data), [`src/app/api/articles/route.ts`](https://github.com/orionsheep/wordlink/blob/main/src/app/api/articles/route.ts) (Article Recommendations), [`src/app/api/libraries/route.ts`](https://github.com/orionsheep/wordlink/blob/main/src/app/api/libraries/route.ts) (Library Listing API), [`src/app/api/ai/chat/route.ts`](https://github.com/orionsheep/wordlink/blob/main/src/app/api/ai/chat/route.ts) (AI Tutor Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_study["Word Study"]
  node_workspace["Vocabulary Workspace<br/>[page.tsx]"]
  node_word_data["Word Data Access<br/>[data.ts]"]
  node_graph_api["Word Graph API<br/>[route.ts]"]
  node_graph_view["Word Graph View"]
  node_quiz["Quiz Experience<br/>[page.tsx]"]
  node_quiz_record["Quiz Recording API<br/>[route.ts]"]
  node_memory["Word Memory Model<br/>[memory.ts]"]
end

subgraph group_content["Reading and Ambient"]
  node_articles_api["Article Recommendations<br/>[route.ts]"]
  node_recommender["Reading Recommender<br/>[recommender.ts]"]
  node_reader["Graded Reader<br/>[page.tsx]"]
  node_ambient["Ambient Mode<br/>[AmbientScreen.tsx]"]
  node_soundscape["Soundscape Engine"]
  node_music["Background Music"]
end

subgraph group_community["Libraries and Notes"]
  node_library_api["Library Listing API<br/>[route.ts]"]
  node_library_data["Library Data<br/>[data.ts]"]
  node_notes_api["Community Notes API<br/>[route.ts]"]
end

subgraph group_platform["Identity and Data"]
  node_auth["Session and Auth<br/>[auth.ts]"]
  node_database[("PostgreSQL Data<br/>[prisma.ts]")]
end

subgraph group_ai_model["AI and Model"]
  node_ai_chat["AI Tutor Chat<br/>[route.ts]"]
  node_ai_gateway["AI Gateway<br/>[gateway.ts]"]
  node_passport["Learning Passport<br/>[route.ts]"]
  node_training["SFT and DPO Pipeline<br/>[run_pipeline.py]"]
  node_benchmark["Model Benchmark"]
end

node_learner(("Learner"))

node_learner -->|"studies in"| node_workspace
node_workspace -->|"loads graph data"| node_graph_api
node_graph_api -->|"reads word links"| node_word_data
node_workspace -->|"renders graph"| node_graph_view
node_learner -->|"takes quizzes"| node_quiz
node_quiz_record -->|"updates memory"| node_memory
node_quiz_record -->|"persists results"| node_database
node_learner -->|"reads articles"| node_reader
node_reader -->|"requests articles"| node_articles_api
node_articles_api -->|"gets session"| node_auth
node_articles_api -->|"scores candidates"| node_recommender
node_articles_api -->|"reads due words"| node_database
node_learner -->|"enters ambient mode"| node_ambient
node_ambient -->|"plays soundscape"| node_soundscape
node_ambient -.->|"plays background music"| node_music
node_learner -->|"browses word books"| node_library_api
node_library_api -->|"lists system books"| node_library_data
node_library_api -->|"checks session"| node_auth
node_library_api -->|"reads user books"| node_database
node_learner -.->|"shares word notes"| node_notes_api
node_notes_api -->|"gets session"| node_auth
node_notes_api -->|"reads and writes notes"| node_database
node_learner -->|"asks tutor"| node_ai_chat
node_ai_chat -->|"gets session"| node_auth
node_ai_chat -->|"streams completion"| node_ai_gateway
node_ai_chat -->|"stores sessions"| node_database
node_learner -->|"views learning report"| node_passport
node_passport -->|"generates narrative"| node_ai_gateway
node_passport -->|"aggregates study metrics"| node_database
node_training -->|"evaluates model"| node_benchmark

click node_workspace "https://github.com/orionsheep/wordlink/blob/main/src/app/study/page.tsx"
click node_word_data "https://github.com/orionsheep/wordlink/blob/main/src/lib/data.ts"
click node_graph_api "https://github.com/orionsheep/wordlink/blob/main/src/app/api/fission/route.ts"
click node_graph_view "https://github.com/orionsheep/wordlink/blob/main/src/components/PanelFissionGraph.tsx"
click node_quiz "https://github.com/orionsheep/wordlink/blob/main/src/app/quiz/page.tsx"
click node_quiz_record "https://github.com/orionsheep/wordlink/blob/main/src/app/api/quiz/record/route.ts"
click node_memory "https://github.com/orionsheep/wordlink/blob/main/src/lib/memory.ts"
click node_articles_api "https://github.com/orionsheep/wordlink/blob/main/src/app/api/articles/route.ts"
click node_recommender "https://github.com/orionsheep/wordlink/blob/main/src/lib/reader-engine/recommender.ts"
click node_reader "https://github.com/orionsheep/wordlink/blob/main/src/app/read/%5Bid%5D/page.tsx"
click node_ambient "https://github.com/orionsheep/wordlink/blob/main/src/components/ambient/AmbientScreen.tsx"
click node_soundscape "https://github.com/orionsheep/wordlink/blob/main/src/components/ambient/SoundScapeEngine.ts"
click node_music "https://github.com/orionsheep/wordlink/blob/main/src/components/ambient/BackgroundMusicEngine.ts"
click node_library_api "https://github.com/orionsheep/wordlink/blob/main/src/app/api/libraries/route.ts"
click node_library_data "https://github.com/orionsheep/wordlink/blob/main/src/lib/data.ts"
click node_notes_api "https://github.com/orionsheep/wordlink/blob/main/src/app/api/notes/route.ts"
click node_auth "https://github.com/orionsheep/wordlink/blob/main/src/lib/auth.ts"
click node_database "https://github.com/orionsheep/wordlink/blob/main/src/lib/prisma.ts"
click node_ai_chat "https://github.com/orionsheep/wordlink/blob/main/src/app/api/ai/chat/route.ts"
click node_ai_gateway "https://github.com/orionsheep/wordlink/blob/main/src/lib/ai/gateway.ts"
click node_passport "https://github.com/orionsheep/wordlink/blob/main/src/app/api/ai/passport/route.ts"
click node_training "https://github.com/orionsheep/wordlink/blob/main/model_training/run_pipeline.py"
click node_benchmark "https://github.com/orionsheep/wordlink/blob/main/model_training/04_evaluate_benchmark.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workspace,node_word_data,node_graph_api,node_graph_view,node_quiz,node_quiz_record,node_memory toneBlue
class node_articles_api,node_recommender,node_reader,node_ambient,node_soundscape,node_music toneAmber
class node_library_api,node_library_data,node_notes_api toneMint
class node_auth,node_database toneRose
class node_ai_chat,node_ai_gateway,node_passport,node_training,node_benchmark,node_learner toneIndigo
```

## Components

### Word Study

- [Vocabulary Workspace](https://github.com/orionsheep/wordlink/blob/main/src/app/study/page.tsx): `src/app/study/page.tsx`
- [Word Data Access](https://github.com/orionsheep/wordlink/blob/main/src/lib/data.ts): `src/lib/data.ts`
- [Word Graph API](https://github.com/orionsheep/wordlink/blob/main/src/app/api/fission/route.ts): `src/app/api/fission/route.ts`
- [Word Graph View](https://github.com/orionsheep/wordlink/blob/main/src/components/PanelFissionGraph.tsx): `src/components/PanelFissionGraph.tsx`
- [Quiz Experience](https://github.com/orionsheep/wordlink/blob/main/src/app/quiz/page.tsx): `src/app/quiz/page.tsx`
- [Quiz Recording API](https://github.com/orionsheep/wordlink/blob/main/src/app/api/quiz/record/route.ts): `src/app/api/quiz/record/route.ts`
- [Word Memory Model](https://github.com/orionsheep/wordlink/blob/main/src/lib/memory.ts): `src/lib/memory.ts`

### Reading and Ambient

- [Article Recommendations](https://github.com/orionsheep/wordlink/blob/main/src/app/api/articles/route.ts): `src/app/api/articles/route.ts`
- [Reading Recommender](https://github.com/orionsheep/wordlink/blob/main/src/lib/reader-engine/recommender.ts): `src/lib/reader-engine/recommender.ts`
- [Graded Reader](https://github.com/orionsheep/wordlink/blob/main/src/app/read/%5Bid%5D/page.tsx): `src/app/read/[id]/page.tsx`
- [Ambient Mode](https://github.com/orionsheep/wordlink/blob/main/src/components/ambient/AmbientScreen.tsx): `src/components/ambient/AmbientScreen.tsx`
- [Soundscape Engine](https://github.com/orionsheep/wordlink/blob/main/src/components/ambient/SoundScapeEngine.ts): `src/components/ambient/SoundScapeEngine.ts`
- [Background Music](https://github.com/orionsheep/wordlink/blob/main/src/components/ambient/BackgroundMusicEngine.ts): `src/components/ambient/BackgroundMusicEngine.ts`

### Libraries and Notes

- [Library Listing API](https://github.com/orionsheep/wordlink/blob/main/src/app/api/libraries/route.ts): `src/app/api/libraries/route.ts`
- [Library Data](https://github.com/orionsheep/wordlink/blob/main/src/lib/data.ts): `src/lib/data.ts`
- [Community Notes API](https://github.com/orionsheep/wordlink/blob/main/src/app/api/notes/route.ts): `src/app/api/notes/route.ts`

### Identity and Data

- [Session and Auth](https://github.com/orionsheep/wordlink/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [PostgreSQL Data](https://github.com/orionsheep/wordlink/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`

### AI and Model

- [AI Tutor Chat](https://github.com/orionsheep/wordlink/blob/main/src/app/api/ai/chat/route.ts): `src/app/api/ai/chat/route.ts`
- [AI Gateway](https://github.com/orionsheep/wordlink/blob/main/src/lib/ai/gateway.ts): `src/lib/ai/gateway.ts`
- [Learning Passport](https://github.com/orionsheep/wordlink/blob/main/src/app/api/ai/passport/route.ts): `src/app/api/ai/passport/route.ts`
- [SFT and DPO Pipeline](https://github.com/orionsheep/wordlink/blob/main/model_training/run_pipeline.py): `model_training/run_pipeline.py`
- [Model Benchmark](https://github.com/orionsheep/wordlink/blob/main/model_training/04_evaluate_benchmark.py): `model_training/04_evaluate_benchmark.py`

### Other components

- **Learner**

## Connections

- Learner → Vocabulary Workspace: studies in (evidence: `README.md`)
- Vocabulary Workspace → Word Graph API: loads graph data (evidence: `README.md`)
- Word Graph API → Word Data Access: reads word links (evidence: `README.md`)
- Vocabulary Workspace → Word Graph View: renders graph (evidence: `README.md`)
- Learner → Quiz Experience: takes quizzes (evidence: `README.md`)
- Quiz Recording API → Word Memory Model: updates memory (evidence: `src/app/api/quiz/record/route.ts`)
- Quiz Recording API → PostgreSQL Data: persists results (evidence: `src/app/api/quiz/record/route.ts`)
- Learner → Graded Reader: reads articles (evidence: `README.md`)
- Graded Reader → Article Recommendations: requests articles (evidence: `README.md`)
- Article Recommendations → Session and Auth: gets session (evidence: `src/app/api/articles/route.ts`)
- Article Recommendations → Reading Recommender: scores candidates (evidence: `src/app/api/articles/route.ts`)
- Article Recommendations → PostgreSQL Data: reads due words (evidence: `src/app/api/articles/route.ts`)
- Learner → Ambient Mode: enters ambient mode (evidence: `README.md`)
- Ambient Mode → Soundscape Engine: plays soundscape (evidence: `README.md`)
- Ambient Mode → Background Music: plays background music
- Learner → Library Listing API: browses word books (evidence: `README.md`)
- Library Listing API → Library Data: lists system books (evidence: `src/app/api/libraries/route.ts`)
- Library Listing API → Session and Auth: checks session (evidence: `src/app/api/libraries/route.ts`)
- Library Listing API → PostgreSQL Data: reads user books (evidence: `src/app/api/libraries/route.ts`)
- Learner → Community Notes API: shares word notes
- Community Notes API → Session and Auth: gets session (evidence: `src/app/api/notes/route.ts`)
- Community Notes API → PostgreSQL Data: reads and writes notes (evidence: `src/app/api/notes/route.ts`)
- Learner → AI Tutor Chat: asks tutor (evidence: `README.md`)
- AI Tutor Chat → Session and Auth: gets session (evidence: `src/app/api/ai/chat/route.ts`)
- AI Tutor Chat → AI Gateway: streams completion (evidence: `src/app/api/ai/chat/route.ts`)
- AI Tutor Chat → PostgreSQL Data: stores sessions (evidence: `src/app/api/ai/chat/route.ts`)
- Learner → Learning Passport: views learning report (evidence: `README.md`)
- Learning Passport → AI Gateway: generates narrative (evidence: `src/app/api/ai/passport/route.ts`)
- Learning Passport → PostgreSQL Data: aggregates study metrics (evidence: `src/app/api/ai/passport/route.ts`)
- SFT and DPO Pipeline → Model Benchmark: evaluates model (evidence: `README.md`)