98 lines
4.5 KiB
Markdown
98 lines
4.5 KiB
Markdown
# Fabled — Android App
|
|
|
|
Native Android client for FabledAssistant, a self-hosted AI second-brain and productivity assistant.
|
|
|
|
## Features
|
|
|
|
- **Daily Briefing** — the primary screen; opens on launch. Shows your AI-compiled morning digest (tasks, calendar, weather, RSS) with a full conversation you can reply to inline. Refresh manually or browse past briefings from the overflow menu.
|
|
- **Quick Capture** — always-visible input bar above all tabs. Type a note or task and submit; multiple captures queue sequentially so the input is never blocked. Falls back to offline persistence when the server is unreachable.
|
|
- **Library** — unified browsable list of notes, tasks, and projects with filter pills (All · Notes · Tasks · Projects). Tasks have a secondary status sub-filter and a tappable status icon to cycle todo → in progress → done without opening the editor. Inline search filters results live.
|
|
- **Chat** — streaming AI conversations with real-time SSE display. Tap + to start a new conversation or open an existing one.
|
|
- **Note & task editing** — full Markdown editor for notes, task editor with due date, priority, project, and milestone assignment.
|
|
- **OAuth / SSO** — authenticates via your server's OIDC provider; local username/password login also supported if enabled server-side.
|
|
- **Session persistence** — stays logged in across restarts via a persistent cookie jar.
|
|
- **Auto-update** — checks your Forgejo releases on launch and prompts to download and install new APKs in-app.
|
|
|
|
## Requirements
|
|
|
|
- A running FabledAssistant server (self-hosted)
|
|
- Android 5.0+ (API 21)
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Flutter 3.x SDK
|
|
- Android Studio (for Android SDK and emulator)
|
|
- JDK 17
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
flutter pub get
|
|
flutter run
|
|
```
|
|
|
|
On first launch, enter your FabledAssistant server URL (e.g. `https://fabled.example.com`) and sign in.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
lib/
|
|
├── main.dart # Entry point; resolves async deps before runApp
|
|
├── app.dart # GoRouter + auth redirect guards + 3-tab shell
|
|
├── core/
|
|
│ ├── constants.dart # Route name constants
|
|
│ ├── exceptions.dart # AppException hierarchy
|
|
│ └── theme.dart # Custom slate-indigo ColorScheme + Fraunces typography
|
|
├── data/
|
|
│ ├── api/ # Dio HTTP layer (one class per resource)
|
|
│ ├── models/ # Plain Dart models with fromJson/toJson
|
|
│ └── repositories/ # Thin wrappers over API classes
|
|
├── providers/ # Riverpod providers (state + dependency wiring)
|
|
│ ├── briefing_provider.dart # Today's briefing — optimistic UI, SSE, polling
|
|
│ └── capture_work_queue_provider.dart # Sequential in-memory capture queue
|
|
├── screens/
|
|
│ ├── briefing/ # BriefingScreen + BriefingHistoryScreen
|
|
│ ├── library/ # LibraryScreen (unified notes/tasks/projects)
|
|
│ ├── chat/ # ConversationsTabScreen + ChatScreen
|
|
│ ├── notes/ # NoteDetailScreen + NoteEditScreen
|
|
│ ├── tasks/ # TaskEditScreen
|
|
│ └── settings/ auth/ setup/ splash/
|
|
└── widgets/
|
|
├── chat_message_bubble.dart # Shared bubble (used by Chat + Briefing)
|
|
├── briefing_digest_card.dart # Expandable first-message card
|
|
└── library_item_card.dart # Note / task / project row widgets
|
|
```
|
|
|
|
**Key packages:** `flutter_riverpod`, `go_router`, `dio` + `cookie_jar`, `google_fonts`, `flutter_markdown_plus`
|
|
|
|
## Building a Release APK
|
|
|
|
```bash
|
|
flutter build apk --release
|
|
```
|
|
|
|
The APK will be at `build/app/outputs/flutter-apk/app-release.apk`.
|
|
|
|
## CI / CD
|
|
|
|
CI and build are defined in a single workflow (`.forgejo/workflows/ci.yml`) running on the shared `py3.12-node22` act runner with the `ghcr.io/cirruslabs/flutter:stable` container.
|
|
|
|
| Trigger | Analyze + Test | Build APK | Release |
|
|
|---------|---------------|-----------|---------|
|
|
| PR | ✓ | — | — |
|
|
| Push `dev` | ✓ | ✓ (artifact `fabledapp-dev-<sha>`) | — |
|
|
| Push `main` | ✓ | — | — |
|
|
| Tag `v*` | ✓ | ✓ (artifact `fabledapp-<sha>`) | ✓ Forgejo Release + APK attached |
|
|
|
|
The build job has `needs: [analyze]` — a failed analyze or test blocks the APK build.
|
|
|
|
To cut a release:
|
|
|
|
```bash
|
|
git tag v26.03.11 && git push origin v26.03.11
|
|
```
|
|
|
|
Requires a `RELEASE_TOKEN` secret (Forgejo PAT with `write:repository` scope) set in repo Settings → Secrets → Actions.
|