Geo Watch

Geo Watch is a self-hosted, evidence-first platform for measuring and improving how brands appear in generative search. Its workflow is deliberately closed-loop:

Foundation → Observe → Diagnose → Improve → Distribute → Verify → Deliver

The product is a modular monolith with a PrimeVue SPA, FastAPI application, PostgreSQL system of record, Redis Streams workers, a local immutable ArtifactStore, and a Chromium MV3 side-panel extension. It is single-owner and multi-project.

Delivery truth

The application code, database migrations, workers, UI, extension, fixtures, and operations tools are present. Validation claims use three distinct levels:

• implemented: production code and a stable contract exist.
• fixtureVerified: deterministic tests or redacted adapter contract fixtures pass.
• liveValidated: a real external account or production-like runtime completed the operation.

No provider or publisher is called without credentials, and a missing credential is never reported as a successful integration. On 2026-08-24 the isolated production Compose topology passed S01-S16, Redis/worker fault recovery, real-browser SPA and MV3 checks, and a full backup restore rehearsal on Debian 12. The GitHub Actions Ubuntu 24.04 workflow is configured but has not been run in this local repository. Provider and publisher real-account validation remains false because no third-party credentials were supplied. See the capability ledger and acceptance report.

Technology baseline

• Python 3.13 and FastAPI 0.141.1+
• PostgreSQL 18.6 and Psycopg 3
• Redis Streams with PostgreSQL transactional outbox
• Vue 3, PrimeVue 4.5.5, Vue Query, Pinia, and Vue Router
• zh-CN, en-US, and ja-JP with identical message keys
• Project Forge 0.1.0 generation metadata, MIT License

The repository-root .venv is the only host Python environment. backend/.venv must not exist.

Local development

cp .env.example .env
make setup
make check

Create secrets/master-key.txt as 1:<base64-encoded-32-byte-key>, start PostgreSQL and Redis, then apply migrations and initialize the single owner:

make migrate-up
.venv/bin/app owner init --username owner
make backend-dev
make frontend-dev

All development and published Compose ports bind to 127.0.0.1 by default. Public access also requires HTTPS, trusted proxy configuration, allowed Origin/Host values, and an explicit APP_SESSION_COOKIE_SECURE=true; loopback HTTP defaults to false so local browser sessions work. An operator who explicitly accepts clear-text LAN risk may set APP_ALLOW_INSECURE_LAN_HTTP=true, but every Origin, Host, and trusted proxy must be an explicit loopback, RFC1918, or ULA IP. Public addresses, hostnames, paths, wildcard proxies, and conflicting Secure Cookie settings remain blocked.

Useful operations:

.venv/bin/app migrate status
.venv/bin/app backup create
.venv/bin/app retention preview

Read AGENTS.md before editing. The authoritative product and architecture documents start at docs/README.md.