Sentinel

Centralized Wikipedia monitoring and bookmarking for patrollers. Complements RTRC with curated watchlists, shared notes, collections, and admin-gated community access.

Sentinel is built for all Wikimedia projects and languages. The live deployment at sentinel.toolforge.org currently serves the Persian Wikipedia patroller community, but the stack is multi-wiki and translatewiki.net-ready by design.

Hosting: Toolforge — see deploy/toolforge.md

Quick start (local)

cp .env.example .env
# Edit .env — set INITIAL_ADMIN_USERNAME to your Wikimedia username for local bootstrap

docker compose up -d db redis
docker compose up backend   # runs migrations + API on :8000

# Separate terminal — frontend dev server with API proxy
cd frontend && npm install && npm run dev

Open http://localhost:5173

Features

Bookmarks & monitoring

• Bookmark users, articles, and specific revisions
• Collections — private or shared bookmark groups
• Tags — label and filter bookmarks from the sidebar
• Bookmark drawer — notes, activity, and manage tabs
• Live feed — WebSocket push when new edits are found (/api/feed/ws)
• Feed filters — bookmarked users, articles, or both
• Diff preview — in-app diff modal (MediaWiki compare API, Redis-cached)
• EventStreams — optional Wikimedia SSE listener (EVENTSTREAMS_ENABLED=true); reconnects automatically when the server closes idle streams

Local dev runs the poller inside the backend process (FEED_POLLER_ENABLED=true in .env). On Toolforge, use a continuous job and set FEED_POLLER_ENABLED=false on the webservice.

# Smoke-test EventStreams (from backend/)
USER_AGENT='Sentinel/0.2 (http://localhost:8000; dev@localhost)' PYTHONPATH=. python scripts/test_eventstreams.py

Multi-wiki & preferences

• Multi-wiki — per-bookmark wiki_url; pick wiki when adding bookmarks
• Settings (/settings) — default wiki and interface language
• Table view — toggle bookmark list layout on the dashboard

Configure available wikis via SUPPORTED_WIKIS and DEFAULT_WIKI_URL in .env.

Admin & moderation

• Admin hub (/admin) — pending approvals, suspend/reinstate, flagged notes, audit log
• Note flagging — patrollers flag notes; admins restore or remove
• Threaded notes — reply to notes on bookmark targets
• OAuth gate — Wikimedia login with manual admin approval for new users

PII handling stays checkbox attestation only — no LLM or external scanning services.

Interface

• Codex (@wikimedia/codex) — Wikimedia design system components and tokens
• Dark mode — user preference, Vector-aligned styling
• Internationalization — English source + community translations via translatewiki.net; RTL locales (e.g. Persian) supported
• Layout helpers in frontend/src/assets/sentinel.css; Codex bridge in frontend/src/codex/i18n.ts

Internationalization

• Locale files: frontend/src/i18n/locales/*.json (en.json + qqq.json maintained by developers)
• vue-i18n + banana-i18n for MediaWiki message syntax ($1, {{PLURAL}})
• Switch language in Settings — preference stored in localStorage (sentinel-locale) and synced to the user profile when logged in
• Run npm run check:i18n before committing string changes

Tests

cd backend
pip install -r requirements-dev.txt
pytest

Without Docker

# MariaDB + Redis running locally
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload --port 8000

Production build (Toolforge)

npm run build:frontend   # → backend/app/static/
git add backend/app/static && git commit -m "Build frontend"

Commit the static assets before pushing — Toolforge does not build the Vue app automatically. See deploy/toolforge.md.

Project layout

sentinel/
├── .gitlab/            # Merge request template
├── CHANGELOG.md        # Release history
├── CONTRIBUTING.md     # How to contribute
├── DESIGN.md           # System design (WMCS-aware)
├── deploy/             # Toolforge deployment guide
├── backend/            # FastAPI + SQLAlchemy + Alembic
├── frontend/           # Vue 3 SPA
├── Procfile            # Toolforge webservice entry
└── docker-compose.yml  # Local dev (MariaDB + Redis)

API docs

When the backend is running: http://localhost:8000/docs

Contributing

See CONTRIBUTING.md. Release history is in CHANGELOG.md.

Development

Much of this codebase was written with the help of AI coding assistants. Every change is manually reviewed and tested by humans before it is merged or released.

License

GPLv3+ (recommended for Toolforge; see right to fork policy)