# 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