# Vojo — Overview

## What is Vojo

A Matrix-based chat client targeting the Russian market. Fork of [Cinny](https://cinny.in) (MIT license), rebranded as Vojo. This repo is the **client only** — no server sources live here.

Value proposition: "Telegram works without VPN" — the server runs a mautrix-telegram bridge, users just open vojo.chat and chat.

## Infrastructure

- **Domain**: vojo.chat
- **Server**: Hostinger VPS `187.127.77.124` (hostname `srv1638609`), Ubuntu 24.04, user `vojo-superuser` (in groups `sudo`, `docker`, `docker-mautrix` GID 1337)
- **Homeserver**: Synapse (Matrix) + PostgreSQL 16 + Caddy 2 (reverse proxy, Let's Encrypt)
- **Bridges** (all `dock.mau.dev/mautrix/*` images, each with its own Postgres role + DB):
  - `telegram` — bridgev2 (Go) v26.04
  - `discord` — legacy (Go) v0.7.6+dev (image tag v0.7.5; bridgev2 rewrite ETA late 2026)
  - `whatsapp` — bridgev2 (Go) v26.04+dev (image v0.12.4)
  - Passive `doublepuppet` appservice (no `url`, non-exclusive `@.*:vojo.chat`) — one AS-token shared by all three bridges for double puppeting per megabridge spec. Legacy `synapse-shared-secret-auth` is gone; the `as_token:` prefix in each bridge's `secrets:` / `login_shared_secret_map:` is mandatory.
- **RTC**: LiveKit + `livekit-jwt-service` (Element Call backend; federation gated to `vojo.chat` via `LIVEKIT_FULL_ACCESS_HOMESERVERS` — see `desired_features.md` §5)
- **Push**: Sygnal (FCM + VAPID)
- **TURN**: coturn (host network mode)
- **Observability**: Prometheus + Grafana
- **Synapse modules**: in-tree `username_blocklist.py` bind-mounted into the Synapse image (`synapse/modules/`)
- **Client**: this repo — built and deployed as static files via Caddy
- **Bot widgets**: three Preact apps in `apps/widget-{telegram,discord,whatsapp}/`, built independently and deployed to `~/vojo/widgets/{telegram,discord,whatsapp}/` for BotShell to embed
- **AI bot ("Vojo AI", `@ai:vojo.chat`)**: a Go **Synapse appservice** in [`apps/ai-bot/`](../../apps/ai-bot/) (xAI-Grok backend; answers `@`-mentions in groups + all 1:1 messages). Built locally + shipped via `docker save`/`load`, deployed to `~/vojo/ai-bot/`. v1 is **backend-only — users add it by inviting `@ai` into any room manually**; the in-app "Bots"-tab widget + "Add to chat" picker (plan Parts B/C) are deferred. Branded **Vojo AI** with a generic icon — "Grok" is only the factual "powered by" attribution + the model id (xAI trademark). 152-ФЗ / transborder-transfer legal gating is a pre-launch item (see `docs/plans/grok_bot.md` §6). See `server-side.md` + `apps/ai-bot/README.md`.

Server filesystem under `~/vojo/`: `caddy/`, `synapse/`, `postgres/`, `coturn/`, `livekit/`, `sygnal/`, `prometheus/`, `grafana/`, `bridges/{telegram,discord,whatsapp}/`, `widgets/{telegram,discord,whatsapp}/`, `ai-bot/`, `cinny/`, `docker-compose.yml`. Caddy serves the client at `https://vojo.chat` with the host's `cinny/` directory bind-mounted into the container as `/var/www/cinny`.

## Branding

"Vojo" everywhere in UI, page titles, meta tags.

## Default homeserver

All configs must point to `vojo.chat` as the default and only homeserver. Hide homeserver selection from the user — end users should not need to know this is Matrix.

## Build & Deploy (web)

```bash
npm ci
npm run build
rsync -avz --delete dist/ vojo-superuser@187.127.77.124:~/vojo/cinny/
```

VSCode task `Deploy to vojo.chat` (Ctrl+Shift+D) automates this. The companion task `Deploy widgets` builds and rsyncs the three Preact widget apps under `apps/widget-{telegram,discord,whatsapp}/` to `~/vojo/widgets/<bridge>/` in parallel. Android build/deploy is covered in [android.md](android.md).

## Developer profile

- Git identity: `v.lagerev`, email `opnaigpt@gmail.com` (referred to as Julian in legacy notes)
- Background: C++ backend engineer, limited frontend experience
- Communicates in Russian
- Uses Claude Code agents heavily for frontend work
- Reviews both English (grammar) and Russian (naturalness) translation quality
- Notices lint regressions, exhaustive-deps issues, use-before-define errors
- Prefers concise communication with file paths and line numbers

## External references

- [Matrix Client-Server API](https://spec.matrix.org/latest/client-server-api/)
- [Synapse Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/)
