# 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)

## 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
└── 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.

## 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 |

## Known limitations

- No E2E encryption (plain-text transport only; suitable for unencrypted rooms)
- No push notifications
- No media/file messages (text only)
- Room list is not paginated (loads whatever `/sync` returns on first sync)