Live Web App · Live API · Main Repo · Android APK

Architecture · Product surfaces · Run the app · Validation & release · Documentation

---

TaskTrail Mobile is the Flutter companion to the TaskTrail web app. It is not a mock or a prototype — it runs against the same production backend at api.tasktrail.site, uses the same team and task model, and enforces the same auth and role rules. The mobile UI is built from scratch for touch; the rules come from the server.

How it fits

Surface	Link	Role
Web app	tasktrail.site	Reference product surface
Shared API	api.tasktrail.site	The exact backend both clients call
Main repo	cloud-computing-project	Backend, web, deployment, infra docs
Android release	TaskTrail-android-arm64-release.apk	Installable APK kept in-repo

Architecture

The mobile app follows a clean Widgets → Controllers → Repositories → ApiClient layering. Widgets stay presentational, controllers hold state, repositories own data access, and a single TaskTrailApiClient wraps dio so the base URL, headers, and session tokens live in one place. No business logic lives in widgets; the backend stays the source of truth.

Product flow

flowchart LR
Auth["Sign in / restore session"] --> Role{"Role-aware shell"}
Role --> Employee["Employee<br/>Tasks · Calendar · Teams · Join · Profile"]
Role --> Manager["Manager<br/>Dashboard · Tracker · Tasks · Teams · Profile"]
Employee --> Execute["Join teams · update work · complete tasks"]
Manager --> Oversight["Assign · manage teams · monitor execution"]

Loading

The shell reads the role off the authenticated user and switches between employee and manager tab sets. Both use the same session model and the same API contracts.

Product surfaces

Role	Mobile surfaces
Employee	Join · Tasks · Calendar · Teams · Profile
Manager	Dashboard · Worker Tracker · Tasks · Teams · Recurring · Profile

The UI uses bottom sheets, compact lists, and tab persistence instead of desktop-style pages.

Engineering profile

Concern	Choice
Framework	Flutter
Language	Dart 3
Navigation	go_router with role-aware shell routes
Networking	dio via a single TaskTrailApiClient
Secure persistence	flutter_secure_storage
UI direction	Calm, mobile-first, iOS-esque shell/theme
Validation	flutter test + integration_test + emulator runs

Repository layout

tasktrail-mobile/
├── lib/src/
│ ├── app/ # bootstrap + router
│ ├── core/ # config, API client, storage, theme, models
│ ├── features/ # auth, dashboard, tracker, tasks, teams, join, calendar, profile
│ └── shared/ # shell, tab bar, reusable mobile surfaces
├── test/ # unit + widget tests
├── integration_test/ # end-to-end mobile flows
├── apk/ # Android release artifact
├── docs/
│ ├── assets/ # README visuals
│ ├── README.md
│ └── ARCHITECTURE.md
├── android/ ios/
└── README.md

Run the app

Install dependencies

flutter pub get

Android emulator against local backend

flutter run -d emulator-5554 \
--dart-define=TASKTRAIL_ENV=development \
--dart-define=TASKTRAIL_API_BASE_URL=http://10.0.2.2:4000/api/v1

Android emulator against live backend

flutter run -d emulator-5554 \
--dart-define=TASKTRAIL_ENV=production

Environment defaults:

• development → http://10.0.2.2:4000/api/v1
• production → https://api.tasktrail.site/api/v1
• TASKTRAIL_API_BASE_URL overrides both

Validation & release

flutter analyze
flutter test

Release build:

flutter build apk --release --dart-define=TASKTRAIL_ENV=production

The latest Android artifact lives at apk/TaskTrail-android-arm64-release.apk. For proper long-term release signing, copy android/key.properties.example to android/key.properties and point it at a real keystore.

What is particularly strong here

• Same backend, same rules. No separate mock data path, no parallel product logic.
• Role-aware shell. Manager and employee flows feel different while sharing the same session.
• Persistent session. Login survives app relaunch through flutter_secure_storage.
• Touch-first UI. Bottom sheets, compact lists, and tab persistence — not a desktop port.
• Real validation. Module-by-module emulator testing was used throughout development.

Documentation

• docs/README.md — module overview
• docs/ARCHITECTURE.md — mobile-specific architecture detail
• AGENTS.md — contributor guidance

For backend, web, and deployment context, use the main repo: blank-space-gsu/cloud-computing-project.

Known limitations

• Mobile deep-link handling is still limited.
• Recurring-rule edit / pause / resume is not built yet.
• Manager task edit/reassign deserves deeper end-to-end mobile coverage.
• Android store-grade signing is not finalized in-repo.
• The app is production-usable, but there is still room for polish in notifications, offline handling, and richer activity history.