FediSuite Android App

Mobile client for FediSuite, the Fediverse management platform.

FediSuite helps users manage multiple Fediverse accounts in one place, including:

• posting and scheduling
• queue and post management
• account analytics and insights
• account connection and status monitoring
• mobile-friendly access to the FediSuite workflow

Project website: https://www.fedisuite.com
Official hosted instance: https://app.fedisuite.com

What Users Should Use

FediSuite currently has several important public URLs with different purposes.

• Project website / landing page: https://www.fedisuite.com
• Official hosted app instance: https://app.fedisuite.com
• Android app repository: https://forge.chrislo.de/FediSuite/FediSuite-Android-App
• Self-hosting repository: https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting
• Plugin repository for optional extensions: https://forge.chrislo.de/FediSuite/FediSuite-Plugins-Repository
• Main source/build repository for the full application stack: https://forge.chrislo.de/FediSuite/FediSuite-Docker-Image

In short:

• If you want to use the hosted service, start at https://app.fedisuite.com.
• If you want to self-host FediSuite, use the FediSuite repository.
• If you want optional plugins for a self-hosted installation, use the FediSuite-Plugins repository.
• If you want to work on the Android client itself, use this repository.
• If you want to work on the web app, API or Docker image build, use the FediSuite-Docker-Image repository.

What FediSuite Is

FediSuite is an all-in-one management platform for the Fediverse. It is designed to work with platforms such as:

• Mastodon
• Pixelfed
• Friendica
• Misskey and related forks
• PeerTube
• Loops
• additional compatible Fediverse platforms

The core idea is to give users one central management hub for posting, planning, analytics and account administration across different Fediverse services.

This repository contains the Android app for that ecosystem.

What This Repository Contains

This repository contains the source code for the mobile app built with:

• Expo
• React Native
• TypeScript
• React Navigation
• TanStack Query
• Zustand

It is a real mobile application, not:

• a WebView wrapper
• a responsive shell around the desktop frontend
• a copy of the desktop layout squeezed onto a phone

The app is mobile-first and touch-first.

Important Product Model

The app always connects to a specific FediSuite instance URL selected by the user.

That means:

• the user starts with instance selection
• all API requests are scoped to that chosen instance
• tokens, caches and sessions are bound to that instance
• the app works with the official hosted instance and with self-hosted instances

Important clarification:

• https://app.fedisuite.com is the official public FediSuite instance
• self-hosted FediSuite instances are also supported
• the app must still not hardcode one backend internally

Current Feature Set

Implemented in the current app:

• instance URL input and validation, recent-instance persistence
• login against the chosen instance, including two-factor codes
• secure JWT storage via SecureStore, one key per exact instance URL
• session restore, expiry detection and sign-out that also ends the session on the server
• bootstrap dashboard via /api/mobile/bootstrap
• account analytics via /api/mobile/accounts/{id}/dashboard
• reach view (net and gross reach, trend, top posts) via the reach-* routes of FediSuite 2.0
• posts list with real counts per status, drafts, retry of failed posts and delivery status after publishing
• composer with media, alt text, native date and time pickers, drafts (also reopening drafts from the web) and a choice of text format (plain text, Markdown or HTML) where the platform supports it, with coloured hashtags, mentions and links
• content calendar (month or week, filters, moving, publishing, withdrawing, copying and deleting posts) on instances that enable it
• connected accounts overview and account disconnect
• settings (language, theme), mobile preferences and admin-tab gating
• app languages: German, English, French, Spanish and Italian

Reach, the calendar and drafts need a FediSuite 2.0 instance. The text format needs a server that supports it (FediSuite 2.0.2 or newer). Older instances keep working for the basics.

Mobile UX Principles

This app is intentionally designed as a native-feeling mobile client.

Key UI principles:

• bottom tab navigation
• large touch targets
• card-based screens
• dark-mode-first visual language
• compact but readable analytics
• explicit loading, error and empty states

Repository Structure

src/
  api/
  components/
  core/
  hooks/
  navigation/
  screens/
    accounts/
    admin/
    auth/
    composer/
    dashboard/
    instance/
    queue/
    settings/
  store/
  theme/
  utils/

Important files:

• App.tsx
• app.config.js
• app.json
• android/app/build.gradle
• AGENTS.md

Architecture Overview

Instance Layer

Responsible for:

