Max Litruv Boonzaayer
e058165830
Bump Vite 8, matrix-js-sdk, and related deps; fix immer/vanilla-extract imports for new majors. Replace blocking sync error dialog with background recovery on wake/offline, and disable Vite auto-open in dev. Add feature handoff documentation index.
94 lines
2.9 KiB
Markdown
94 lines
2.9 KiB
Markdown
# Matrix client — handoff
|
|
|
|
## Summary
|
|
|
|
The Matrix client layer wraps `matrix-js-sdk`: client creation, IndexedDB crypto/sync stores, start/stop sync, logout, and React context providers. `ClientRoot` is the authenticated app bootstrapper.
|
|
|
|
## User-facing behavior
|
|
|
|
- Splash screen ("Heating up") while client initializes
|
|
- Sync status reflected in UI (`SyncStatus`, splash)
|
|
- Logout from settings or forced server logout
|
|
- Mobile: visibility-based sync restart
|
|
|
|
## Architecture
|
|
|
|
```
|
|
ClientRoot.tsx
|
|
→ getCurrentSession() → initClient(session)
|
|
→ startClient(mx)
|
|
→ Providers: MatrixClient, Capabilities, MediaConfig, Call, PluginLoader
|
|
initMatrix.ts
|
|
→ createClient + IndexedDBStore + IndexedDBCryptoStore
|
|
→ secretStorageKeys / cryptoCallbacks
|
|
```
|
|
|
|
## Key files
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `cinny/src/client/initMatrix.ts` | createClient, start/stop, logout, cache clear |
|
|
| `cinny/src/client/secretStorageKeys.ts` | SSSS / secret storage callbacks |
|
|
| `cinny/src/app/pages/client/ClientRoot.tsx` | Bootstrap, providers, title bar |
|
|
| `cinny/src/app/hooks/useMatrixClient.ts` | React context for `MatrixClient` |
|
|
| `cinny/src/app/hooks/useSyncState.ts` | Sync state subscription |
|
|
| `cinny/src/app/pages/client/SyncStatus.tsx` | Sync indicator UI |
|
|
| `cinny/src/app/components/splash-screen/SplashScreen.tsx` | Loading shell |
|
|
|
|
## Data model
|
|
|
|
| Store | Backend | Purpose |
|
|
|-------|---------|---------|
|
|
| IndexedDB sync store | matrix-js-sdk | Room timeline cache |
|
|
| IndexedDB crypto store | matrix-js-sdk | Olm/Megolm keys |
|
|
| Session | localStorage | Auth credentials |
|
|
|
|
## Dependencies
|
|
|
|
- `matrix-js-sdk`
|
|
- IndexedDB (browser/Electron)
|
|
|
|
## Integration points
|
|
|
|
- **authentication**: session → initClient
|
|
- **state-management**: sync events feed atoms
|
|
- **background-notifications**: pushers registered after sync
|
|
- **e2e-and-devices**: crypto store, verification
|
|
- **plugins**: Matrix client exposed to plugin API
|
|
|
|
## Testing
|
|
|
|
### Manual
|
|
|
|
1. Fresh login; verify sync completes (timeline loads).
|
|
2. Reload app; session restores without re-login.
|
|
3. Logout; IndexedDB cleared appropriately.
|
|
4. Airplane mode → sync error → recovery on reconnect.
|
|
|
|
### Automated
|
|
|
|
- None
|
|
|
|
## Known issues & gotchas
|
|
|
|
- `handlingKeyConflict` flag in initMatrix for crypto key conflicts
|
|
- `deleteAllMatrixDatabases` on certain logout/clear paths — destructive
|
|
- Mobile `useVisibilitySync` restarts sync on app resume (Tauri)
|
|
- `clearCacheAndReload` utility for support scenarios
|
|
|
|
## Future work
|
|
|
|
- Lazy sync / sliding sync if migrating MSC
|
|
- Better sync error UX with retry backoff
|
|
|
|
## Related docs
|
|
|
|
- [authentication HANDOFF](../authentication/HANDOFF.md)
|
|
- [state-management HANDOFF](../state-management/HANDOFF.md)
|
|
- [e2e-and-devices HANDOFF](../e2e-and-devices/HANDOFF.md)
|
|
|
|
## Add your extra things here
|
|
|
|
- `logoutClient`, `clearLoginData`, `clearCacheAndReload` exported from initMatrix.ts
|
|
- `HttpApiEvent.SessionLoggedOut` listener in ClientRoot clears everything
|