spb/tools-spboucher-ai

1# tools.spboucher.ai — Tool Atlas23A 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.45**Live:** https://tools.spboucher.ai · **Admin:** https://tools.spboucher.ai/admin (owner only)67## Product8- 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.9- 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.10- Pipeline: content files → validator → import (idempotent, revisions) → publish gate → worker (link checks, source rescans, freshness flags, embeddings, encrypted backups).1112## Repository layout13```14content/            seed content: categories.json, tools/*.json (public), private/*.json, collections/*.json, owner/*.json15drizzle/            SQL migrations (source of truth), applied by scripts/migrate.ts16src/app             Next.js routes: (public), (auth)/login, admin, api17src/lib/public      read-only queries (tools_reader role)        src/lib/admin   editorial mutations18src/lib/content     zod schema + import                           src/lib/jobs    queue, handlers, backup19src/lib/auth        sessions, passwords, guards, limiter          src/lib/ai      provider adapter (optional)20src/worker          background worker                             scripts/        ops & audits21tests/unit, tests/integration (vitest) · tests/e2e (Playwright) · docs/ · infra/mld (manifest)22```2324## Local development25```bash26pnpm install27createdb tools_spboucher_dev && createdb tools_spboucher_test28cp .env.example .env            # fill DATABASE_URL_ADMIN=postgres://localhost:5432/tools_spboucher_dev, then:29DATABASE_URL_ADMIN=postgres://localhost:5432/tools_spboucher_dev pnpm db:roles   # prints role passwords → put in .env30pnpm db:migrate && pnpm content:validate && pnpm content:import --publish && pnpm bootstrap31pnpm dev                        # http://localhost:8540 ; worker: pnpm worker32```33Requires PostgreSQL 17 with `pg_trgm`, `unaccent`, `pgcrypto` (bundled) and optionally `vector` (pgvector).3435## Commands36| | |37|---|---|38| `pnpm content:validate` | schema + editorial rules over `content/` |39| `pnpm content:import [--publish] [--force] [slug…]` | deterministic upsert |40| `pnpm content:export` | `exports/tools-public.{json,csv}` |41| `pnpm links:check [--sample N]` | synchronous link audit |42| `pnpm worker` | background jobs |43| `pnpm backup` / `pnpm restore:drill` | encrypted dump / restore into a temp DB and compare |44| `pnpm test` · `pnpm test:e2e` · `pnpm test:a11y` · `pnpm test:security` · `pnpm eval:ranking` | quality gates |45| `scripts/ci.sh` | everything above in order (used before each release) |4647## Production48See `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).4950## Documentation51`docs/discovery.md` · `data-model.md` · `taxonomy.md` · `source-policy.md` · `ingestion.md` · `security.md` · `deployment.md` · `verification.md` · `editorial-guide.md` · `roadmap.md`52