explorer/README.md

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.