Your personal boardgame collection manager with AI-powered recommendations, game explainers, and shelf insights.
Boardgame collectors know the feeling: a shelf full of games, but no easy way to track what you own, when you last played something, or what a game is actually worth today. Spreadsheets work until they do not. BGG is great for discovery but not built for personal collection management.
Board Vault is the tool that sits between your shelf and your brain. It keeps track of your collection, surfaces games that have been gathering dust, helps you explain games to new players in plain language, and gives you a clear picture of your collection over time.
- Collection Dashboard — All your games in one view with ratings, last played date, and current market value
- Automatic Game Data — Search by name and pull metadata directly from BoardGameGeek (description, complexity, player count, playing time)
- AI Game Explainer — Generate a plain-language explanation of any game tailored for new players, skipping rulebook jargon
- Shelf Insights — AI-powered nudges for games that have not hit the table in a while, based on your own history
- Smart Recommendations — Get suggestions on what to play next based on your collection, group size, and available time
- Semantic Search — Search your collection by vibe ("something cooperative", "a quick game for two") using embedding-based similarity
Board Vault uses a layered AI approach, introducing more complex patterns progressively:
For game explanations and shelf insights, the app serializes the game's BGG data (description, mechanics, complexity rating) and injects it into a structured system prompt. The model generates clean, audience-aware output without any knowledge of the game from training data — it only reasons over what is provided.
For "what should I play tonight" recommendations, the full collection is serialized as a structured list (name, complexity, player count, last played, personal rating) and provided as context. The model reasons over the collection to suggest the best fit for the current session parameters.
For natural language collection search, game descriptions are embedded using OpenAI's text-embedding-3-small model and stored alongside the game records. User queries are embedded at search time and compared via cosine similarity to return semantically relevant results, even when the exact words do not match.
User query ("cooperative game for 4 players")
│
▼
Embed query (text-embedding-3-small)
│
▼
Cosine similarity against stored game embeddings
│
▼
Top N results ranked and returned to UI
For detailed decisions, see /docs/AI_ARCHITECTURE.md.
| Layer | Technology |
|---|---|
| Framework | Next.js 14+ (App Router) |
| Language | TypeScript |
| Styling | TailwindCSS + Radix UI |
| AI Integration | Vercel AI SDK |
| LLM Provider | OpenAI (GPT-4o + text-embedding-3-small) |
| Database | Supabase (Postgres + pgvector) |
| External Data | BoardGameGeek XML API |
| Deployment | Vercel |
board-vault/
├── app/
│ ├── (routes)/
│ │ ├── collection/ # Dashboard and game list
│ │ ├── game/[id]/ # Individual game page
│ │ ├── add/ # Add new game flow
│ │ └── insights/ # AI shelf insights and recommendations
│ └── api/
│ ├── chat/ # Streaming recommendation endpoint
│ ├── explain/ # Game explainer generation
│ ├── search/ # Semantic search endpoint
│ └── embed/ # Embedding generation on game add
├── components/
│ ├── collection/ # Game cards, filters, grid layout
│ ├── game/ # Game detail, explainer panel
│ ├── insights/ # Nudge cards, recommendation UI
│ └── search/ # Semantic search input and results
├── lib/
│ ├── ai/
│ │ ├── prompts.ts # System prompt builders
│ │ ├── embeddings.ts # Embedding generation and similarity
│ │ └── context.ts # Collection context serialization
│ ├── bgg/
│ │ └── client.ts # BoardGameGeek API client
│ └── db/
│ └── client.ts # Supabase client and queries
├── docs/
│ ├── AI_ARCHITECTURE.md
│ └── DECISIONS.md
└── types/
└── index.ts
- Node.js 18+
- An OpenAI API key
- A Supabase project (free tier works)
git clone https://github.com/lucas-webdev/board-vault
cd board-vault
pnpm installcp .env.example .env.localOPENAI_API_KEY=your_key_here
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_keypnpm db:migrateThis runs the migration that creates the games table and enables the pgvector extension in Supabase for embedding storage.
pnpm devOpen http://localhost:3000.
- Project setup and base architecture
- BGG API integration and game search
- Collection CRUD with personal ratings and last played date
- AI game explainer with structured prompts
- Shelf insights ("games you have not played in 60+ days")
- Embedding generation on game add
- Semantic search across collection
- "What should we play tonight?" recommendation flow
- Market value tracking (manual input + history)
- Export collection as CSV
Key decisions and trade-offs are documented in /docs/DECISIONS.md. Some highlights:
Why Supabase with pgvector instead of a dedicated vector DB? For a personal collection that realistically tops out at a few hundred games, running a separate vector database like Pinecone or Chroma adds operational overhead without real benefit. Supabase with pgvector keeps everything in one place and the similarity search at this scale is fast enough without indexes.
Why BGG XML API? It is the most complete source of boardgame metadata available. The XML format is not ideal, but the data quality is worth it. A thin client wrapper normalizes the response into a clean TypeScript type before anything else in the app touches it.
Why Radix UI with TailwindCSS? Accessibility primitives out of the box with full styling control. No fighting against a component library's opinions. This combination matches the production stack from my professional work, so it was a natural choice.
Why text-embedding-3-small over ada-002? Better performance per token at a lower cost. For a collection of a few hundred games, the cost difference is negligible, but the quality improvement in semantic search results is noticeable.
This is a personal learning project with open source documentation. Feedback, issues, and suggestions are welcome. If you want to contribute, open an issue first to discuss the change.
MIT License. See LICENSE for details.
Built by Lucas Medeiros — Senior Frontend Engineer exploring AI integration patterns in real-world applications.