Ferrum

An offline-first Flutter app for workouts, plans, progress, social challenges, and AI-assisted coaching.

GitHub repository · Architecture docs · API contracts

Status: Repository access may be required. No working public demo is available; the listed Play Store and deep-link URLs are inactive.

System architecture

flowchart LR
    UI[Flutter features] --> RP[Riverpod controllers]
    RP --> REPO[Repositories]
    REPO --> DB[(Drift and SQLite)]
    RP --> SYNC[Sync engine]
    SYNC --> API[Authenticated API client]
    API --> B[External Ferrum API]
    UI --> AI[AI feature gateway]
    AI --> API
    APP[App startup] --> F[Firebase and Sentry]
    RP --> AN[Analytics]
    AN --> F
    AN --> P[PostHog]

The backend is not part of this repository; the review covers the mobile app and its API contracts.

Data flow

1. Workout and plan changes are saved locally, so core features work offline.
2. The sync engine checks for local changes and uploads sessions in groups of up to 200.
3. Server updates are applied locally, and completed uploads are marked as synced or deleted.
4. The API client adds version headers and login tokens, refreshes expired sessions once, then retries the request.

Engineering highlights and trade-offs

• Offline-first design: Local SQLite keeps workouts available without a connection, but requires careful conflict and sync handling.
• Resumable sync: Chunked uploads and saved cursors allow later sync runs to continue after failure.
• One network layer: Authentication, uploads, timeouts, token refresh, and errors are handled in one client.
• Central AI gateway: Features request AI tasks through one service, keeping model details out of the interface.
• Safe analytics: Firebase, PostHog, and backend events run independently, so analytics failures do not block the app. Unsaved in-memory events can be lost when the app closes.