tools.spboucher.ai — Tool Atlas
A curated, source-cited encyclopedia of software, AI systems, APIs, data platforms, developer tools and academic tools, with a private owner inventory. Next.js 16 · React 19 · Tailwind 4 · PostgreSQL 17 (full-text + trigram + optional pgvector) · Drizzle · TypeScript. Hosted on MacLustr (node M2M32c) behind the MacLustr Tunnel.
Live: https://tools.spboucher.ai · Admin: https://tools.spboucher.ai/admin (owner only)
Product
- Public: homepage, directory with hybrid search (lexical + typo tolerance, optional semantic), faceted filters with shareable URLs, tool pages with evidence/sources/link verification, categories (8 → 66), collections, side-by-side compare (2–5), error reports, SEO (SSR, sitemap, JSON-LD), WCAG 2.2 AA target, dark/light.
- Owner/admin: passkeys + TOTP, record editor (form or raw JSON), review queue (reviewed records, automated flags, reports), duplicate merge, bulk CSV/JSON import, role-scoped export, link-integrity dashboard, job queue & crawler schedule, owner dashboard (active/testing/candidate/archived/rejected, projects, private notes & deployment links), audit log, sessions.
- Pipeline: content files → validator → import (idempotent, revisions) → publish gate → worker (link checks, source rescans, freshness flags, embeddings, encrypted backups).
Repository layout
content/ seed content: categories.json, tools/*.json (public), private/*.json, collections/*.json, owner/*.json
drizzle/ SQL migrations (source of truth), applied by scripts/migrate.ts
src/app Next.js routes: (public), (auth)/login, admin, api
src/lib/public read-only queries (tools_reader role) src/lib/admin editorial mutations
src/lib/content zod schema + import src/lib/jobs queue, handlers, backup
src/lib/auth sessions, passwords, guards, limiter src/lib/ai provider adapter (optional)
src/worker background worker scripts/ ops & audits
tests/unit, tests/integration (vitest) · tests/e2e (Playwright) · docs/ · infra/mld (manifest)Local development
pnpm install
createdb tools_spboucher_dev && createdb tools_spboucher_test
cp .env.example .env # fill DATABASE_URL_ADMIN=postgres://localhost:5432/tools_spboucher_dev, then:
DATABASE_URL_ADMIN=postgres://localhost:5432/tools_spboucher_dev pnpm db:roles # prints role passwords → put in .env
pnpm db:migrate && pnpm content:validate && pnpm content:import --publish && pnpm bootstrap
pnpm dev # http://localhost:8540 ; worker: pnpm workerRequires PostgreSQL 17 with pg_trgm, unaccent, pgcrypto (bundled) and optionally vector (pgvector).
Commands
pnpm content:validate |
schema + editorial rules over content/ |
pnpm content:import [--publish] [--force] [slug…] |
deterministic upsert |
pnpm content:export |
exports/tools-public.{json,csv} |
pnpm links:check [--sample N] |
synchronous link audit |
pnpm worker |
background jobs |
pnpm backup / pnpm restore:drill |
encrypted dump / restore into a temp DB and compare |
pnpm test · pnpm test:e2e · pnpm test:a11y · pnpm test:security · pnpm eval:ranking |
quality gates |
scripts/ci.sh |
everything above in order (used before each release) |
Production
See docs/deployment.md (mld manifest, node prep, release, rollback, backups) and docs/security.md. Remote-first: after the first deploy the node directory M2M32c:~/apps/tools-spboucher-ai is the canonical git clone (origin spbgit).
Documentation
docs/discovery.md · data-model.md · taxonomy.md · source-policy.md · ingestion.md · security.md · deployment.md · verification.md · editorial-guide.md · roadmap.md