# 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

text

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

bash

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 worker

Requires 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

spb/tools-spboucher-ai