move all ai docs to folder
This commit is contained in:
parent
6fbcf94cd9
commit
c7c47ec23a
9 changed files with 368 additions and 264 deletions
20
BUGS.md
20
BUGS.md
|
|
@ -1,20 +0,0 @@
|
||||||
# Known Bugs & Regressions
|
|
||||||
|
|
||||||
## Open
|
|
||||||
|
|
||||||
### [CAP-001] SSO UIA flow may hang in Capacitor WebView
|
|
||||||
|
|
||||||
**Severity**: Low
|
|
||||||
**Component**: `src/app/components/uia-stages/SSOStage.tsx`, `src/app/components/ActionUIA.tsx`
|
|
||||||
**Platform**: Android (Capacitor)
|
|
||||||
|
|
||||||
**Description**: `SSOStage` uses `window.open()` + `window.postMessage()` callback pattern for SSO re-authentication during UIA operations (password change, account deactivation, etc.). In Capacitor, the Browser plugin opens a separate process, and `postMessage` callback may not reach the WebView, causing the UIA flow to hang.
|
|
||||||
|
|
||||||
**Impact**: Only affects users whose homeserver requires SSO for UIA (not password). Vojo users authenticate via password, so UIA also uses password flow. Risk is low for current user base.
|
|
||||||
|
|
||||||
**Workaround**: None needed for password-authenticated users.
|
|
||||||
**Fix options**: Remove `AuthType.Sso` from `SUPPORTED_IN_APP_UIA_STAGES` in `ActionUIA.tsx`, or rewrite SSO callback to use Capacitor App URL listener instead of `postMessage`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Resolved
|
|
||||||
196
CLAUDE.md
196
CLAUDE.md
|
|
@ -1,195 +1,7 @@
|
||||||
# Vojo — Project Guide
|
# Directive for AI agents
|
||||||
|
|
||||||
Matrix chat client (React 18 + TypeScript), forked from Cinny and rebranded as Vojo. This is only client repo (there is no server side sources)
|
**All project context for Vojo lives in [`docs/ai/`](docs/ai/README.md). Read it before making any non-trivial change.**
|
||||||
|
|
||||||
## Quick Start
|
This file exists only as a pointer. Do not add project knowledge here — put it in `docs/ai/`. Same rule for `.cursorrules`, `.windsurfrules`, `AGENTS.md`, `.codex`, home-directory memory, or any other agent-specific context file: if you're tempted to write project knowledge there, write it in `docs/ai/` instead and keep those files as thin pointers.
|
||||||
|
|
||||||
```bash
|
Start here: [docs/ai/README.md](docs/ai/README.md).
|
||||||
npm start # dev server on :8080
|
|
||||||
npm run build # production build → dist/
|
|
||||||
npm run lint # eslint + prettier
|
|
||||||
npm run typecheck # tsc --noEmit
|
|
||||||
```
|
|
||||||
|
|
||||||
Build: **Vite 5.4** with vanilla-extract, WASM, PWA plugins.
|
|
||||||
|
|
||||||
## Source Layout
|
|
||||||
|
|
||||||
```
|
|
||||||
src/
|
|
||||||
├── index.tsx # Entry point
|
|
||||||
├── client/
|
|
||||||
│ ├── initMatrix.ts # Matrix SDK init (createClient, startClient, logout)
|
|
||||||
│ └── secretStorageKeys.js # Crypto callbacks
|
|
||||||
├── types/matrix/ # Matrix protocol types (room.ts, accountData.ts, common.ts)
|
|
||||||
└── app/
|
|
||||||
├── i18n.ts # i18next config
|
|
||||||
├── pages/
|
|
||||||
│ └── App.tsx # Root component (providers, config loader)
|
|
||||||
├── features/ # Feature modules
|
|
||||||
├── components/ # Shared components
|
|
||||||
├── hooks/ # ~117 custom hooks
|
|
||||||
├── state/ # Jotai atoms
|
|
||||||
├── plugins/ # Content plugins
|
|
||||||
├── utils/ # Utilities
|
|
||||||
└── styles/ # Vanilla-extract global styles
|
|
||||||
```
|
|
||||||
|
|
||||||
## Pages & Routing (`src/app/pages/`)
|
|
||||||
|
|
||||||
Router in `Router.tsx` — createBrowserRouter / createHashRouter.
|
|
||||||
|
|
||||||
- **Auth**: `auth/login/`, `auth/register/`, `auth/reset-password/`
|
|
||||||
- **Client**: `client/` — main layout after login
|
|
||||||
- `home/` — Home timeline (path: `/home/`, root `/` redirects here)
|
|
||||||
- `direct/` — DMs (path: `/direct/`)
|
|
||||||
- `space/` — Space view (path: `/:spaceIdOrAlias/`)
|
|
||||||
- `explore/` — Public rooms (path: `/explore/`)
|
|
||||||
- `inbox/` — Notifications, invites (path: `/inbox/`)
|
|
||||||
- `create/` — New room/space (path: `/create/`)
|
|
||||||
- `sidebar/` — Tab components for sidebar nav
|
|
||||||
- `WelcomePage.tsx` — Empty state
|
|
||||||
- `SyncStatus.tsx`, `SpecVersions.tsx` — Connection status
|
|
||||||
|
|
||||||
## Features (`src/app/features/`)
|
|
||||||
|
|
||||||
| Dir | Purpose |
|
|
||||||
|-----|---------|
|
|
||||||
| `room/` | Core room view — **RoomTimeline.tsx** (63KB), **RoomInput.tsx** (24KB), **RoomViewHeader.tsx** (18KB), MembersDrawer, MessageEditor, RoomTombstone |
|
|
||||||
| `room-nav/` | Room list navigation items & categories |
|
|
||||||
| `room-settings/` | Room-specific settings page |
|
|
||||||
| `common-settings/` | Shared settings: general, members, permissions, emojis-stickers, developer-tools |
|
|
||||||
| `space-settings/` | Space-specific settings |
|
|
||||||
| `settings/` | User settings (general, account, notifications, devices, emojis, about, dev-tools) |
|
|
||||||
| `lobby/` | Space/room lobby view |
|
|
||||||
| `search/` | Global search |
|
|
||||||
| `message-search/` | In-room message search |
|
|
||||||
| `create-chat/` | DM creation flow |
|
|
||||||
| `create-room/` | Room creation |
|
|
||||||
| `create-space/` | Space creation |
|
|
||||||
| `add-existing/` | Join existing rooms |
|
|
||||||
| `join-before-navigate/` | Pre-join navigation logic |
|
|
||||||
| `call/` | Element Call integration |
|
|
||||||
| `call-status/` | Call state display |
|
|
||||||
|
|
||||||
## Key Components (`src/app/components/`)
|
|
||||||
|
|
||||||
- `message/` — Message rendering (layout variants: compact, bubble, modern)
|
|
||||||
- `editor/` — Slate-based rich text editor
|
|
||||||
- `emoji-board/` — Emoji picker
|
|
||||||
- `image-pack-view/` — Custom emoji pack management
|
|
||||||
- `image-viewer/`, `Pdf-viewer/` — Media viewers
|
|
||||||
- `sidebar/` — Sidebar navigation
|
|
||||||
- `user-profile/` — User info, power chips, moderation
|
|
||||||
- `member-tile/` — Member list items
|
|
||||||
- `power/` — Power level UI
|
|
||||||
- `upload-card/` — Upload progress cards
|
|
||||||
- `url-preview/` — Link previews
|
|
||||||
- `page/` — Page layout wrapper (Page, PageHeader, PageContent)
|
|
||||||
- `setting-tile/` — Settings list item pattern
|
|
||||||
- `sequence-card/`, `cutout-card/` — Card layouts
|
|
||||||
- `uia-stages/` — User-interactive auth stages (email, captcha, token)
|
|
||||||
- `room-intro/` — Room introduction card
|
|
||||||
- `invite-user-prompt/`, `join-address-prompt/`, `leave-room-prompt/` — Dialogs
|
|
||||||
|
|
||||||
## State Management
|
|
||||||
|
|
||||||
**Jotai** atoms in `src/app/state/`:
|
|
||||||
- `settings.ts` — User preferences (MessageLayout, DateFormat, etc.)
|
|
||||||
- `sessions.ts` — Active session
|
|
||||||
- `upload.ts` — Upload progress
|
|
||||||
- `room/` — roomInputDrafts, roomToParents, roomToUnread
|
|
||||||
- `room-list/` — roomList, inviteList, sorting/filtering
|
|
||||||
|
|
||||||
Some atoms persist to localStorage (e.g. `settings.ts`, `navToActivePath.ts`), others are in-memory only (e.g. `upload.ts`, `roomInputDrafts.ts`). Access via hooks in `state/hooks/`.
|
|
||||||
|
|
||||||
## Localisation (i18n)
|
|
||||||
|
|
||||||
**Config**: `src/app/i18n.ts` — i18next + HTTP backend + language detector, `fallbackLng: 'ru'`
|
|
||||||
|
|
||||||
**Locale files**: `public/locales/en.json`, `public/locales/ru.json`
|
|
||||||
|
|
||||||
**Namespaces** (top-level keys in JSON):
|
|
||||||
`Organisms`, `Auth`, `Settings`, `Search`, `Home`, `Direct`, `Room`, `Inbox`, `Explore`, `Create`, `RoomSettings`
|
|
||||||
|
|
||||||
**Pattern**:
|
|
||||||
```tsx
|
|
||||||
import { useTranslation } from 'react-i18next';
|
|
||||||
|
|
||||||
const { t } = useTranslation();
|
|
||||||
return <Text>{t('RoomSettings.some_key')}</Text>;
|
|
||||||
```
|
|
||||||
|
|
||||||
**Conventions**:
|
|
||||||
- Each component gets its own `useTranslation()` call
|
|
||||||
- In custom hooks with `useMemo`, add `[t]` to dependency array
|
|
||||||
- `react-i18next` import goes after framework imports, before local imports
|
|
||||||
- For dynamic values: `t('key', { count: 5 })`
|
|
||||||
- For rare cases with HTML in translations: `dangerouslySetInnerHTML` (used sparingly, e.g. in RoomAddress.tsx)
|
|
||||||
|
|
||||||
## Key Libraries
|
|
||||||
|
|
||||||
- **React 18.2** + React Router DOM 6
|
|
||||||
- **matrix-js-sdk 38.2** — Matrix protocol
|
|
||||||
- **folds 2.6** — UI component library
|
|
||||||
- **jotai 2.6** — State management
|
|
||||||
- **vanilla-extract** — Type-safe CSS
|
|
||||||
- **slate 0.123** — Rich text editor
|
|
||||||
- **@tanstack/react-query 5** — Data fetching
|
|
||||||
- **@tanstack/react-virtual 3** — Virtual scrolling
|
|
||||||
- **i18next 23 + react-i18next 15** — Localisation
|
|
||||||
- **Capacitor 8.3** — Native Android wrapper
|
|
||||||
- **@capacitor/browser 8.0** — External link handling in native
|
|
||||||
|
|
||||||
## Android (Capacitor)
|
|
||||||
|
|
||||||
**Requirements**: Node >=22, JDK 17+ (21 used), Android SDK with platform 36 + build-tools 36.0.0
|
|
||||||
|
|
||||||
**Config**: `capacitor.config.ts` — `appId: chat.vojo.app`, `webDir: dist`
|
|
||||||
|
|
||||||
**Android project**: `android/` — generated, `targetSdkVersion 36`, `compileSdkVersion 36`, `minSdkVersion 24`
|
|
||||||
|
|
||||||
**Build scripts**:
|
|
||||||
```bash
|
|
||||||
npm run build:android:debug # full chain: build → sync → debug APK
|
|
||||||
npm run build:android:release # full chain: build → sync → release APK
|
|
||||||
npm run build:android:aab # full chain: build → sync → release AAB
|
|
||||||
npm run android:sync # sync dist/ → android assets
|
|
||||||
npm run android:apk:debug # gradle debug build only
|
|
||||||
```
|
|
||||||
|
|
||||||
**APK output**: `android/app/build/outputs/apk/debug/app-debug.apk`
|
|
||||||
|
|
||||||
**Version**: `versionCode` and `versionName` auto-derived from `package.json` version (major*1000000 + minor*1000 + patch)
|
|
||||||
|
|
||||||
**Key architecture decisions**:
|
|
||||||
- Bundled build (dist/ copied into APK), not remote WebView
|
|
||||||
- Service Worker kept active — critical for authenticated Matrix media (MSC3916 / spec v1.11+). Do NOT disable. `resolveServiceWorkerRequests` default `true`.
|
|
||||||
- Edge-to-edge via `EdgeToEdge.enable()` in `MainActivity.java` + `windowLayoutInDisplayCutoutMode: shortEdges`
|
|
||||||
- External links opened via `@capacitor/browser` plugin (see `src/app/utils/capacitor.ts`)
|
|
||||||
- `body` background-color bound to folds theme variable `var(--oq6d070)` for consistent safe-area coloring
|
|
||||||
- Safe-area insets applied on `#root` (not `body`) so theme background extends behind system bars
|
|
||||||
|
|
||||||
**VSCode tasks** (`.vscode/tasks.json`):
|
|
||||||
- `Deploy to vojo.chat` (Ctrl+Shift+D) — web deploy
|
|
||||||
- `Deploy to Android (ADB)` (Ctrl+Shift+A) — build + adb install
|
|
||||||
|
|
||||||
**ADB wireless**: pair via `adb pair <ip>:<port> <code>`, connect via `adb connect <ip>:<port>`. Ports for pair and connect are different.
|
|
||||||
|
|
||||||
**SDK location**: `/usr/lib/android-sdk`, also set in `android/local.properties`
|
|
||||||
|
|
||||||
## Matrix SDK Patterns
|
|
||||||
|
|
||||||
```tsx
|
|
||||||
const mx = useMatrixClient(); // Get SDK instance
|
|
||||||
const room = useRoom(); // Current room
|
|
||||||
const stateEvent = useStateEvent(room, StateEvent.Type); // Room state
|
|
||||||
const powerLevels = usePowerLevels(room); // Permissions
|
|
||||||
```
|
|
||||||
|
|
||||||
## Git
|
|
||||||
|
|
||||||
- Main branch: `dev`
|
|
||||||
- Current work branch: `vojo/dev`
|
|
||||||
- Semantic-release on `dev` branch
|
|
||||||
- CI: GitHub Actions (build, deploy, docker, netlify)
|
|
||||||
|
|
|
||||||
52
PROMT.md
52
PROMT.md
|
|
@ -1,52 +0,0 @@
|
||||||
# Vojo — Matrix-based messenger for the Russian market
|
|
||||||
|
|
||||||
## What is this
|
|
||||||
|
|
||||||
This is a fork of Cinny (https://cinny.in, MIT license) rebranded as Vojo.
|
|
||||||
Vojo is an independent messenger built on the Matrix protocol, targeting
|
|
||||||
Russian users affected by Telegram blocking.
|
|
||||||
|
|
||||||
Key value proposition: "Telegram works without VPN" — the server maintains
|
|
||||||
Telegram bridge connections, users just open vojo.chat and chat.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
- **Domain**: vojo.chat
|
|
||||||
- **Server**: Yandex Cloud VPS, Ubuntu 24.04
|
|
||||||
- **Backend**: Synapse (Matrix homeserver) + PostgreSQL + Caddy (reverse proxy)
|
|
||||||
- **Bridges**: mautrix-telegram (Python v0.15.3, SOCKS5 proxy for Telegram)
|
|
||||||
- **Client**: This repo — Cinny fork, deployed as static files via Caddy
|
|
||||||
|
|
||||||
The client is served from `~/vojo/cinny/` on the server.
|
|
||||||
Caddy serves it at `https://vojo.chat`.
|
|
||||||
|
|
||||||
## Branding
|
|
||||||
|
|
||||||
- **Name**: 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 — they don't need to know about Matrix.
|
|
||||||
|
|
||||||
## Build & Deploy
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm ci
|
|
||||||
npm run build
|
|
||||||
# Output in dist/
|
|
||||||
scp -r dist/* vojo-superuser@111.88.146.156:~/vojo/cinny/
|
|
||||||
```
|
|
||||||
|
|
||||||
Caddy serves from `/var/www/cinny` (symlinked to ~/vojo/cinny).
|
|
||||||
|
|
||||||
## Key API Reference
|
|
||||||
|
|
||||||
- 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/
|
|
||||||
|
|
||||||
## Developer
|
|
||||||
|
|
||||||
Julian — C++ backend engineer. Limited frontend experience.
|
|
||||||
Using Claude Code agents for frontend work.
|
|
||||||
29
docs/ai/README.md
Normal file
29
docs/ai/README.md
Normal file
|
|
@ -0,0 +1,29 @@
|
||||||
|
# Vojo — AI Context Bank
|
||||||
|
|
||||||
|
**Single source of truth for every AI agent working on this repo.**
|
||||||
|
|
||||||
|
## Directive
|
||||||
|
|
||||||
|
Any agent (Claude Code, Cursor, Codex, Windsurf, Cline, Copilot, Aider, …) working here MUST:
|
||||||
|
|
||||||
|
1. Read every file in [docs/ai/](.) before making non-trivial changes.
|
||||||
|
2. Treat this folder as the ONLY authoritative source for project context.
|
||||||
|
3. Write new project knowledge HERE, not in `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, `AGENTS.md`, home-dir memory, or wherever else your tool defaults to.
|
||||||
|
4. If a top-level agent file (like `CLAUDE.md`) appears to disagree with anything in `docs/ai/`, `docs/ai/` wins. Treat the top-level file as a stale pointer and fix it.
|
||||||
|
|
||||||
|
## Contents
|
||||||
|
|
||||||
|
| File | What's in it |
|
||||||
|
|------|--------------|
|
||||||
|
| [overview.md](overview.md) | What Vojo is, infrastructure, deployment target, developer profile, default homeserver rule |
|
||||||
|
| [architecture.md](architecture.md) | Stack, source layout, routing, features, state management, Matrix SDK patterns, git workflow |
|
||||||
|
| [i18n.md](i18n.md) | i18next setup, translation patterns, Russian-language quality standards, localization progress |
|
||||||
|
| [android.md](android.md) | Capacitor wrapper, Android build chain, edge-to-edge, Service Worker invariants, ADB workflow |
|
||||||
|
| [bugs.md](bugs.md) | Known bugs & regressions |
|
||||||
|
|
||||||
|
## Rules for updating
|
||||||
|
|
||||||
|
- Prefer editing an existing entry over adding a new one.
|
||||||
|
- Don't duplicate content across files — pick the best home and cross-link if needed.
|
||||||
|
- Do not create a new `CLAUDE.md`, `.cursorrules`, `AGENTS.md`, etc. with project knowledge. Those files should only contain a pointer back here.
|
||||||
|
- If you add a new topic file, also add it to the table above.
|
||||||
57
docs/ai/android.md
Normal file
57
docs/ai/android.md
Normal file
|
|
@ -0,0 +1,57 @@
|
||||||
|
# Android (Capacitor)
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Node >= 22
|
||||||
|
- JDK 17+ (21 used in practice)
|
||||||
|
- Android SDK with platform 36 + build-tools 36.0.0
|
||||||
|
- SDK location: `/usr/lib/android-sdk`, also set in `android/local.properties`
|
||||||
|
|
||||||
|
## Config
|
||||||
|
|
||||||
|
- [`capacitor.config.ts`](../../capacitor.config.ts) — `appId: chat.vojo.app`, `webDir: dist`
|
||||||
|
- `android/` — generated Android Studio project, `targetSdkVersion 36`, `compileSdkVersion 36`, `minSdkVersion 24`
|
||||||
|
|
||||||
|
## Build scripts
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build:android:debug # full chain: build → sync → debug APK
|
||||||
|
npm run build:android:release # full chain: build → sync → release APK
|
||||||
|
npm run build:android:aab # full chain: build → sync → release AAB
|
||||||
|
npm run android:sync # sync dist/ → android assets
|
||||||
|
npm run android:apk:debug # gradle debug build only
|
||||||
|
```
|
||||||
|
|
||||||
|
**APK output**: `android/app/build/outputs/apk/debug/app-debug.apk`
|
||||||
|
|
||||||
|
## Versioning
|
||||||
|
|
||||||
|
`versionCode` and `versionName` auto-derived from `package.json` version:
|
||||||
|
|
||||||
|
```
|
||||||
|
versionCode = major * 1_000_000 + minor * 1_000 + patch
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key architecture decisions
|
||||||
|
|
||||||
|
- **Bundled build.** `dist/` is copied into the APK — not loaded remotely in a WebView.
|
||||||
|
- **Service Worker stays active.** Critical for authenticated Matrix media (MSC3916 / Matrix spec v1.11+). DO NOT disable. `resolveServiceWorkerRequests` default `true`.
|
||||||
|
- **Edge-to-edge.** `EdgeToEdge.enable()` in `MainActivity.java` + `windowLayoutInDisplayCutoutMode: shortEdges`.
|
||||||
|
- **External links.** Opened via `@capacitor/browser` plugin — see [`src/app/utils/capacitor.ts`](../../src/app/utils/capacitor.ts).
|
||||||
|
- **Safe-area coloring.** `body` background-color is bound to the folds theme variable `var(--oq6d070)` for consistent safe-area coloring.
|
||||||
|
- **Safe-area insets.** Applied on `#root` (not `body`) so the theme background extends behind the system bars.
|
||||||
|
|
||||||
|
## VSCode tasks
|
||||||
|
|
||||||
|
See [`.vscode/tasks.json`](../../.vscode/tasks.json):
|
||||||
|
|
||||||
|
- `Deploy to vojo.chat` (Ctrl+Shift+D) — web deploy
|
||||||
|
- `Deploy to Android (ADB)` (Ctrl+Shift+A) — build + `adb install`
|
||||||
|
|
||||||
|
## ADB wireless workflow
|
||||||
|
|
||||||
|
1. On the phone, enable Wireless debugging, tap "Pair device with pairing code" — note IP, port, 6-digit code.
|
||||||
|
2. `adb pair <ip>:<pair-port> <code>`
|
||||||
|
3. `adb connect <ip>:<connect-port>`
|
||||||
|
|
||||||
|
The pair port and the connect port are different — don't mix them up.
|
||||||
133
docs/ai/architecture.md
Normal file
133
docs/ai/architecture.md
Normal file
|
|
@ -0,0 +1,133 @@
|
||||||
|
# Architecture
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm start # dev server on :8080
|
||||||
|
npm run build # production build → dist/
|
||||||
|
npm run lint # eslint + prettier
|
||||||
|
npm run typecheck # tsc --noEmit
|
||||||
|
```
|
||||||
|
|
||||||
|
Build: **Vite 5.4** with vanilla-extract, WASM, PWA plugins.
|
||||||
|
|
||||||
|
## Source Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── index.tsx # Entry point
|
||||||
|
├── client/
|
||||||
|
│ ├── initMatrix.ts # Matrix SDK init (createClient, startClient, logout)
|
||||||
|
│ └── secretStorageKeys.js # Crypto callbacks
|
||||||
|
├── types/matrix/ # Matrix protocol types (room.ts, accountData.ts, common.ts)
|
||||||
|
└── app/
|
||||||
|
├── i18n.ts # i18next config
|
||||||
|
├── pages/
|
||||||
|
│ └── App.tsx # Root component (providers, config loader)
|
||||||
|
├── features/ # Feature modules
|
||||||
|
├── components/ # Shared components
|
||||||
|
├── hooks/ # ~117 custom hooks
|
||||||
|
├── state/ # Jotai atoms
|
||||||
|
├── plugins/ # Content plugins
|
||||||
|
├── utils/ # Utilities
|
||||||
|
└── styles/ # Vanilla-extract global styles
|
||||||
|
```
|
||||||
|
|
||||||
|
## Pages & Routing (`src/app/pages/`)
|
||||||
|
|
||||||
|
Router in `Router.tsx` — `createBrowserRouter` / `createHashRouter`.
|
||||||
|
|
||||||
|
- **Auth**: `auth/login/`, `auth/register/`, `auth/reset-password/`
|
||||||
|
- **Client**: `client/` — main layout after login
|
||||||
|
- `home/` — Home timeline (path: `/home/`, root `/` redirects here)
|
||||||
|
- `direct/` — DMs (path: `/direct/`)
|
||||||
|
- `space/` — Space view (path: `/:spaceIdOrAlias/`)
|
||||||
|
- `explore/` — Public rooms (path: `/explore/`)
|
||||||
|
- `inbox/` — Notifications, invites (path: `/inbox/`)
|
||||||
|
- `create/` — New room/space (path: `/create/`)
|
||||||
|
- `sidebar/` — Tab components for sidebar nav
|
||||||
|
- `WelcomePage.tsx` — Empty state
|
||||||
|
- `SyncStatus.tsx`, `SpecVersions.tsx` — Connection status
|
||||||
|
|
||||||
|
## Features (`src/app/features/`)
|
||||||
|
|
||||||
|
| Dir | Purpose |
|
||||||
|
|-----|---------|
|
||||||
|
| `room/` | Core room view — **RoomTimeline.tsx** (~63KB), **RoomInput.tsx** (~24KB), **RoomViewHeader.tsx** (~18KB), MembersDrawer, MessageEditor, RoomTombstone |
|
||||||
|
| `room-nav/` | Room list navigation items & categories |
|
||||||
|
| `room-settings/` | Room-specific settings page |
|
||||||
|
| `common-settings/` | Shared settings: general, members, permissions, emojis-stickers, developer-tools |
|
||||||
|
| `space-settings/` | Space-specific settings |
|
||||||
|
| `settings/` | User settings (general, account, notifications, devices, emojis, about, dev-tools) |
|
||||||
|
| `lobby/` | Space/room lobby view |
|
||||||
|
| `search/` | Global search |
|
||||||
|
| `message-search/` | In-room message search |
|
||||||
|
| `create-chat/` | DM creation flow |
|
||||||
|
| `create-room/` | Room creation |
|
||||||
|
| `create-space/` | Space creation |
|
||||||
|
| `add-existing/` | Join existing rooms |
|
||||||
|
| `join-before-navigate/` | Pre-join navigation logic |
|
||||||
|
| `call/` | Element Call integration |
|
||||||
|
| `call-status/` | Call state display |
|
||||||
|
|
||||||
|
## Key Components (`src/app/components/`)
|
||||||
|
|
||||||
|
- `message/` — Message rendering (layout variants: compact, bubble, modern)
|
||||||
|
- `editor/` — Slate-based rich text editor
|
||||||
|
- `emoji-board/` — Emoji picker
|
||||||
|
- `image-pack-view/` — Custom emoji pack management
|
||||||
|
- `image-viewer/`, `Pdf-viewer/` — Media viewers
|
||||||
|
- `sidebar/` — Sidebar navigation
|
||||||
|
- `user-profile/` — User info, power chips, moderation
|
||||||
|
- `member-tile/` — Member list items
|
||||||
|
- `power/` — Power level UI
|
||||||
|
- `upload-card/` — Upload progress cards
|
||||||
|
- `url-preview/` — Link previews
|
||||||
|
- `page/` — Page layout wrapper (Page, PageHeader, PageContent)
|
||||||
|
- `setting-tile/` — Settings list item pattern
|
||||||
|
- `sequence-card/`, `cutout-card/` — Card layouts
|
||||||
|
- `uia-stages/` — User-interactive auth stages (email, captcha, token)
|
||||||
|
- `room-intro/` — Room introduction card
|
||||||
|
- `invite-user-prompt/`, `join-address-prompt/`, `leave-room-prompt/` — Dialogs
|
||||||
|
|
||||||
|
## State Management
|
||||||
|
|
||||||
|
**Jotai** atoms in `src/app/state/`:
|
||||||
|
|
||||||
|
- `settings.ts` — User preferences (MessageLayout, DateFormat, …)
|
||||||
|
- `sessions.ts` — Active session
|
||||||
|
- `upload.ts` — Upload progress
|
||||||
|
- `room/` — `roomInputDrafts`, `roomToParents`, `roomToUnread`
|
||||||
|
- `room-list/` — `roomList`, `inviteList`, sorting/filtering
|
||||||
|
|
||||||
|
Some atoms persist to localStorage (e.g. `settings.ts`, `navToActivePath.ts`), others are in-memory only (e.g. `upload.ts`, `roomInputDrafts.ts`). Access via hooks in `state/hooks/`.
|
||||||
|
|
||||||
|
## Matrix SDK Patterns
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
const mx = useMatrixClient(); // Get SDK instance
|
||||||
|
const room = useRoom(); // Current room
|
||||||
|
const stateEvent = useStateEvent(room, StateEvent.Type); // Room state
|
||||||
|
const powerLevels = usePowerLevels(room); // Permissions
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key Libraries
|
||||||
|
|
||||||
|
- **React 18.2** + React Router DOM 6
|
||||||
|
- **matrix-js-sdk 38.2** — Matrix protocol
|
||||||
|
- **folds 2.6** — UI component library
|
||||||
|
- **jotai 2.6** — State management
|
||||||
|
- **vanilla-extract** — Type-safe CSS
|
||||||
|
- **slate 0.123** — Rich text editor
|
||||||
|
- **@tanstack/react-query 5** — Data fetching
|
||||||
|
- **@tanstack/react-virtual 3** — Virtual scrolling
|
||||||
|
- **i18next 23 + react-i18next 15** — Localisation
|
||||||
|
- **Capacitor 8.3** — Native Android wrapper
|
||||||
|
- **@capacitor/browser 8.0** — External link handling in native
|
||||||
|
|
||||||
|
## Git
|
||||||
|
|
||||||
|
- Main branch: `dev`
|
||||||
|
- Current work branch: `vojo/dev`
|
||||||
|
- Semantic-release on `dev` branch
|
||||||
|
- CI: GitHub Actions (build, deploy, docker, netlify)
|
||||||
23
docs/ai/bugs.md
Normal file
23
docs/ai/bugs.md
Normal file
|
|
@ -0,0 +1,23 @@
|
||||||
|
# Known Bugs & Regressions
|
||||||
|
|
||||||
|
## Open
|
||||||
|
|
||||||
|
### [CAP-001] SSO UIA flow may hang in Capacitor WebView
|
||||||
|
|
||||||
|
- **Severity**: Low
|
||||||
|
- **Component**: [`src/app/components/uia-stages/SSOStage.tsx`](../../src/app/components/uia-stages/SSOStage.tsx), [`src/app/components/ActionUIA.tsx`](../../src/app/components/ActionUIA.tsx)
|
||||||
|
- **Platform**: Android (Capacitor)
|
||||||
|
|
||||||
|
**Description**: `SSOStage` uses `window.open()` + `window.postMessage()` callback pattern for SSO re-authentication during UIA operations (password change, account deactivation, etc.). In Capacitor, the Browser plugin opens a separate process, and the `postMessage` callback may not reach the WebView, causing the UIA flow to hang.
|
||||||
|
|
||||||
|
**Impact**: Only affects users whose homeserver requires SSO for UIA (not password). Vojo users authenticate via password, so UIA also uses the password flow. Risk is low for the current user base.
|
||||||
|
|
||||||
|
**Workaround**: None needed for password-authenticated users.
|
||||||
|
|
||||||
|
**Fix options**: Remove `AuthType.Sso` from `SUPPORTED_IN_APP_UIA_STAGES` in `ActionUIA.tsx`, or rewrite the SSO callback to use a Capacitor App URL listener instead of `postMessage`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Resolved
|
||||||
|
|
||||||
|
_(none yet)_
|
||||||
72
docs/ai/i18n.md
Normal file
72
docs/ai/i18n.md
Normal file
|
|
@ -0,0 +1,72 @@
|
||||||
|
# Localisation (i18n)
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
- **Config**: [`src/app/i18n.ts`](../../src/app/i18n.ts) — i18next + HTTP backend + language detector
|
||||||
|
- **Fallback language**: `ru`
|
||||||
|
- **Locale files**: [`public/locales/en.json`](../../public/locales/en.json), [`public/locales/ru.json`](../../public/locales/ru.json)
|
||||||
|
- **Namespaces** (top-level keys in the JSON files): `Organisms`, `Auth`, `Settings`, `Search`, `Home`, `Direct`, `Room`, `Inbox`, `Explore`, `Create`, `RoomSettings`
|
||||||
|
|
||||||
|
## Usage pattern
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useTranslation } from 'react-i18next';
|
||||||
|
|
||||||
|
const { t } = useTranslation();
|
||||||
|
return <Text>{t('RoomSettings.some_key')}</Text>;
|
||||||
|
```
|
||||||
|
|
||||||
|
Dynamic values:
|
||||||
|
```tsx
|
||||||
|
t('key', { count: 5 })
|
||||||
|
```
|
||||||
|
|
||||||
|
For the rare case where a translation contains HTML tags, use `dangerouslySetInnerHTML` (used sparingly, e.g. in `RoomAddress.tsx`).
|
||||||
|
|
||||||
|
## Conventions
|
||||||
|
|
||||||
|
- Every React component gets its own `useTranslation()` call — do not share `t` across components.
|
||||||
|
- Custom hooks with `useMemo` / `useCallback` must include `t` in their dependency array. This is what makes language switching actually re-render.
|
||||||
|
- Import order: `react-i18next` goes after framework imports (`react`, `folds`, `focus-trap-react`, …) and before local imports.
|
||||||
|
- After adding `useTranslation` inside a hook, always run `npm run lint` / check `exhaustive-deps` warnings.
|
||||||
|
|
||||||
|
## Russian translation quality standards
|
||||||
|
|
||||||
|
The developer reviews Russian translations as a native speaker would see them in UI context, and has specifically called out the following past failures:
|
||||||
|
|
||||||
|
- **Buttons are verbs, not nouns.** "Открыть" (not "Просмотр") for a View button. "Создать" (not "Создание"). Action labels in Russian must be infinitive or imperative verb forms.
|
||||||
|
- **Avoid calques from English.** "публичный каталог" sounds translated; "общий список" reads naturally. If a phrase feels like literal English in Cyrillic, rewrite it.
|
||||||
|
- **Kill ambiguous pronouns.** Passive constructions like "могут быть изменены" leave the reader asking *who/what is being changed*. Rewrite with an explicit subject.
|
||||||
|
- **Read it in context.** Translations are for UI, not documentation. Short, unambiguous, natural.
|
||||||
|
|
||||||
|
**Why this matters:** These came from real review corrections ("Просмотр" for a button, "Составить" for Compose, ambiguous `founders_desc`). The developer is Russian-native and will notice.
|
||||||
|
|
||||||
|
## Localisation progress
|
||||||
|
|
||||||
|
**Completed namespaces** (fully localised EN + RU):
|
||||||
|
|
||||||
|
- `Auth` — Login, register, password reset
|
||||||
|
- `Settings` — All user-settings sections
|
||||||
|
- `Search` — Global search
|
||||||
|
- `Home` — Home timeline
|
||||||
|
- `Direct` — DM list
|
||||||
|
- `Room` — Room UI
|
||||||
|
- `Inbox` — Notifications & invites
|
||||||
|
- `Explore` — Public rooms
|
||||||
|
- `Create` — Room/space creation
|
||||||
|
- `RoomSettings` — Room settings (general, members, permissions, emojis/stickers, developer tools, image pack editor, power level tags)
|
||||||
|
- `Organisms` — Complex UI pieces
|
||||||
|
|
||||||
|
**Still to localise** (snapshot taken 2026-04-14 — verify before acting):
|
||||||
|
|
||||||
|
- Room features: `MessageEditor`, `MembersDrawer`, `RoomTombstone`
|
||||||
|
- Lobby: `Lobby.tsx`, `RoomItem.tsx`
|
||||||
|
- `AddExisting` feature
|
||||||
|
- System pages: `ConfigConfig`, `FeatureCheck`, `SpecVersions`, `WelcomePage`, `ClientRoot`
|
||||||
|
- Auth: `OrDivider`
|
||||||
|
- Dialogs: `LogoutDialog`, `ManualVerification`, `BackupRestore`
|
||||||
|
- UIA stages: `ReCaptchaStage`, `EmailStage`, `RegistrationTokenStage`
|
||||||
|
- Components: `TimePicker`, `DatePicker`, `ImageViewer`, `PdfViewer`, `UploadCard`, `UserModeration`
|
||||||
|
- Various `aria-label` attributes throughout
|
||||||
|
|
||||||
|
When the developer asks to localise a new area, check this list first and update it after finishing.
|
||||||
50
docs/ai/overview.md
Normal file
50
docs/ai/overview.md
Normal file
|
|
@ -0,0 +1,50 @@
|
||||||
|
# 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**: Yandex Cloud VPS, Ubuntu 24.04
|
||||||
|
- **Homeserver**: Synapse (Matrix) + PostgreSQL + Caddy (reverse proxy)
|
||||||
|
- **Bridges**: mautrix-telegram v0.15.3 (Python, SOCKS5 proxy for Telegram)
|
||||||
|
- **Client**: this repo — deployed as static files via Caddy
|
||||||
|
|
||||||
|
Client source on server: `~/vojo/cinny/`. Caddy serves it at `https://vojo.chat` (via `/var/www/cinny` symlink to `~/vojo/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
|
||||||
|
scp -r dist/* vojo-superuser@111.88.146.156:~/vojo/cinny/
|
||||||
|
```
|
||||||
|
|
||||||
|
VSCode task `Deploy to vojo.chat` (Ctrl+Shift+D) automates this. 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/)
|
||||||
Loading…
Add table
Reference in a new issue