mirror of
https://github.com/pawelorzech/Swoosh.git
synced 2026-03-31 20:15:41 +00:00
0891013df6
Add multi-account, stats dashboard, search/filtering, animations, theme system, and expanded architecture documentation.
129 lines
5.4 KiB
Markdown
129 lines
5.4 KiB
Markdown
# Swoosh
|
|
|
|
A native Android microblogging client for [Ghost CMS](https://ghost.org). Write, publish, and manage short-form posts from your phone — with offline support, image uploads, link previews, and scheduled publishing.
|
|
|
|
[](https://developer.android.com)
|
|
[](https://kotlinlang.org)
|
|
[](https://developer.android.com/jetpack/compose)
|
|
[](LICENSE)
|
|
|
|
## Features
|
|
|
|
- **Ghost Admin API** — Full integration via JWT authentication (HS256)
|
|
- **Offline-first** — Posts are saved locally and synced when connectivity returns
|
|
- **Multi-account** — Connect up to 5 Ghost blogs and switch between them
|
|
- **Image uploads** — Attach photos from your gallery or camera
|
|
- **Link previews** — Automatic Open Graph metadata extraction (title, description, thumbnail)
|
|
- **Hashtag support** — Auto-extracted hashtags converted to Ghost tags
|
|
- **Scheduled publishing** — Set a future publish date for your posts
|
|
- **Statistics dashboard** — Post counts, word counts, reading time, and more with animated counters
|
|
- **Search & filtering** — Filter by status (Published, Draft, Scheduled) and sort by date
|
|
- **Mobiledoc format** — Native Ghost content format with text paragraphs and bookmark cards
|
|
- **Encrypted credentials** — API keys stored with AES-256-GCM via AndroidX Security
|
|
- **Background sync** — WorkManager handles upload queue with exponential backoff
|
|
- **Material 3 UI** — Bluesky-inspired feed design with polished animations and Light/Dark/System themes
|
|
|
|
## Screenshots
|
|
|
|
> Coming soon — contributions welcome!
|
|
|
|
## Architecture
|
|
|
|
MVVM with Repository pattern, single-module Gradle project.
|
|
|
|
```
|
|
com.swoosh.microblog/
|
|
├── data/
|
|
│ ├── api/ # Retrofit client, JWT auth, interceptors
|
|
│ ├── db/ # Room database, DAOs, type converters
|
|
│ ├── model/ # GhostPost (API), LocalPost (DB), FeedPost (UI), PostStats, GhostAccount
|
|
│ └── repository/ # PostRepository, OpenGraphFetcher
|
|
├── ui/
|
|
│ ├── animation/ # SwooshMotion shared animation specs
|
|
│ ├── components/ # Reusable composables (dialogs, placeholders)
|
|
│ ├── feed/ # Post feed with search and filtering
|
|
│ ├── composer/ # Post creation with images, links, hashtags, scheduling
|
|
│ ├── detail/ # Full post view
|
|
│ ├── preview/ # HTML post preview
|
|
│ ├── stats/ # Statistics dashboard
|
|
│ ├── setup/ # Configuration wizard and add-account flow
|
|
│ ├── settings/ # App settings, account management, theme toggle
|
|
│ ├── navigation/ # Compose Navigation with bottom nav bar
|
|
│ └── theme/ # Material 3 theming (Light/Dark/System)
|
|
└── worker/ # PostUploadWorker (WorkManager)
|
|
```
|
|
|
|
**Data flow:** Compose UI → ViewModel → Repository → Room (local) + Retrofit (remote). Posts are persisted to Room first, then queued for upload via WorkManager.
|
|
|
|
**Navigation:** Bottom bar with three tabs (Feed, Stats, Settings). Composer and Detail screens slide in as overlays.
|
|
|
|
## Getting started
|
|
|
|
### Prerequisites
|
|
|
|
- Android Studio Hedgehog (2023.1.1) or later
|
|
- JDK 17
|
|
- Android SDK 34
|
|
- A [Ghost](https://ghost.org) blog with Admin API access
|
|
|
|
### Ghost setup
|
|
|
|
1. In your Ghost admin panel, go to **Settings → Integrations**
|
|
2. Create a new **Custom Integration**
|
|
3. Copy the **Admin API Key** (format: `id:secret`)
|
|
4. Note your Ghost blog URL (e.g. `https://yourblog.com`)
|
|
|
|
### Build and run
|
|
|
|
```bash
|
|
git clone https://github.com/pawelorzech/Swoosh.git
|
|
cd Swoosh
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
Install the debug APK on your device or emulator, then follow the setup wizard to connect your Ghost blog.
|
|
|
|
## Building
|
|
|
|
```bash
|
|
./gradlew assembleDebug # Debug APK
|
|
./gradlew assembleRelease # Release APK (ProGuard enabled)
|
|
```
|
|
|
|
## Testing
|
|
|
|
The project includes unit tests with JUnit 4 and Robolectric:
|
|
|
|
```bash
|
|
./gradlew test # Run all tests
|
|
./gradlew app:testDebugUnitTest # Debug variant only
|
|
```
|
|
|
|
24 test classes covering JWT generation, mobiledoc building, URL normalization, data model serialization, auth interceptors, time formatting, hashtag parsing, account management, feed preferences, and theme modes.
|
|
|
|
## Tech stack
|
|
|
|
| Layer | Technology |
|
|
|-------|-----------|
|
|
| UI | Jetpack Compose, Material 3 |
|
|
| Navigation | Compose Navigation |
|
|
| Architecture | MVVM, StateFlow, Repository pattern |
|
|
| Networking | Retrofit 2, OkHttp 4 |
|
|
| Images | Coil |
|
|
| Database | Room |
|
|
| Background | WorkManager |
|
|
| Auth | JJWT (HS256), EncryptedSharedPreferences |
|
|
| Link parsing | Jsoup |
|
|
| Testing | JUnit 4, Robolectric, MockWebServer |
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
|
|
## License
|
|
|
|
This project is licensed under the [PolyForm Noncommercial License 1.0.0](LICENSE) — you can use, modify, and share it for any non-commercial purpose. Commercial use requires permission from the author.
|
|
|
|
## Author
|
|
|
|
**Paweł Orzech** — [pawelorzech.pl](https://pawelorzech.pl)
|