# 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
```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`