# Project plan — mobile (LOGiiT)

Evidence date: 2026-10-09.

Source repository: `git@bitbucket.org:overdrive/mobile.git`, branch `main` at `8ef251f` (2026-01-08, "Fixed null issues").

There was no `silicon_ark/mobile/` directory before this document set. In-repo product notes are `README.md`, `CHANGELOG.md`, `Notes.md`, `TEST_RESULTS.md`, `REST_API_CONVERSION_ANALYSIS.md`, and `credits.md`. This plan describes what that repository contains. It does not decide what the product should become.

## Product

The Dart package name is `logiit_flutter`. The user-facing name is **LOGiiT**. `pubspec.yaml` version is `1.3.0+82`. The in-app build label in `lib/env.dart` is `v1.3.0 [27/10/2025 9:30]`. `CHANGELOG.md` dates v1.3.0 as 28/10/2025.

LOGiiT is a Flutter client for commercial diving and ROV (remotely operated vehicle) logbooks. A signed-in person records projects, dives, and ROV tours, keeps a local copy, and syncs that copy with `https://app.logiit.co/` (production) or a flavor-specific host. Supervisors and ROV supervisors approve or decline work from a notifications screen. Divers and ROV pilots can open a competency flow named COMPiiT and a sharing flow (Share Logbook for divers, SHARiiT for ROV roles).

Provenance: **Implemented** in `lib/`. The README documents build commands and the offline/online save pattern. It does not state a product purpose beyond the package name.

Account registration and the forgotten-password page are opened in the browser at `{baseApiUrl}register` and `{baseApiUrl}forgot-password`. The app tells a person with no user-details record to complete their profile on the web before logging in. The web application itself is not in this repository.

## Branch reality

`main` is the only branch present in the clone. History is three commits, all on 2026-01-08:

| Commit | Subject | What it changes |
|---|---|---|
| `8c14445` | Initial commit | The application tree |
| `6748c92` | First commit , chrome working | Not diffed line by line. Subject says Chrome was made to work |
| `8ef251f` | Fixed null issues | Null-handling across models and Isar locals, FVM pin `3.38.5`, small README / changelog / test-result edits, `lib/main.dart` and `lib/env.dart` |

`CHANGELOG.md` describes v1.3.0 (28/10/2025) and v1.0.28. Those changes are not separate commits. Product history before 2026-01-08 is **Documented** only in the changelog.

No pull-request or pipeline file is in the tree. Which commit is installed on a store or device is **Unknown / Requires Confirmation**.

## Scope in the repository

In scope of what is implemented:

- Flutter app with Android product flavors `dev`, `staging`, `demo`, and `production`, each with its own `lib/main_*.dart` entry.
- GetX navigation, Isar local database on non-web platforms, and a generic HTTP CRUD client.
- Login, offline login after a prior online login, logout, and profile password-reset request.
- Role-based drawer: diver, supervisor, ROV pilot, ROV supervisor.
- Projects and dives, ROV tours, COMPiiT competency records, notifications, profiles, logbook sharing.
- Offline action log and background sync via Workmanager.
- Manual Android smoke notes in `TEST_RESULTS.md` (17 November 2025, dev flavor, emulator).

Out of scope of this repository, though the app depends on them:

- The LOGiiT HTTP API and the web register / profile / forgot-password pages.
- Store listing, signing keystore (`android/key.properties` is not in git), and production release approval.

`lib/config.dart` names a CodeCapsules host and an API key. A search of `lib/` found no use of `Config.apiUrl` or `Config.apiKey`. That file is not the live API configuration. `AppEnvironment` in `lib/env.dart` is.

Desktop folders `linux/`, `macos/`, and `windows/` are present as Flutter platform projects. No test note or README command treats them as a supported product. **Unknown / Requires Confirmation** whether they are shipped.

## System architecture

```text
Flutter UI (GetX pages)
    ↓
Services (auth, domain CRUD, sync, files)
    ↓
Local Isar database (mobile)     HTTP client → {flavor base URL}api/...
    ↓
Action log, replayed by SyncService when the device can reach the API
```

Web builds compile against `local_database_provider_web.dart`, which throws `UnsupportedError` because Isar is not used on web. `SplashPage` skips database init when `kIsWeb` is true, then still calls `AuthService.isAuthenticated()`. A working web product is not established. The commit subject "chrome working" is not enough to treat web as supported.

Connectivity is "can I reach `AppEnvironment.baseApiUrl`?", not a general internet check (`NetworkController`).

## Major components

| Area | Location | Role |
|---|---|---|
| Flavor entry | `lib/main.dart`, `lib/main_dev.dart`, `lib/main_staging.dart`, `lib/main_demo.dart`, `lib/main_production.dart` | Selects environment and starts GetX, Workmanager (not on web), database, network, and state |
| Environment | `lib/env.dart` | Title, API base URL, offline API host |
| Session | `lib/services/auth_service.dart` | JWT, offline user id, login, logout, verification flag |
| HTTP | `lib/services/http_service.dart`, `lib/services/online_crud_service.dart` | Bearer JSON calls under `{base}api/` |
| Local data | `lib/services/local_database_provider*.dart`, `lib/models_isar/` | Isar schemas on mobile |
| Sync | `lib/services/sync_service.dart`, `offline_log_service.dart`, `background_sync_service.dart`, `periodic_sync_service.dart` | Replay action logs; optional 15-minute periodic task |
| UI shell | `lib/widgets/app_page.dart` | Drawer, offline banner, student badge, hidden action-log entry |
| Features | `lib/pages/` | Splash, login, landing, projects, ROV, COMPiiT, notifications, profiles, sharing |

