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
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
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:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
