Skip to content

Commit e7eefe9

Browse files
josedabjosedab
committed
docs(website): add why, troubleshooting, contributing, changelog
1 parent bce4978 commit e7eefe9

4 files changed

Lines changed: 421 additions & 0 deletions

File tree

‎website/docs/changelog.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: Changelog
3+
description: Release notes for GamePulse.
4+
---
5+
6+
# Changelog
7+
8+
All notable changes to GamePulse will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
9+
10+
## [Unreleased]
11+
12+
### Planned
13+
14+
- Real authentication via NextAuth.js — replaces the mock `getCurrentUser()` stub.
15+
- Optional BoardGameGeek importer as an alternative seed pipeline.
16+
- Public read-only API for game and critic data.
17+
18+
## [0.1.0] — 2024
19+
20+
The initial open-source release.
21+
22+
### Added
23+
24+
- **Landing page** with hero, trending games, latest critic reviews, rising games, and an awards tracker.
25+
- **Game detail pages** with dual GamePulse scores (critics + community), consensus badges, full critic breakdown, community reviews, price comparison, and a "Similar games" rail.
26+
- **Browse & discover** with filters for category, player count, and complexity. Sort by score, trending, newest, or most reviewed. Header search with keyboard navigation.
27+
- **Critic profiles** with taste-profile radar charts, review history, taste-match percentage, and follow/unfollow.
28+
- **User dashboard** at `/me` — your ratings, watchlist, wishlist, matched critics, taste-profile visualization, and personalized score predictions.
29+
- **Personalized content feed** with filters for reviews, news, deals, and videos. Release calendar and weekly newsletter preview.
30+
- **Taste matching** that combines cosine similarity and Pearson correlation across six taste dimensions.
31+
- **Local persistence** — all interactions (ratings, reviews, watchlist, follows, newsletter signups) persist in SQLite via `better-sqlite3`.
32+
- **Deterministic seeds** — 60+ board games, 14 named critics, 50+ community users, 200+ critic reviews, 100+ community reviews, awards, release-calendar entries, follow relationships, and saved-list activity.
33+
- **Server Actions** for every mutation, with rate limiting per action.
34+
- **Production guard** — automatic reseeds are blocked in production unless `GAMEPULSE_ENABLE_PRODUCTION_RESEED=1`.
35+
- **Dockerfile** + volume-mountable database for one-command deploys.
36+
- **CI pipeline** running `type-check → lint → build` on every PR.
37+
38+
### Technical foundation
39+
40+
- Next.js 16 (App Router) + React 19
41+
- TypeScript 5 (strict mode)
42+
- Tailwind CSS 4
43+
- Recharts for taste-profile radar charts
44+
- Lucide React for icons
45+
- `better-sqlite3` for synchronous server-component-friendly persistence
46+
47+
---
48+
49+
_This changelog will grow as releases ship. For the unreleased work-in-progress, see [docs/IMPROVEMENTS.md](https://github.com/TabletopFoundry/gamepulse/blob/main/docs/IMPROVEMENTS.md) in the repo._

‎website/docs/contributing.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Contributing
3+
description: How to contribute to GamePulse — setup, conventions, PR process.
4+
---
5+
6+
# Contributing
7+
8+
Thanks for your interest in contributing to GamePulse! This guide gets you from zero to your first PR in **about 15 minutes**.
9+
10+
## Code of Conduct
11+
12+
GamePulse follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be welcoming, be patient, assume good intent. Harassment of any kind is not tolerated.
13+
14+
## Setup
15+
16+
```bash
17+
# 1. Fork on GitHub, then clone your fork
18+
git clone https://github.com/<your-username>/gamepulse.git
19+
cd gamepulse
20+
21+
# 2. Install
22+
nvm use # if you have nvm
23+
npm install
24+
25+
# 3. Run
26+
npm run dev
27+
```
28+
29+
You're ready. See [Quick Start](./getting-started/quick-start.md) if anything blows up.
30+
31+
## Before you start coding
32+
33+
1. **Search [open issues](https://github.com/TabletopFoundry/gamepulse/issues)** — your idea may already be tracked.
34+
2. For non-trivial changes, **open an issue or discussion first** describing the proposal. This avoids wasted work.
35+
3. **Branch from `main`**: `git checkout -b feat/your-feature`.
36+
37+
## Coding conventions
38+
39+
These are enforced by ESLint + TypeScript, but worth reading once:
40+
41+
### TypeScript
42+
43+
- **Strict mode is on.** No `any`, no unchecked indexed access.
44+
- **Explicit return types** on exported functions.
45+
- **`type` over `interface`** for object shapes (project convention).
46+
- **Path aliases**: `@/lib/...`, `@/components/...` — never relative paths across layers.
47+
48+
### Styling
49+
50+
- **Tailwind only.** No additional CSS files except `app/globals.css`.
51+
- **Stick to the design system**: `rounded-[2rem]` cards, `rose-500` accents, `slate-950` text.
52+
- **Use shared UI** from `components/gamepulse-ui.tsx` (`PageShell`, `SectionHeading`, `ScoreCard`, `ConsensusBadge`, `GameCard`).
53+
54+
### Components
55+
56+
- **Server components by default.** Add `"use client"` only when you need hooks, event handlers, or browser APIs.
57+
- **Forms use server actions** via `useActionState` + the shared `SubmitButton`.
58+
- **Toast notifications** via `useToast()` from `@/components/toast`.
59+
60+
### Data access
61+
62+
- **Pages never call `getDb()` directly.** All reads go through `lib/queries/`, all writes through `lib/actions.ts`.
63+
- **Seed data** lives in `lib/db/seeds/`. Bump `SEED_VERSION` in `lib/db/seed.ts` when you change it.
64+
- **Parameter binding always** — never string-interpolate SQL.
65+
66+
### Naming
67+
68+
| Kind | Style | Example |
69+
| --- | --- | --- |
70+
| Files | kebab-case | `game-card.tsx` |
71+
| Components | PascalCase | `GameCard` |
72+
| Functions | camelCase | `getGameBySlug` |
73+
| Types | PascalCase | `GameCardData` |
74+
| DB columns | snake_case | `community_score` |
75+
76+
## The PR process
77+
78+
### 1. Make the change
79+
80+
Keep PRs **focused**. One concern per PR. If your change touches three unrelated areas, split it.
81+
82+
### 2. Run the CI gate
83+
84+
```bash
85+
npm run check
86+
```
87+
88+
This runs `type-check → lint → build`. All three must pass before you push.
89+
90+
### 3. Write a clear PR description
91+
92+
Use the PR template. Cover:
93+
94+
- **What** changed (one or two sentences)
95+
- **Why** it changed (link to issue or explain the motivation)
96+
- **How** to test it (the steps a reviewer should take)
97+
- Screenshots for any visual change
98+
99+
### 4. Conventional commit prefixes
100+
101+
| Prefix | Use for |
102+
| --- | --- |
103+
| `feat:` | New user-facing feature |
104+
| `fix:` | Bug fix |
105+
| `docs:` | Documentation only |
106+
| `refactor:` | Internal change, no behavior difference |
107+
| `perf:` | Performance improvement |
108+
| `chore:` | Tooling, deps, build config |
109+
110+
### 5. Self-review
111+
112+
Read your own diff before you request review. Catch:
113+
114+
- Dead code, console.logs, commented-out blocks
115+
- Unused imports
116+
- Inconsistent naming
117+
- Missing types on exported functions
118+
119+
## What we're looking for
120+
121+
| Welcome | Less welcome |
122+
| --- | --- |
123+
| Bug fixes with reproduction steps | Drive-by formatting changes |
124+
| New games / critics with realistic data | Sweeping refactors without discussion |
125+
| Documentation improvements | Adding heavy dependencies (`zod`, `prisma`, …) for marginal gains |
126+
| Accessibility fixes | Style nitpicks not tied to a real readability issue |
127+
| Test improvements for `lib/` algorithms | Tests for trivial components |
128+
129+
## Areas that need help
130+
131+
- **Real authentication** integration (NextAuth.js or Clerk) — see [Data Model → Mock authentication](./concepts/data-model.md#mock-authentication).
132+
- **BoardGameGeek importer** as an optional seed pipeline.
133+
- **Price-tracker webhooks** for `game_prices` updates.
134+
- **Accessibility audit** of forms and modals.
135+
- **More critic personalities** in seed data — bring your community's voice.
136+
137+
## Need help?
138+
139+
- Read [docs/](https://github.com/TabletopFoundry/gamepulse/tree/main/docs) in the repo (PRD, code review, UX review).
140+
- Open a [Discussion](https://github.com/TabletopFoundry/gamepulse/discussions) for questions.
141+
- Open an [Issue](https://github.com/TabletopFoundry/gamepulse/issues) for bugs.
142+
143+
Thank you for helping make GamePulse better. 🎲

‎website/docs/troubleshooting.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: Troubleshooting & FAQ
3+
description: Fixes for the most common GamePulse errors and answers to recurring questions.
4+
---
5+
6+
# Troubleshooting & FAQ
7+
8+
## Install & build errors
9+
10+
### `better-sqlite3` fails to build
11+
12+
You'll see an error like:
13+
14+
```
15+
gyp ERR! find Python …
16+
or
17+
node-gyp rebuild failed
18+
```
19+
20+
`better-sqlite3` compiles a native binding during `npm install`. You need a C++ toolchain.
21+
22+
- **macOS**: `xcode-select --install`
23+
- **Ubuntu/Debian**: `sudo apt install build-essential python3`
24+
- **Windows**: install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) with the "Desktop development with C++" workload.
25+
26+
Then re-run `npm install`.
27+
28+
### Node version error
29+
30+
If the install fails on `engines` or you see syntax errors during build, check your Node version:
31+
32+
```bash
33+
node --version # must be ≥ 20.x
34+
```
35+
36+
The repo includes a `.nvmrc`. With `nvm`:
37+
38+
```bash
39+
nvm use
40+
```
41+
42+
### `npm run dev` hangs at "seeding database"
43+
44+
This usually means an earlier seed crashed mid-transaction and left a lock. Fix with:
45+
46+
```bash
47+
npm run clean
48+
npm run dev
49+
```
50+
51+
`clean` removes `data/gamepulse.db*` so the next dev start rebuilds from scratch.
52+
53+
## Runtime issues
54+
55+
### Database is locked (`SQLITE_BUSY`)
56+
57+
SQLite is single-writer. You'll see this if two processes try to write at once — typically `npm run dev` running alongside `npm run start`. Stop one of them.
58+
59+
If you're running in production behind a process supervisor (PM2, systemd, Docker), make sure only one instance writes to `data/gamepulse.db`.
60+
61+
### "Cannot find module" after pulling new changes
62+
63+
Something in `node_modules` is stale.
64+
65+
```bash
66+
rm -rf node_modules .next
67+
npm install
68+
npm run dev
69+
```
70+
71+
### My new seed data isn't showing up
72+
73+
You probably forgot to bump `SEED_VERSION`:
74+
75+
```ts
76+
// lib/db/seed.ts
77+
const SEED_VERSION = 5; // ← bump this
78+
```
79+
80+
Then:
81+
82+
```bash
83+
npm run clean && npm run dev
84+
```
85+
86+
See [Seeding Data](./guides/seeding-data.md) for the full pipeline.
87+
88+
### A page returns 404 after I added it
89+
90+
The Next.js App Router file conventions changed in v16. Make sure your new route is:
91+
92+
```
93+
app/<your-route>/page.tsx
94+
```
95+
96+
Not `index.tsx`. Not `route.tsx` (that's for API routes). The file must be named `page.tsx`.
97+
98+
### Type errors after editing the schema
99+
100+
If you added a column to `lib/db/schema.ts` but didn't update parsers, TypeScript will surface the gap. Update:
101+
102+
1. `lib/queries/types.ts` — add the field to the relevant type.
103+
2. `lib/queries/parsers.ts` — read the new field from `RawGame` / `RawCritic`.
104+
105+
Then `npm run type-check` should pass.
106+
107+
## Performance
108+
109+
### Pages feel slow in dev
110+
111+
Dev mode runs everything in development — no minification, no static optimization, source maps, HMR. Run `npm run build && npm run start` to get a realistic feel. Production pages render in single-digit milliseconds.
112+
113+
### `npm run check` takes forever
114+
115+
`npm run check` runs `type-check → lint → build`. The build is the slow part — typically 20–40 seconds. To iterate faster:
116+
117+
```bash
118+
npm run type-check # ~3 seconds
119+
npm run lint # ~5 seconds
120+
```
121+
122+
Then `npm run build` only when you're ready to verify the whole thing.
123+
124+
## FAQ
125+
126+
### Where's the real authentication?
127+
128+
It's intentionally not built in. `getCurrentUser()` returns the seeded mock user `alex`. Adding NextAuth.js (or Clerk, or Lucia) is a roadmap item — see [Data Model → Mock authentication](./concepts/data-model.md#mock-authentication) for the minimum diff.
129+
130+
### Can I use Postgres instead of SQLite?
131+
132+
Yes. The schema is portable. Swap `better-sqlite3` for `pg` in `lib/db/connection.ts` and update the parameterized SQL placeholders (`?` → `$1`, `$2`, …). The query and route layers don't need to change.
133+
134+
### Can I deploy to Vercel?
135+
136+
No — Vercel's serverless runtime can't host a persistent SQLite file across invocations. Use Fly.io, Railway, Render, a VPS, or Docker on any host with a persistent volume. See [Deploying](./guides/deploying.md).
137+
138+
### Where do the critic scores come from?
139+
140+
They're hand-authored in `lib/db/seeds/critic-reviews.ts`. GamePulse doesn't scrape any third-party site. The 14 critics are illustrative — replace them with whatever set makes sense for your audience.
141+
142+
### Why not BoardGameGeek's API?
143+
144+
Two reasons: BGG's API has aggressive rate limits and inconsistent response shapes, and seeding from a third party makes the project less self-contained. The MVP optimizes for "clone and run" over "synced with the real world." Adding a BGG importer is a reasonable extension — it just doesn't ship by default.
145+
146+
### Is there a roadmap?
147+
148+
Yes, in [`docs/IMPROVEMENTS.md`](https://github.com/TabletopFoundry/gamepulse/blob/main/docs/IMPROVEMENTS.md) in the repo. The headline items: real auth, BGG sync (optional), price-tracker webhooks, and a public read-only API.
149+
150+
### How do I report a bug?
151+
152+
[Open an issue](https://github.com/TabletopFoundry/gamepulse/issues/new) with reproduction steps. Issue templates are provided. For security issues, please email the maintainers privately rather than opening a public issue.

0 commit comments

Comments
 (0)