vojo/docs/ai/architecture.md

Architecture

Quick Start

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

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)