git.iko.soy/parseable-android
on 63ee88d help sign in
parseable-android/CLAUDE.md
82 lines 3.8 kB history raw
1# CLAUDE.md
3## Project Overview
5Android client for [Parseable](https://www.parseable.com/), an open-source log analytics platform. The app connects to a Parseable server instance and lets users browse, search, filter, and live-tail log data.
7## Build & Test
9```bash
10./gradlew assembleDebug # Build debug APK
11./gradlew assembleRelease # Build release APK (minified)
12./gradlew testDebugUnitTest # Run unit tests
13./gradlew lintDebug # Run Android lint
14```
16Requires JDK 17 and the Android SDK (compileSdk 35, minSdk 26).
18## Architecture
20Single-module Android app (`app/`) using MVVM with Jetpack Compose.
22### Layers
24- **`data/api/`** — `ParseableApiClient`: OkHttp-based REST client wrapping all Parseable API endpoints. Uses Basic Auth. Returns `ApiResult<T>` (sealed class: `Success`/`Error`).
25- **`data/model/`** — Kotlinx Serialization data classes for API request/response types (`LogStream`, `StreamStats`, `StreamSchema`, `Alert`, `QueryRequest`, etc.).
26- **`data/repository/`** — `ParseableRepository` (domain facade over the API client) and `SettingsRepository` (DataStore-backed credential persistence).
27- **`di/`** — Hilt DI module. All singletons are constructor-injected.
28- **`ui/screens/`** — One package per screen, each containing a `*Screen.kt` (Composable) and `*ViewModel.kt` (Hilt ViewModel with `StateFlow`).
29- **`ui/navigation/`** — `NavGraph.kt` defines all routes. Navigation uses string-based routes with `{streamName}` path params.
30- **`ui/theme/`** — Material 3 theme with Parseable brand colors (purple `#545BEB`). Supports dark/light.
32### Screen Map
34| Route | Screen | ViewModel |
35|---|---|---|
36| `login` | `LoginScreen` | `LoginViewModel` |
37| `streams` | `StreamsScreen` | `StreamsViewModel` |
38| `log_viewer/{streamName}` | `LogViewerScreen` | `LogViewerViewModel` |
39| `stream_info/{streamName}` | `StreamInfoScreen` | `StreamInfoViewModel` |
40| `alerts` | `AlertsScreen` | `AlertsViewModel` |
41| `settings` | `SettingsScreen` | `SettingsViewModel` |
43### Parseable API Endpoints Used
45All endpoints are under `/api/v1/`. Auth is Basic Auth via `Authorization` header.
47- `GET /liveness` — connection test
48- `GET /about` — server version/mode info
49- `GET /logstream` — list all streams
50- `GET /logstream/{name}/schema` — stream field schema
51- `GET /logstream/{name}/stats` — ingestion/storage stats
52- `GET /logstream/{name}/info` — stream metadata
53- `GET /logstream/{name}/retention` — retention config
54- `DELETE /logstream/{name}` — delete stream
55- `POST /query` — SQL log queries (body: `{query, startTime, endTime}`)
56- `GET /alerts` — list alerts
57- `GET /user` — list users
59API docs: https://www.parseable.com/docs/api
61### Key Dependencies
63- Jetpack Compose with Material 3 (BOM 2024.12.01)
64- Hilt 2.53.1 (DI via KSP)
65- OkHttp 4.12.0
66- Kotlinx Serialization 1.7.3
67- Navigation Compose 2.8.5
68- DataStore Preferences 1.1.1
70## Code Conventions
72- Kotlin with Jetpack Compose — no XML layouts
73- State is exposed as `StateFlow` from ViewModels, collected via `collectAsStateWithLifecycle()`
74- API responses use `ApiResult<T>` sealed class — always handle both `Success` and `Error` branches
75- Network calls use `Dispatchers.IO` via `withContext` inside the API client
76- Parseable queries use PostgreSQL-compatible SQL; column names are double-quoted in generated SQL
77- Cleartext HTTP is allowed via `network_security_config.xml` (many Parseable instances are self-hosted without TLS)
79## CI/CD
81- **`.github/workflows/ci.yml`** — Runs on PRs and pushes to main/master. Builds debug APK, runs tests and lint.
82- **`.github/workflows/build-release.yml`** — Runs on `v*` tags. Builds debug+release APKs and creates a draft GitHub release.