mirror of
https://github.com/pawelorzech/Swoosh.git
synced 2026-03-31 20:15:41 +00:00
74f42fd2f1
Add professional open-source scaffolding: - README.md with badges, features, architecture, and setup guide - LICENSE (PolyForm Noncommercial 1.0.0) - CONTRIBUTING.md with guidelines - CHANGELOG.md for v1.0.0 - GitHub issue and PR templates - Updated .gitignore
119 lines
4.4 KiB
Markdown
119 lines
4.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
|
|
- **Image uploads** — Attach photos from your gallery or camera
|
|
- **Link previews** — Automatic Open Graph metadata extraction (title, description, thumbnail)
|
|
- **Scheduled publishing** — Set a future publish date for your posts
|
|
- **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** — Clean, modern interface built entirely with Jetpack Compose
|
|
|
|
## 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)
|
|
│ └── repository/ # PostRepository, OpenGraphFetcher
|
|
├── ui/
|
|
│ ├── feed/ # Post list with pull-to-refresh
|
|
│ ├── composer/ # Post creation and editing
|
|
│ ├── detail/ # Full post view
|
|
│ ├── setup/ # Initial configuration wizard
|
|
│ ├── settings/ # App settings and logout
|
|
│ ├── navigation/ # Compose Navigation graph
|
|
│ └── theme/ # Material 3 theming
|
|
└── 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.
|
|
|
|
## 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
|
|
```
|
|
|
|
Test coverage includes JWT generation, mobiledoc building, URL normalization, data model serialization, auth interceptors, and time formatting.
|
|
|
|
## 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)
|