Skip to content

Commit ce5fe61

Browse files
BenMuschBenMusch
authored
Merge pull request #62 from BenMusch/llmRules
2 parents 92820b5 + d19b54f commit ce5fe61

File tree

3 files changed

+175
-0
lines changed

3 files changed

+175
-0
lines changed

‎.cursor/rules/architecture.mdc‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
alwaysApply: true
3+
---
4+
5+
# Word DB Server
6+
7+
Word DB Server is a Go backend server that powers multiple frontend applications for word study in scrabble-like games.
8+
9+
The most specialized of these applications is WordVault, which
10+
allows users to study alphagrams and track their progress using
11+
spaced repetition algorithms
12+
13+
## Core Data Models
14+
15+
**Alphagram:**
16+
17+
- Alphabetically sorted letters that can form one or more words
18+
- Each word must use exactly the letters provided (including duplicates)
19+
- Example: "NRU" creates words "RUN" and "URN"
20+
- Belongs to a specific lexicon (dictionary/language ruleset)
21+
- Same alphagram may have different valid words across lexicons
22+
23+
**Word:**
24+
25+
- Single valid word that can be formed from an alphagram
26+
- Contains lexicon symbols indicating word status (new, collins-only, etc.)
27+
- Lexicon symbols show word metadata, not lexicon membership
28+
29+
**Card (WordVault-specific):**
30+
31+
- Base unit for spaced repetition study
32+
- User and lexicon specific (same alphagram = different cards per user)
33+
- Tracks study progress and schedules reviews based on performance
34+
35+
**Deck (WordVault-specific):**
36+
37+
- Optional grouping mechanism for cards
38+
- Allows different study strategies and scheduling parameters
39+
- Example: separate deck for longer words with different retention targets
40+
41+
## Technical Architecture
42+
43+
### Server Framework
44+
45+
- **Framework:** Built using Connect RPC. Types defined in \*.proto files
46+
- **HTTP Server:** Configurable port with graceful shutdown handling
47+
- **Middleware:** Uses alice middleware for logging and request handling
48+
- **Authentication:** JWT-based authentication with Connect interceptors
49+
50+
### Database Layer
51+
52+
- **Primary Database:** PostgreSQL with pgx/v5 driver and connection pooling
53+
- Stores user data including wordvault_cards, wordvault_params, wordvault_decks
54+
- Uses JSONB fields for FSRS (spaced repetition) algorithm data
55+
- **Migration System:** golang-migrate/v4 with migrations in `db/migrations/`
56+
- **Query Generation:** sqlc for type-safe SQL queries from `db/queries/`
57+
- **Lexicon Data:** SQLite databases for word/alphagram lookup
58+
- Stored in `DataPath/lexica/db/` directory
59+
- Contains linguistic data optimized for fast searches
60+
61+
### API Structure
62+
63+
**Connect RPC Services:**
64+
65+
- **WordVaultService** (authenticated): Card management, spaced repetition scheduling, deck operations
66+
- **QuestionSearcher:** Alphagram and word searching functionality
67+
- **Anagrammer:** Anagram generation, blank tile challenges, build challenges
68+
- **WordSearcher:** Simple word lookups and definitions
69+
70+
### Key Internal Components
71+
72+
- **internal/wordvault:** FSRS spaced repetition logic using go-fsrs/v3 library
73+
- **internal/searchserver:** SQLite-based word and alphagram search engine
74+
- **internal/anagramserver:** GADDAG/KWG-based anagram generation using word-golib
75+
- **internal/auth:** JWT authentication and context management
76+
- **dbmaker:** Utility for creating and updating SQLite lexicon databases
77+
78+
### Deployment
79+
80+
- **Containerization:** Docker-based deployment
81+
- **CI/CD:** GitHub Actions pipeline for automated testing and deployment
82+
- **Database Management:** Migrations run automatically on startup