• instance URL entry
• normalization
• validation
• persistence of active and recent instances

Auth Layer

Responsible for:

• login
• token storage
• logout
• session restore
• auth failure recovery

API Layer

Responsible for:

• typed HTTP requests
• bearer-token injection
• Accept-Language injection
• central error parsing
• instance-scoped request handling

Feature Layer

Responsible for:

• dashboard
• analytics
• queue
• composer
• accounts
• settings
• admin-aware behavior

UI Layer

Responsible for:

• navigation
• screen composition
• reusable mobile components
• visual states and touch-first interactions

Important API Endpoints

Pre-login:

• GET /api/health
• GET /api/public/config
• GET /api/public/notice

Authentication:

• POST /api/auth/login

Preferred mobile bundle endpoints:

• GET /api/mobile/bootstrap
• GET /api/mobile/accounts/{id}/dashboard
• PUT /api/mobile/preferences

Post and account management:

• GET /api/posts
• POST /api/posts
• POST /api/posts/publish-now
• PUT /api/posts/{id}
• DELETE /api/posts/{id}
• POST /api/posts/{id}/publish
• GET /api/posts/calendar
• POST /api/posts/drafts
• GET /api/accounts
• DELETE /api/accounts/{id}

Important Implementation Rules

These rules should not be broken lightly:

1. Do not remove the instance-selection flow.
2. Do not hardcode one backend into the app.
3. Do not store JWTs in plain AsyncStorage.
4. Do not bypass the typed API layer from screens.
5. Do not turn this app into a WebView or desktop clone.
6. Prefer the mobile bundle endpoints over older fragmented analytics calls.
7. Keep instance data isolated from each other.

Development

Requirements

• Node.js
• npm
• OpenJDK 17
• Android SDK
• adb for device installation

Install dependencies

npm install

Start Expo development server

npm run start

Typecheck

npm run typecheck

Export Android bundle

npx expo export --platform android

Build release APK

cd android
./gradlew assembleRelease

Versioning

The app reads its version from the plain-text file version.

That version is used for:

• Expo app version
• Android versionName
• release APK filename
• visible version footer inside the app

Example output:

android/app/build/outputs/apk/release/org.fedisuite.mobile-<version>.apk

Installing on a Device

Example:

adb install -r /absolute/path/to/android/app/build/outputs/apk/release/org.fedisuite.mobile-<version>.apk

-r replaces the existing installation while preserving app data as long as package id and signing key remain compatible.

Branding

The Android launcher icon and related assets are derived from the official FediSuite logo in this repository.

If branding changes, update both:

• Expo asset files under assets/
• native Android launcher assets under android/app/src/main/res/

The branding, screenshots and store graphics shipped in this repository are documented in ASSET_LICENSES.md.

Release Versioning

The canonical app version is stored in the plain-text file version.

Android and F-Droid builds derive the numeric versionCode directly from that semantic version using this formula:

MAJOR * 10000 + MINOR * 100 + PATCH

Examples:

• 0.9.12 -> 912
• 1.2.3 -> 10203

This keeps release tags, Fastlane changelogs and Android upgrade paths aligned.

Related FediSuite URLs

• Website: https://www.fedisuite.com
• Hosted app instance: https://app.fedisuite.com
• Android app repository: https://forge.chrislo.de/FediSuite/FediSuite-Android-App
• Self-hosting repository: https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting
• Main source/build repository for the full application stack: https://forge.chrislo.de/FediSuite/FediSuite-Docker-Image

F-Droid

Vorbereitete Dateien fuer die Einreichung in das offizielle F-Droid-Repository:

• repo-lokale Build-Metadaten: .fdroid.yml
• konkrete fdroiddata-Vorlage: fdroiddata/org.fedisuite.mobile.yml
• Ablaufbeschreibung: docs/fdroid-submission.md

Die F-Droid-Build-Metadaten beruecksichtigen bereits, dass dieses Expo-/React-Native-Projekt auf dem Builder npm benoetigt und vor dem Gradle-Build ein npm ci im Repo-Root ausgefuehrt werden muss.

Notes

• The app is close to production shape, but parts of the backend may still evolve.
• Some mobile analytics behavior depends on server-side endpoint quality.
• When in doubt, verify against the official hosted instance.

License

FediSuite is licensed under the GNU GPL v3.0.