# Trouve-KA — Cherche le Québec.

**Moteur de recherche web indépendant, Québec-first.** Son propre crawler, son propre
index, son propre ranking, son API et son application web publique. Pas un métamoteur :
aucune dépendance à Google, Bing ou Brave pour les résultats.

> **Crawl en continu. Indexe immédiatement. Recherche immédiatement. Améliore en asynchrone.**

En production : **https://www.trouve-ka.com** (node m2m32 du cluster MacLustr, tunnel ngrok).

Author: Simon-Pierre Boucher — Contact: contact@spboucher.ai

---

## Ce que c'est

```
Crawler → Frontier → Fetcher → Parser → Classification Québec
→ Déduplication → Indexer → Index → Ranking → API → Web App
```

Le crawler découvre le web québécois à partir de seeds à forte autorité (gouvernement,
municipalités, universités, médias), suit les liens sortants, juge la pertinence
québécoise de chaque page (`page_quebec_score` **et** `domain_quebec_score`),
et indexe **immédiatement** : une page fetchée est cherchable en ~2-4 secondes,
pendant que le frontier continue de grandir. L'enrichissement (autorité, entités,
embeddings) arrive après, en asynchrone, sans jamais bloquer.

Détails : [docs/architecture.md](docs/architecture.md) (diagrammes Mermaid) et
[docs/decisions.md](docs/decisions.md) (pourquoi OpenSearch, pourquoi Postgres
comme frontier, etc.).

## Stack

