Repository structure

• Directorysrc/ the backend: core, adapters, entrypoints

  • Directorydomain/ pure — Zod models and decision rules

    • models.ts watches, sources, candidates, verdicts, run state, keys, users
    • decisions.ts hashing, delta, grounding, trust, tiering, cron
    • feedback.ts precision/recall and collection summaries
    • keyCatalog.ts the curated category → provider → model registry
    • auth.ts users, roles, claims, pure predicates
  • Directoryapplication/ orchestration and the port interfaces

    • ports.ts every interface the core depends on
    • runWatch.ts the loop
    • executeWatch.ts loop + run record + last-run, under the lock
    • runDueWatches.ts load, filter due, worker pool
    • watchLock.ts per-watch mutual exclusion
    • importWatches.ts YAML → repository upsert
  • Directoryadapters/ all input and output

    • Directorycollectors/ rss, webFetch, tavily, jina, fake

      • …
    • Directoryevaluator/ llm, cascade, groq, keyRotating, keyword, fake

      • …
    • Directoryembedder/ llm, keyRotating, fake

      • …
    • Directorydrafter/ llm, keyRotating, domainChecker

      • …
    • Directorynotifiers/ telegram, fcm, console, memory

      • …
    • Directorymailer/ nodemailer, console

      • …
    • Directoryrepositories/ mongo, memory, yamlFiles

      • …
    • Directoryauth/ authService, tokens, passwords, googleVerifier

      • …
    • DirectorykeyValidation/ per-provider add-time probes

      • …
    • keyPool.ts keyAdmin.ts secretCrypto.ts usageRecorder.ts http.ts
  • Directoryentrypoints/

    • cli.ts run-due and management commands
    • api.ts Fastify app, scheduler, server bootstrap
    • wiring.ts the one place the real adapter graph is built
  • config.ts the only place secrets enter
  • index.ts the public export surface
• Directoryweb/ admin panel (Vite + React)

  • …
• Directorywatcher-mobile/ Android app (its own project, not in the workspace)

  • …
• Directorydocs-site/ this documentation site

  • …
• Directorywatches/ example watch files, an import source only

  • …
• Directorytests/ Vitest suites, plus fixtures and one integration test

  • …
• Directoryeval/ the golden-set accuracy harness

  • …
• Directorydocs/ internal engineering documents

  • …

Which parts you will touch

Task	Where
Change a decision rule	src/domain/decisions.ts (+ its unit tests)
Add a field to a watch	src/domain/models.ts, then wherever it is consumed
Add a source type	src/adapters/collectors/, register in wiring.ts
Add a delivery channel	src/adapters/notifiers/, register in wiring.ts
Add an HTTP route	src/entrypoints/api.ts
Add a CLI command	src/entrypoints/cli.ts
Change what is persisted	src/adapters/repositories/mongo.ts and memory.ts

Repository changes come in pairs

There are two repository implementations: MongoDB for production and an in-memory one for tests. A field added to the state model must be handled in both, or the tests pass while production silently drops the data. That exact mistake has happened here before — see Watcher internals.

Workspace layout

The backend, the admin panel and this documentation site are packages in one pnpm workspace. The Android app is a separate project with its own toolchain.

The panel imports the backend’s domain schemas directly, so the UI validates against exactly the same types the server does.

Commands by area

Area	Gate
Backend	pnpm verify
Admin panel	pnpm web:verify
Documentation	pnpm docs:verify
Mobile app	Its own verify script

What is not in the repository

Secrets, credentials, database dumps and service-account files. .env and the secrets directory are ignored by git — verify that before your first commit.