diff --git a/AGENTS.md b/AGENTS.md index eaeffce..f326701 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ Next Explorer is a web application for exploring the Spectrum Next ecosystem. It It has two main areas: - Registers: parsed from `data/nextreg.txt`, browsable with real-time filtering and deep links. -- ZXDB Explorer: a deep, cross‑linked browser for ZXDB entries, labels, genres, languages, and machine types backed by MySQL using Drizzle ORM. +- ZXDB Explorer: a deep, cross‑linked browser for ZXDB entries, releases, labels, magazines, genres, languages, and machine types backed by MySQL using Drizzle ORM. ## Project Structure @@ -69,8 +69,10 @@ next-explorer/ - `src/app/zxdb/`: ZXDB Explorer routes and client components. - `page.tsx` + `ZxdbExplorer.tsx`: Search + filters with server-rendered initial content and ISR. - `entries/[id]/page.tsx` + `EntryDetail.tsx`: Entry details (SSR initial data). + - `releases/page.tsx` + `ReleasesExplorer.tsx`: Releases search + filters. - `labels/page.tsx`, `labels/[id]/page.tsx` + client: Labels search and detail. - `genres/`, `languages/`, `machinetypes/`: Category hubs and detail pages. + - `magazines/`, `issues/`: Magazine and issue browsing. - `src/app/api/zxdb/`: Zod‑validated API routes (Node runtime) for search and category browsing. - `src/server/`: - `env.ts`: Zod env parsing/validation (t3.gg style). Validates `ZXDB_URL` (mysql://). @@ -133,7 +135,7 @@ Comment what the code does, not what the agent has done. The documentation's pur - Database connection via `mysql2` pool wrapped by Drizzle (`src/server/db.ts`). - Env validation via Zod (`src/env.ts`) ensures `ZXDB_URL` is a valid `mysql://` URL. - Minimal Drizzle schema models used for fast search and lookups (`src/server/schema/zxdb.ts`). -- Repository consolidates SQL with typed results (`src/server/repo/zxdb.ts`). +- Repository consolidates SQL with typed results (`src/server/repo/zxdb.ts`). Gracefully handles missing tables (e.g. `releases`) by checking `information_schema.tables`. - API routes under `/api/zxdb/*` validate inputs with Zod and run on Node runtime. - UI under `/zxdb` is deeply cross‑linked and server‑renders initial data for performance. Links use Next `Link` to enable prefetching. - Helper SQL `ZXDB/scripts/ZXDB_help_search.sql` must be run to create `search_by_*` tables for efficient searches. diff --git a/README.md b/README.md index 30ac99a..e72f90f 100644 --- a/README.md +++ b/README.md @@ -28,12 +28,16 @@ Project scripts (package.json) Routes - `/` — Home - `/registers` — Register Explorer -- `/zxdb` — ZXDB Explorer (search + filters) +- `/zxdb` — ZXDB Explorer (hub) +- `/zxdb/entries` — Entries search + filters - `/zxdb/entries/[id]` — Entry detail +- `/zxdb/releases` — Releases search + filters - `/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/magazines` and `/zxdb/magazines/[id]` — Magazines list and issues +- `/zxdb/issues/[id]` — Issue detail (contents and references) 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. @@ -58,16 +62,19 @@ The Registers section works without any database. The ZXDB Explorer requires a M 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/releases/search?q=...&year=...&languageId=...&machinetypeId=...&sort=...` - `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` +- `GET /api/zxdb/{availabletypes,casetypes,currencies,filetypes,roletypes,schemetypes,sourcetypes}` 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. +- Database Schema: Repository queries include graceful fallback checks (via `information_schema.tables`) to remain functional even if optional tables (like `releases` or `downloads`) are missing from the connected MySQL instance. Further reading - ZXDB details and API usage: `docs/ZXDB.md`