| Couche | Choix |
|---|---|
| Web | Next.js 15, TypeScript, React 19, Tailwind (composants style shadcn/ui) |
| API | FastAPI (Python 3.12) |
| Pipeline | Python 3.12 async — httpx, selectolax, Protego |
| BD relationnelle | PostgreSQL 16 (frontier, domaines, documents, graphe de liens, analytics) |
| Coordination | Redis 7 (politesse par hôte, pause, Redis Streams pour l'enrichissement) |
| Recherche | OpenSearch 2.17 (BM25 FR/EN, synonymes bilingues, function_score Québec-first) |
| Déploiement | Docker Compose sur m2m32 + ngrok (www.trouve-ka.com) |

## Layout du monorepo

```
apps/web         # moteur public + dashboard /admin (Next.js)
apps/api         # FastAPI (trouveka.api)
services/        # crawler, frontier, parser, classifier, indexer, ranking, scheduler, enrichment
packages/        # config, database, logging, queue, search-core, shared, types
infrastructure/  # docker/, migrations/, monitoring/, deployment/ (m2m32 + ngrok)
scripts/         # bootstrap-seeds/, start-crawler/, health-check/, eval/, check-headers.py
tests/           # unitaires : canonicalisation, SSRF, robots, scoring Québec, fetcher, ranking
```

Le backend Python est un seul package namespace `trouveka.*` mappé sur ce layout
(voir `pyproject.toml`).

## Démarrage rapide (dev)

```bash
git clone … && cd trouve-ka
cp .env.example .env
docker compose up -d postgres redis opensearch   # infra
uv venv --python 3.12 .venv && uv pip install -e ".[dev]" --python .venv/bin/python
pnpm install

pnpm crawl:seed                                  # migrations + 60+ seeds québécoises
bash scripts/start-crawler/start.sh &            # le crawl démarre
.venv/bin/uvicorn trouveka.api.main:app --port 8080 &
pnpm dev                                         # → http://localhost:3000
# → des résultats apparaissent en quelques secondes
```

Ports occupés sur la machine? Surcharger dans `.env` : `PG_PORT`, `REDIS_PORT`,
`SEARCH_PORT`, `API_PORT` (et les URLs correspondantes).

Stack complet en containers : `docker compose up -d --build` (le service `migrate`
applique les migrations, `crawler-worker` se scale avec
`docker compose up -d --scale crawler-worker=3`).

## Comment ça marche

### Crawl et politesse
- **Identité assumée** : UA `Mozilla/5.0 (compatible; TrouveKABot/0.1; +https://www.trouve-ka.com/trouveka-bot)`,
  page publique [/trouveka-bot](https://www.trouve-ka.com/trouveka-bot), pas de stealth.
- **robots.txt** parsé avec Protego, cache 24 h en base; `noindex`/`nofollow`/`X-Robots-Tag` respectés.
- **Politesse par origine** : verrou Redis par hôte (défaut 2 s entre requêtes, `Crawl-delay` respecté),
  quel que soit le nombre de workers.
- **Sécurité** : garde SSRF (IP privées/loopback/métadonnées cloud bloquées, revalidée à chaque
  redirection), limites par réponse (3 Mo, 5 redirections, timeout 20 s), détection de pièges
  (session IDs, calendriers infinis, facettes explosives, pagination sans fin).

### Indexation incrémentale
Le worker exécute fetch→parse→score→index **inline** : `refresh_interval: 1s` côté
OpenSearch → cherchable en secondes. Détection de changement par hash de contenu +
ETag/If-Modified-Since; recrawl adaptatif (inchangé → intervalle ×2, volatil → ÷2).

### Détection Québec
Deux scores distincts (`page` et `domaine`) calculés à partir de : TLD (.qc.ca, .quebec),
gazetteer de toponymes (pondération réduite pour les ambigus type Laval/Hull), codes
postaux G/H/J, indicatifs (418/514/438/…), organisations connues (Hydro-Québec, RAMQ,
UQAM…), mentions structurées de la province (JSON-LD), langue française (indice, pas preuve).
Déterministe et gratuit — aucun LLM dans le chemin chaud (§12).

### Ranking
`function_score` OpenSearch : BM25 bilingue (analyzers FR + EN, synonymes
thermopompe↔heat pump à la recherche) + scores Québec + autorité de domaine
(inlinks pondérés) + fraîcheur + boost de localité (« plombier Gatineau » → documents
avec preuve géographique `locations`). Chaque composant est optionnel; BM25 tient seul.

Évaluation mesurable : `python3 scripts/eval/run-eval.py --api http://localhost:8080`
(dataset dans `scripts/eval/ranking-eval.yaml`).

## API

- `GET /api/search?q=&page=&limit=&language=&category=&quebec_only=&freshness=`
- `GET /api/status` — compteurs publics (pages, domaines, débit, état du crawler)
- `POST /api/submit {"url": …}` — soumettre un site québécois (soumission ≠ inclusion)
- `GET|POST /api/admin/*` — protégé par header `X-Admin-Token` : overview, flux live,
  pause/reprise, seeds, recrawl, blocage de domaine, inspection du frontier

## Tests

```bash
.venv/bin/python -m pytest tests/          # 54 tests : URLs, SSRF, pièges, Québec, frontier, parser, fetcher, ranking
python3 scripts/check-headers.py           # header auteur obligatoire dans chaque fichier source (CI)
bash scripts/health-check/check.sh         # santé du stack
```

## Déploiement m2m32 + ngrok (www.trouve-ka.com)

Prérequis sur m2m32 : colima + docker + docker-compose (brew), ngrok authentifié,
domaine `www.trouve-ka.com` réservé dans le compte ngrok.

```bash
pnpm deploy:m2m32        # = bash infrastructure/deployment/deploy-m2m32.sh
```

Le script : rsync du monorepo → `docker compose up -d --build` → migrations + seeds
(idempotent) → tunnel `ngrok http --url=www.trouve-ka.com 3000` → health-check.
Le web proxifie `/api/*` vers l'API interne : un seul port exposé, pas d'URL absolues
côté client, cookies/CORS sans surprise derrière le tunnel.

Opérations courantes sur le node :

```bash
ssh M2M32 'cd trouve-ka && docker compose logs -f crawler-worker'   # crawl en direct
ssh M2M32 'cd trouve-ka && docker compose up -d --scale crawler-worker=3'
```

## Observabilité

Logs JSON structurés par service, métriques réelles via `/api/status` et
`/api/admin/overview`, dashboard `/admin` (files, débits, distribution HTTP, latences
p50/p95, flux live). Voir [infrastructure/monitoring/README.md](infrastructure/monitoring/README.md).

## Règles du dépôt

- **Header auteur obligatoire** dans chaque fichier source (§0.1) — vérifié par
  `scripts/check-headers.py`.
- **Aucune donnée factice** : pas de compteurs simulés, pas de résultats hard-codés;
  les fixtures vivent dans `tests/` uniquement.
- Provenance préservée : URL originale, canonique, timestamp de crawl, domaine source.
  Trouve-KA renvoie vers les éditeurs originaux.