matrix-android/README.md

# matrix-android

A minimal Android Matrix chat client with a terminal aesthetic — dark background, green monospace text, `<` / `>` message prefixes — inspired by the [matrix-message](../matrix-message) living-room terminal app.

## Features

- Browser-based SSO login (Custom Tabs — no password stored by the app)
- Password login fallback
- Room list after login
- Text-only chat (no images, no avatars)
- Real-time sync via Matrix `/sync` long-polling
- Persistent session (survives app restart)
- End-to-end encryption (E2EE) via libolm / Megolm
- SAS device verification
- Push notifications (foreground via sync loop; background via FCM + Cloudflare Worker)

## Download

Pre-built APKs are available on the [releases page](https://git.tadix.dev/ltadeu6/matrix-android/releases).

## Screenshots / UI description

```
> MATRIX LOGIN          (login screen)
────────────────────────
homeserver: matrix.org
[ LOGIN WITH BROWSER (SSO) ]
──── or password login ────
username: @user:matrix.org
password: ••••••••
[ LOGIN ]

> ROOMS                 (room list)
────────────────────────────────────────
> My Room
  !abc123:matrix.org
> Family chat
  !xyz456:example.com
[logout]

< back          My Room (chat screen)
──────────────────────────────────────
< alice
  hello!
                         > hey there >
< alice
  how are you?
──────────────────────────────────────
> message...
```

## Requirements

- Android Studio Ladybug (2024.2) or later
- Android SDK 35
- minSdk 26 (Android 8.0)

## Build

1. Clone the repo
2. Open the `matrix-android/` folder in Android Studio
3. Let Gradle sync (it downloads all dependencies automatically)
4. Run on a device or emulator

If you prefer the command line, first generate the Gradle wrapper:

```bash
cd matrix-android
gradle wrapper --gradle-version 8.9
./gradlew assembleDebug
```

The APK is at `app/build/outputs/apk/debug/app-debug.apk`.

### NixOS / CLI build

This repo includes a `flake.nix` dev shell with:

- JDK 17
- Gradle
- Android SDK 35 + Build Tools 35.0.0

Enter the shell and build:

```bash
cd matrix-android
nix develop
gradle wrapper --gradle-version 8.9
./gradlew assembleDebug
```

The shell exports `ANDROID_HOME` / `ANDROID_SDK_ROOT` and rewrites `local.properties` to the Nix SDK path so Gradle uses the packaged Android SDK instead of a user-specific installation.

## Login

### SSO (recommended)

1. Enter your homeserver (default: `matrix.org`)
2. Tap **LOGIN WITH BROWSER (SSO)**
3. A browser tab opens to the homeserver's login/SSO page
4. After authenticating, you are redirected back to the app automatically

The app registers the `matrixandroid://sso` URI scheme for this redirect.

### Password

Enter your full Matrix username (`@user:homeserver.tld`) and password directly.

## Architecture

```
app/src/main/java/com/ltadeu6/matrix/
├── MainActivity.kt              — single Activity; handles SSO deep link
├── navigation/
│   └── AppNavigation.kt         — Compose NavHost (Login → Rooms → Chat)
├── auth/
│   ├── LoginScreen.kt           — login UI
│   └── LoginViewModel.kt        — SSO URL builder, login calls
├── rooms/
│   └── RoomListScreen.kt        — joined rooms list
├── chat/
│   ├── ChatScreen.kt            — message list + input bar
│   └── ChatViewModel.kt         — sends messages, maps sync state
├── matrix/
│   ├── MatrixApi.kt             — Retrofit interface (Matrix REST v3)
│   ├── MatrixModels.kt          — serialization data classes + local models
│   ├── MatrixSession.kt         — singleton: auth, sync loop, state flows
│   ├── CryptoService.kt         — E2EE: Olm/Megolm, OTK management
│   ├── VerificationService.kt   — SAS device verification
│   ├── NotificationHelper.kt    — notification channel + posting
│   └── MatrixFirebaseMessagingService.kt — FCM push (app killed)
├── verification/
│   └── VerificationScreen.kt    — verification UI
└── ui/theme/
    └── Theme.kt                 — terminal color scheme (green on black)
```

**State flow**: `MatrixSession` owns a `syncState: StateFlow<SyncState>` that all screens observe. The background sync loop continuously updates it via `/sync` long-polling.

## Push notifications

When the app is in the foreground or background, notifications are fired directly from the sync loop. When the app is killed, push is delivered via FCM through a self-hosted Cloudflare Worker (`gateway/`) that acts as a Matrix push gateway.

## Dependencies

| Library | Purpose |
|---|---|
| Jetpack Compose + Material3 | UI |
| Navigation Compose | Screen routing |
| Retrofit 2 + OkHttp | Matrix HTTP API |
| kotlinx.serialization | JSON parsing |
| retrofit2-kotlinx-serialization-converter | Retrofit ↔ kotlinx bridge |
| kotlinx.coroutines | Async / sync loop |
| androidx.browser (Custom Tabs) | SSO browser login |
| libolm (native) | E2EE: Olm/Megolm encryption |
| Firebase Messaging | FCM push notifications |

## Known limitations

- No media/file messages (text only)
- Room list is not paginated (loads whatever `/sync` returns on first sync)