NextBestNetwork/explorer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add ZXDB guide; refresh README & AGENTS

Browse Source 
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
This commit is contained in:
D. Rimron-Soutter
2025-12-12 16:17:35 +00:00
parent 3ef3a16bc0
commit ddbf72ea52
10 changed files with 409 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
COMMIT_EDITMSG
View File

@@ -1,28 +1,15 @@
perf(zxdb): server-render index pages with ISR and initial data
docs: add ZXDB guide; refresh README & AGENTS
Why
- Reduce time-to-first-content on ZXDB index pages by eliminating the initial client-side fetch and enabling incremental static regeneration.
Expand and update documentation to reflect the current app (Registers + ZXDB Explorer), with clear setup and usage instructions.
What
- Main Explorer (/zxdb):
- Server-renders first page of results and lookup lists (genres, languages, machinetypes) and passes them as initial props.
- Keeps client interactivity for subsequent searches/filters.
- Labels index (/zxdb/labels):
- Server-renders first page of empty search and passes as initial props to skip the first fetch.
- Category lists:
- Genres (/zxdb/genres), Languages (/zxdb/languages), Machine Types (/zxdb/machinetypes) now server-render their lists and export revalidate=3600.
- Refactored list components to accept server-provided items; removed on-mount fetching.
- Links & prefetch:
- Replaced remaining anchors with Next Link to enable prefetch where applicable.
Tech details
- Added revalidate=3600 to the index pages for ISR.
- Updated ZxdbExplorer to accept initial results and initial filter lists; skips first client fetch when initial props are present.
- Updated LabelsSearch to accept initial payload and skip first fetch in default state.
- Updated GenreList, LanguageList, MachineTypeList to be presentational components receiving items from server pages.
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
- Low-churn list APIs already emit Cache-Control for CDN; list pages now render instantly from server.
- Further polish (breadcrumbs, facet counts UI) can build on this foundation without reintroducing initial network waits.
- 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
Signed-off-by: Junie@lucy.xalior.com