‎.cursor/rules/development.mdc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
alwaysApply: true
3+
---
4+
5+
# Development Rules
6+
7+
- **Do not run migrations or start the dev server directly**
8+
- The development environment runs via docker-compose in a separate directory
9+
- Database and server are containerized and managed externally

‎CLAUDE.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Word DB Server
2+
3+
Word DB Server is a Go backend server that powers multiple frontend applications for word study in scrabble-like games.
4+
5+
The most specialized of these applications is WordVault, which
6+
allows users to study alphagrams and track their progress using
7+
spaced repetition algorithms
8+
9+
## Core Data Models
10+
11+
**Alphagram:**
12+
13+
- Alphabetically sorted letters that can form one or more words
14+
- Each word must use exactly the letters provided (including duplicates)
15+
- Example: "NRU" creates words "RUN" and "URN"
16+
- Belongs to a specific lexicon (dictionary/language ruleset)
17+
- Same alphagram may have different valid words across lexicons
18+
19+
**Word:**
20+
21+
- Single valid word that can be formed from an alphagram
22+
- Contains lexicon symbols indicating word status (new, collins-only, etc.)
23+
- Lexicon symbols show word metadata, not lexicon membership
24+
25+
**Card (WordVault-specific):**
26+
27+
- Base unit for spaced repetition study
28+
- User and lexicon specific (same alphagram = different cards per user)
29+
- Tracks study progress and schedules reviews based on performance
30+
31+
**Deck (WordVault-specific):**
32+
33+
- Optional grouping mechanism for cards
34+
- Allows different study strategies and scheduling parameters
35+
- Example: separate deck for longer words with different retention targets
36+
37+
## Technical Architecture
38+
39+
### Server Framework
40+
41+
- **Framework:** Built using Connect RPC. Types defined in \*.proto files
42+
- **HTTP Server:** Configurable port with graceful shutdown handling
43+
- **Middleware:** Uses alice middleware for logging and request handling
44+
- **Authentication:** JWT-based authentication with Connect interceptors
45+
46+
### Database Layer
47+
48+
- **Primary Database:** PostgreSQL with pgx/v5 driver and connection pooling
49+
- Stores user data including wordvault_cards, wordvault_params, wordvault_decks
50+
- Uses JSONB fields for FSRS (spaced repetition) algorithm data
51+
- **Migration System:** golang-migrate/v4 with migrations in `db/migrations/`
52+
- **Query Generation:** sqlc for type-safe SQL queries from `db/queries/`
53+
- **Lexicon Data:** SQLite databases for word/alphagram lookup
54+
- Stored in `DataPath/lexica/db/` directory
55+
- Contains linguistic data optimized for fast searches
56+
57+
### API Structure
58+
59+
**Connect RPC Services:**
60+
61+
- **WordVaultService** (authenticated): Card management, spaced repetition scheduling, deck operations
62+
- **QuestionSearcher:** Alphagram and word searching functionality
63+
- **Anagrammer:** Anagram generation, blank tile challenges, build challenges
64+
- **WordSearcher:** Simple word lookups and definitions
65+
66+
### Key Internal Components
67+
68+
- **internal/wordvault:** FSRS spaced repetition logic using go-fsrs/v3 library
69+
- **internal/searchserver:** SQLite-based word and alphagram search engine
70+
- **internal/anagramserver:** GADDAG/KWG-based anagram generation using word-golib
71+
- **internal/auth:** JWT authentication and context management
72+
- **dbmaker:** Utility for creating and updating SQLite lexicon databases
73+
74+
### Deployment
75+
76+
- **Containerization:** Docker-based deployment
77+
- **CI/CD:** GitHub Actions pipeline for automated testing and deployment
78+
- **Database Management:** Migrations run automatically on startup
79+
80+
## Development Rules
81+
82+
- **Do not run migrations or start the dev server directly**
83+
- The development environment runs via docker-compose in a separate directory
84+
- Database and server are containerized and managed externally

0 commit comments

Comments
 (0)