Zahavan'ia — A journalistic investigation assistant for Madagascar

**"You look — the AI looks with you."**

Zahavan'ia is the translation, in the southern dialect of Madagascar, of the Malagasy expression meaning "you look" — the gesture of paying attention to something, of looking together. Within the project's nomenclature, this name carries its full meaning: Zahavan'ia: "You look — the AI looks with you." The journalist stays in control; the AI helps them see further, faster, and above all with evidence to back it up.

Zahavan'ia helps journalists go from a raw piece of news they received (often via WhatsApp or Facebook) to verified, documented, and usable content. This is not a chatbot: it is a pipeline of Monitor → Verify (text/link, image) → Contextualize (figures) → Contact an expert → Find an angle.

---

Honesty principles (non-negotiable)

• Never a "true/false" verdict. Only the statuses confirmed, contradicted, insufficient, needs_verification.
• A 0–100 confidence index, computed by the code (lib/score.ts), never "decided" by the model, fully explained, and presented as indicative — not as a probability.
• Traceability: every conclusion links back to clickable sources (title, domain, date, URL). No usable source = insufficient status.
• The AI invents nothing: no source, no URL, no quote, no figure, no person's name.
• The journalist decides: every report offers Validate / Enrich / Reject.
• Images are clues, never proof. An image with "no anomaly" is not "authentic".
• Data is always dated and sourced (source, reference period, date last updated).

---

Features

Screen	What it does
Verify	Breaks a text or link down into individual claims and cross-checks them through web search; per-claim report with status, explainable confidence, and clickable sources.
Image / Video	EXIF metadata, visual clues, reverse-image search links; for video, 6 key frames extracted in the browser (no server-side ffmpeg).
Monitor	Groups articles together and raises alerts (P2).
Translate	Malagasy ⇄ French ⇄ English, with automatic checks (output language, sentence splitting).
Experts	Directory of consenting people, filterable by field, region, and language (fictional data in demo mode).
Stats	Dated, sourced World Bank indicators (data/stats.json).
Angles	Story-angle suggestions based only on confirmed claims.
My Dossiers	Local saving of reports (localStorage) — nothing leaves the device.

---

Tech stack

• Framework: Next.js 16 (App Router, cacheComponents) — single repo, with the app/api/* routes acting as the backend.
• Frontend: React 19, strict TypeScript, Tailwind CSS v4
• i18n: next-intl, language selected via the NEXT_LOCALE cookie (mg | fr | en, default mg)
• AI: the openai SDK pointed at OpenRouter, web search via the web plugin, zod validation on output
• Data: Supabase (anonymous auth + experts directory with RLS), data/stats.json, localStorage
• Media: sharp, exifr, image-size; 3D and animations: three + @react-three/fiber, gsap, lenis, motion
• Tests: vitest (tests/api/.test.ts) + node --test (tests/.test.mjs)
• Security: server-side keys only, SSRF protection for submitted URLs (lib/security/safe-fetch.ts), IP + user + day rate limiting, strict zod validation on input/output
• CI: GitHub Actions
• Deployment: Vercel or Docker

---

Local installation

Prerequisites

• Node.js 24+ (current LTS) and npm
• or Docker with Docker Compose v2
• An OpenRouter key for AI calls (optional in demo mode)

Method 1 — standard Next.js installation

1. Clone the repository

git clone zahavania cd zahavania

2. Install dependencies

npm ci

3. Configure your environment

cp .env.example .env.local

then edit .env.local (see "Environment variables" below)

4. Run in development

npm run dev

→ http://localhost:3000

In development, you can set USE_MOCK=true in .env.local to run without an API key (demo outputs are flagged with a "Demonstration" badge). This mode is ignored in production: npm run build && npm start requires real API calls.

Build and run in real conditions:

npm run build npm start

Method 2 — Docker

1. Configure your environment (secrets are read at runtime, never at build time)

cp .env.example .env.local

2. Build and start (application + PostgreSQL 17)

docker compose up --build

→ http://localhost:3000

The Dockerfile is multi-stage: npm ci → npm run build → minimal runtime image (Node 24 Alpine, standalone output, non-root user, port 3000). The db service (PostgreSQL) is not published on the host by default: the app reaches it at db:5432 on the Compose network. To access it with an external client, uncomment the ports block in docker-compose.yml.

Useful commands:

docker compose logs -f app # application logs docker compose down # stop docker compose down -v # stop + delete the PostgreSQL data

Environment variables

Secrets live in .env.local (git-ignored); .env.example contains no real values. The most important ones:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