Initial commit

README.md

@@ -0,0 +1,125 @@
+# 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`.
+
+## 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)