## Environments

| Flavor | Entry | Title | API base | Offline API host default | Android application id |
|---|---|---|---|---|---|
| dev | `lib/main_dev.dart` | LOGiiT Dev | `http://10.0.2.2/` | `logiit.local` | `co.logiit.app` |
| staging | `lib/main_staging.dart` | LOGiiT Staging | `https://staging-app.logiit.co/` | `4c26c0265b2cad392ae77c1e1de0bd10.balena-devices.com` | `co.logiit.app.staging` |
| demo | `lib/main_demo.dart` | LOGiiT Demo | `https://demo-app.logiit.co/` | same Balena host as staging | `co.logiit.app` |
| production | `lib/main_production.dart` | LOGiiT | `https://app.logiit.co/` | `logiit.local` | `co.logiit.app` |

`lib/main.dart` (the default `main()`, including web) calls `mainWithEnvironment(Environment.dev)`.

`10.0.2.2` is the Android emulator alias for the host machine. The code comment says "pc IP". A physical device on the dev flavor would not reach a developer PC through that address. **Inferred.**

Dev, demo, and production share `co.logiit.app`. Only staging adds a suffix. Installing one of those three flavors replaces another. **Implemented** in `android/app/build.gradle`.

## Milestones visible in the repo

There is no project plan, roadmap, or issue tracker in the repository.

| Marker | Evidence | Status |
|---|---|---|
| v1.0.28 | Changelog: offline API status dialog, login loading indicator, per-environment offline URL, iOS platform `16.0` | **Documented** as a past release. Not a separate git tag or commit |
| v1.3.0 | Changelog: ROV supervisor, vetters, contractor dive creation, hashes on user / user details / project, SHARiiT on the logbook entity, password visibility | **Documented**, and the corresponding types exist in `lib/` |
| Flutter 3.38.5 / Dart 3.10 | README, changelog, `.fvm/fvm_config.json` | **Documented** and pinned |
| Android dev APK smoke | `TEST_RESULTS.md`, 17 November 2025, package `co.logiit.app` | **Documented** manual test. Not re-run for this write-up |
| REST path conversion | `REST_API_CONVERSION_ANALYSIS.md`, estimate 31–40 hours | **Planned**. `OnlineCrudService` still calls `find/`, `put/`, `post/`, and the other non-REST paths |

## Implementation plan (as evidenced)

The README's own extension plan for a new model is:

1. Add a cloud model under `lib/models/` and a local Isar model under `lib/models_isar/`.
2. Add a service, register the schema on the local database, add a `DataType` and embedded payload on the action log, and register the service on `SyncService.serviceMap`.
3. Run `flutter pub run build_runner build`.

That is a developer procedure, not a product roadmap.

## Dependencies known from the repo

- Flutter SDK 3.38.5 via FVM. `pubspec.yaml` allows Dart `>=3.3.1 <4.0.0`.
- Isar Community `3.3.0-dev.2` for the on-device database.
- GetX, Dio is declared but HTTP calls in `HttpService` use `package:http`.
- Workmanager `0.9.0` for background sync. README and code both say it is not used on web.
- `flutter_secure_storage` for the offline password hash. The JWT is stored in `shared_preferences`, not secure storage.
- A LOGiiT API at the flavor base URL. Authentication is `Authorization: Bearer {jwt}`.
- An "offline API" host used only by the network-status dialog (long-press "Forgot Password?").
- Browser pages for register and forgot-password on the same base URL.
- Facebook, Instagram, and LinkedIn URLs on the login screen.

## Current project status

The tree on `main` at `8ef251f` is a complete Flutter application at version 1.3.0+82, not a starter app, despite `pubspec.yaml` description "A new Flutter project."

Automated coverage is one environment unit test in `test/widget_test.dart`. The file comments say widget tests that need `NetworkController` are skipped because of timers. `TEST_RESULTS.md` records one successful dev-flavor install on an Android 16 emulator and recommends tests that were not done: physical device, real API, full login, offline sync, and feature navigation.

No Bitbucket pipeline file was found.

## Human confirmation

1. Whether `main` at `8ef251f` is what is shipped, and to which stores or devices.
2. Whether Linux, macOS, Windows, or web are supported products. Web database init throws.
3. Whether the REST conversion analysis is an approved plan or an unused estimate.
4. `CHANGELOG.md` says "project supervisor no longer being verified before saving". `lib/pages/projects/project_widgets.dart` still calls `verifySupervisorEmails()` before save. Which statement is the rule needs confirmation.
5. `credits.md` contains plaintext account emails and passwords. `lib/config.dart` contains an unused API key literal. Both need a security decision. Values are not copied into Silicon Ark.
6. Meaning of logbook status id `1` (the client names 2, 3, 4, and 5 only).
7. Whether `UserType.admin` and `UserType.company` are real app roles. They exist on the enum and have no drawer destination.
8. Production value of the offline API host `logiit.local`, and whether the Balena hostname is still the staging/demo device.