D. Rimron-Soutter
ddbf72ea52
Expand and update documentation to reflect the current app (Registers + ZXDB Explorer), with clear setup and usage instructions. Changes - README: add project overview including ZXDB Explorer; routes tour; ZXDB setup (DB import, helper search tables, readonly role); environment configuration; selected API endpoints; implementation notes (Next 15 async params, Node runtime for mysql2, SSR/ISR usage); links to AGENTS.md and docs/ZXDB.md. - docs/ZXDB.md (new): deep-dive guide covering database preparation, helper tables, environment, Explorer UI, API reference under /api/zxdb, performance approach (helper tables, parallel queries, ISR), troubleshooting, and roadmap. - AGENTS.md: refresh Project Overview/Structure with ZXDB routes and server/client boundaries; document Next.js 15 dynamic params async pattern for pages and API routes; note Drizzle+mysql2, Node runtime, and lookup `text`→`name` mapping; keep commit workflow guidance. - example.env: add reference to docs/ZXDB.md and clarify mysql:// format and setup pointers. Notes - Documentation focuses on the current state of the codebase (what the code does), not a log of agent actions. - Helper SQL at ZXDB/scripts/ZXDB_help_search.sql is required for performant searches. Signed-off-by: Junie@lucy.xalior.com
78 lines
3.6 KiB
Markdown
78 lines
3.6 KiB
Markdown
Spectrum Next Explorer
|
||
|
||
A Next.js application for exploring the Spectrum Next ecosystem. It ships with:
|
||
|
||
- Register Explorer: parsed from `data/nextreg.txt`, with real‑time search and deep links
|
||
- ZXDB Explorer: a deep, cross‑linked browser for entries, labels, genres, languages, and machine types backed by a MySQL ZXDB instance
|
||
- Bootstrap 5 theme with light/dark support
|
||
|
||
Quick start
|
||
- Prerequisites: Node.js 20+, pnpm (recommended), access to a MySQL server for ZXDB (optional for Registers)
|
||
- Install dependencies:
|
||
- `pnpm install`
|
||
- Run in development (Turbopack, port 4000):
|
||
- `pnpm dev` then open http://localhost:4000
|
||
- Build and start (production):
|
||
- `pnpm build`
|
||
- `pnpm start` (defaults to http://localhost:3000)
|
||
- Lint:
|
||
- `pnpm lint`
|
||
|
||
Project scripts (package.json)
|
||
- `dev`: `PORT=4000 next dev --turbopack`
|
||
- `build`: `next build --turbopack`
|
||
- `start`: `next start`
|
||
- `deploy-test`: push to `test.explorer.specnext.dev`
|
||
- `deploy-prod`: push to `explorer.specnext.dev`
|
||
|
||
Routes
|
||
- `/` — Home
|
||
- `/registers` — Register Explorer
|
||
- `/zxdb` — ZXDB Explorer (search + filters)
|
||
- `/zxdb/entries/[id]` — Entry detail
|
||
- `/zxdb/labels` and `/zxdb/labels/[id]` — Labels search and detail
|
||
- `/zxdb/genres` and `/zxdb/genres/[id]` — Genres list and entries
|
||
- `/zxdb/languages` and `/zxdb/languages/[id]` — Languages list and entries
|
||
- `/zxdb/machinetypes` and `/zxdb/machinetypes/[id]` — Machine types list and entries
|
||
|
||
ZXDB setup (database, env, and helper tables)
|
||
The Registers section works without any database. The ZXDB Explorer requires a MySQL ZXDB database and one environment variable.
|
||
|
||
1) Prepare the database (outside this app)
|
||
- Import ZXDB data into MySQL. If you want only structure, use `ZXDB/ZXDB_mysql_STRUCTURE_ONLY.sql` in this repo. For data, import ZXDB via your normal process.
|
||
- Create the helper search tables (required for fast search):
|
||
- Run `ZXDB/scripts/ZXDB_help_search.sql` against your ZXDB database.
|
||
- Create a read‑only role/user (recommended):
|
||
- Example (see `bin/import_mysql.sh`):
|
||
- Create role `zxdb_readonly`
|
||
- Grant `SELECT, SHOW VIEW` on database `zxdb`
|
||
|
||
2) Configure environment
|
||
- Copy `.env` from `example.env`.
|
||
- Set `ZXDB_URL` to a MySQL URL, e.g. `mysql://zxdb_readonly:password@hostname:3306/zxdb`.
|
||
- On startup, `src/env.ts` validates env vars (t3.gg pattern with Zod) and will fail fast if invalid.
|
||
|
||
3) Run the app
|
||
- `pnpm dev` → open http://localhost:4000 and navigate to `/zxdb`.
|
||
|
||
API (selected endpoints)
|
||
- `GET /api/zxdb/search?q=...&page=1&pageSize=20&genreId=...&languageId=...&machinetypeId=...&sort=title&facets=1`
|
||
- `GET /api/zxdb/entries/[id]`
|
||
- `GET /api/zxdb/labels/search?q=...`
|
||
- `GET /api/zxdb/labels/[id]?page=1&pageSize=20`
|
||
- `GET /api/zxdb/genres` and `/api/zxdb/genres/[id]?page=1`
|
||
- `GET /api/zxdb/languages` and `/api/zxdb/languages/[id]?page=1`
|
||
- `GET /api/zxdb/machinetypes` and `/api/zxdb/machinetypes/[id]?page=1`
|
||
|
||
Implementation notes
|
||
- Next.js 15 dynamic params: pages and API routes that consume `params` must await it, e.g. `export default async function Page({ params }: { params: Promise<{ id: string }> }) { const { id } = await params; }`
|
||
- ZXDB integration uses Drizzle ORM over `mysql2` with a singleton pool at `src/server/db.ts`; API routes declare `export const runtime = "nodejs"`.
|
||
- Entry and detail pages server‑render initial content and use ISR (`revalidate = 3600`) for fast time‑to‑content; index pages avoid a blocking first client fetch.
|
||
|
||
Further reading
|
||
- ZXDB details and API usage: `docs/ZXDB.md`
|
||
- Agent/developer workflow and commit guidelines: `AGENTS.md`
|
||
|
||
License
|
||
- See `LICENSE.txt` for details.
|