# Roadmap: mobile version, multiple projects, access outside the VPN Date: 2026-10-12 Status: plan for a future build. It is not a spec. No wave, `CR-`, or `D-` id exists for it yet. Inputs: `docs/waves/decisions-2026-10-12.md` (Q2 to Q14), `BL-062` to `BL-068` in `docs/waves/backlog.md`, and the code as of `main` (`d42ae0c`). Goal (from Matt, 2026-10-12): field agents use the app on phones and tablets on site, from outside the VPN, across more than one project. Scope facts confirmed by Matt on 2026-10-12: - All end users will be in the Okta group. There are no contractors without an Okta account. - The product will scale to **multiple customers**, not only more projects for one customer. - The devices will be **company-managed**. ## 1. Where the product is today | Area | Fact today | Source | |---|---|---| | Mobile shell | A PWA already exists: `manifest.webmanifest` (standalone, "Field View" shortcut) and `sw.js` (caches the app shell and uploaded drawings). | `html/manifest.webmanifest`, `html/sw.js` | | Offline writes | Writes queue in a sync outbox in `project-data.js`. Reads fall back to a `localStorage` cache. `/api/*` is never cached by the service worker. | `html/sw.js` header | | Offline drawings | Drawings for the user's assigned packages are prefetched and cached (CR-007, D8). | `html/sw.js`, `html/field.js` | | Files | The bytes live in the Postgres `wp_files` table. Limit: 5 MB a file, 2 GB per project. | `server/models.py` | | Sign-in | Okta OIDC. A signed cookie (`HttpOnly`, `SameSite=Lax`, `Secure` over HTTPS). Idle timeout (D18, T13.1) is on `feat/waves-11-13`, not on `main`. | `server/auth.py`, `docs/waves/wave-13.md` | | Projects | `Project` and `ProjectMember` exist. Access is by project role. There is no organization or customer level above the project. | `server/models.py` | | Hosting | Docker Compose on an internal host. NGINX serves the site. An external proxy ends TLS. The database and backup containers have no internet route. | `docker-compose.yml`, `nginx/conf.d/wp-suite.conf` | | Asset picker | Reads the Micron SQL Server catalog through `MICRON_DB_URL`. That database sits on the company network. | `server/assets_db.py` | | Abuse limits | No rate limiting or login throttling was found in `server/`. CSRF origin checks and security headers (CSP, HSTS) exist. | `server/app.py`, `wp-suite.conf` | | Security review | The 2026-10-01 review put session revocation (SEC-06) on hold until the AWS work. Wave 16 fixed SEC-01, SEC-02, SEC-07. | `docs/waves/decisions-2026-10-02.md` | Result: the "mobile app" is mostly built as a PWA. The main work is not a new app. It is (a) finishing offline Field View, (b) making the service safe to put on the internet, and (c) removing the single-host limits. ## 2. Path in phases Each phase has a gate. Do not start a phase before the gate of the one before it is met, unless this file says the phases are independent. Sizes are rough estimates (S under 1 week, M 1 to 3 weeks, L over 3 weeks). They are not commitments. ### Phase 0: Close the open decisions (S) - Answer the questions in section 7 and the "Still open" list in `decisions-2026-10-12.md`. - Assign `CR-`/`D-` ids and write the wave files. - **Gate:** every item in `BL-062` to `BL-068` is free of "to confirm". ### Phase 1: Finish offline Field View, still inside the VPN (L) Scope: `BL-062`, `BL-063`, `BL-064`. 1. Land the outbox work (wave 14, T14.1 to T14.3). `wave-12.md` says T13.1 must not reach `main` before T14.1. 2. Set the offline window to 7 days (Q2). Reconcile it with the D18 idle timeout and absolute ceiling. Define what "signed in" means offline. Decide what the 7 day window does when Okta says the account is disabled (wipe on the next online open). 3. Conflict handling (Q4): merge, field value wins on the same field, history of changes, a notification to the crew, a log entry, and an update to the owner. 4. Photos: capture on the device, 5 MB per photo (Q5). Add resize before upload if Matt chooses it. Store photos like drawings (server-side, with D19 download headers). 5. Add a phone and tablet test matrix (real devices): iOS Safari installed to the home screen, Android Chrome, one tablet. 6. Test the weak-link case: no signal, then a slow signal, then a sync with a conflict. Known platform risks to test on the devices (verify; do not assume): - iOS may delete site storage after a period of no use unless the PWA is installed to the home screen. - iOS Safari has no Background Sync. The outbox then sends only while the app is open. A crew member must open the app to push changes. - A lost device holds up to 7 days of project data. Web storage is not encrypted by the app. See Phase 2. **Gate:** the crew completes a full shift offline on a test device, reconnects, and the server holds every change. The conflict case works as Q4 says. `tests/mobile_check.py` and the 390px/1440px checks pass. ### Phase 2: Make the service safe to reach from the internet (M to L) Today the design assumes the firewall. Outside the VPN, the app becomes the perimeter. Do this before any real user connects from the internet. | Control | Why | |---|---| | Rate limiting and login throttling on the API (none today) | Stops guessing and scraping. The toolkit (`sde-meeting-toolkit`) needed the same fix. | | A WAF or reverse proxy with request limits in front of NGINX | Filters bad requests before they reach the API. | | Real client IP handling (`X-Forwarded-For` from the trusted proxy only) | Limits and logs must use the real address, not the proxy. | | Okta policy for the app: MFA, session length, device trust | Okta is the only sign-in path (D15, D16). The policy is the control. Ask the Okta admin. | | Session revocation (SEC-06) | When a phone is lost, an admin must end that session now. This was put on hold for the AWS work. Bring it forward. | | A rule for lost devices | Devices are company-managed (decided). Require a device PIN and disk encryption through the device policy. Remote wipe through the device manager. Pair it with session revocation (above), because a wipe cannot reach an offline device. Confirm with IT that the policy covers every phone and tablet that runs the app, and that a lost device is reported quickly. | | Okta access rule | All end users are in the Okta group (decided). Gate the app on that group. Today the API creates the account on first sign-in; check that a person who is not in the group is refused, and that removal from the group ends access (this is what D18 and wave 13 do). Ask the Okta admin to add MFA and device-trust conditions for the outside path. | | Cookie flags on every cookie (the OIDC state cookie uses `https_only=False` in `server/app.py`) | Must be `Secure` on the public site. | | Review the 2026-10-01 findings that stayed in backlog drafts | Re-rank them for an internet-facing service. | | Outside review (a penetration test) | Required before the customer-IP data is reachable from the internet. | | Alerting on failed sign-ins and on odd upload sizes | Detect abuse early. | **Gate:** the controls above are in place and an outside test finds no high findings open. ### Phase 3: Hosting that can leave the office network (L) The AWS work is already planned (SEC-06 note). Proposed shape. The choice of services is open for Matt and the AWS owner. - A public edge (load balancer, WAF, TLS) in front of the API and the static site. - API containers on a managed container service, with a managed Postgres database. - Files in object storage instead of the database (`BL-066`, Q13). Move the bytes out of `wp_files`. Keep the metadata in Postgres. Kept files from deleted packages go to a retention area with a lifecycle rule. The quota counts only live files. - Backups and restore tests on the new stack (the current backup container writes to a host folder). - A private link back to the Micron asset database, or a different design for the asset picker (the catalog is on the company network). Until this exists, the picker falls back to manual entry outside the VPN. Check that fallback works for a user who is online but cannot reach the database (the code treats "unconfigured" as a normal state, but not "unreachable"). - Infrastructure as code, so the environment can be rebuilt. - Keep the internal deployment working until the cutover. **Gate:** a full restore test passes, the migration runs on Postgres (render the SQL for the Postgres dialect first, BL-027), and a rollback plan is written and rehearsed. ### Phase 4: Many projects and many customers (L) Matt confirmed multiple customers. A customer boundary is now part of the plan, not an option. The data model has `Project` and `ProjectMember` but nothing above a project, so this phase changes the base design. Plan for it early. Phase 3 choices (storage layout, database layout) must already allow it. - Add an organization (customer) level above `Project`. Every project, user role, file, report, export, and search belongs to one organization. A user may belong to more than one organization (for example Prime Controls staff who work for several customers). Decide this rule first (section 7, question 1). - Isolation: choose the model before any code. Options: one database with an organization id on every row and checks on every query; a separate schema per customer; or a separate database or stack per customer. Matt and the AWS owner decide. The choice sets cost, backup, and the strength of the separation that a customer can be shown. - Files: one storage prefix per customer, with its own access rule and, if a customer asks, its own encryption key. - Customer-specific data: the cost-code list, the asset catalog (today Micron only), and the SOP templates must belong to the organization or the project. `BL-068` (one cost-code list in the SOP) must not become one list for all customers. - Okta: map Okta groups to organizations and projects, so the Okta admin controls who sees which customer. - Reports and the admin console: super users see only the organizations they are given. Check CR-019 usage reports, the user directory, and the bulk user tools from wave 12 against this rule. - Onboarding a customer: a runbook with the steps and a checklist. - Project onboarding: create a project, load its SOP, cost codes (`BL-068`, one list in the SOP, codes from the PM), people, and roles. Use the bulk user tools from wave 12. - Okta group to project membership mapping, so the Okta admin controls who joins a project. - Per-project storage and photo quotas (2 GB per project exists today) and per-project usage reports (CR-019 on `feat/waves-11-13`). - Performance work with a load test: many crews syncing at shift start. Check the outbox flush, the `wp_files` move, and the list endpoints on a large project. - Data retention rules per project. **Gate:** two real customers run side by side. A test user in one customer cannot reach any data of the other through any screen, report, export, search, file link, or API call. A test that tries to cross the boundary on purpose passes. The load test meets targets that Matt sets. ### Phase 5: Native wrapper (only if needed) (M) Wrap the PWA in a native shell (for example Capacitor) only if Phase 1 testing shows a platform limit that the PWA cannot meet: storage eviction, no background sync, camera control, or a company rule for app-store distribution. A wrapper adds app-store review, signing, and update cost. Do not start it by default. ## 3. Order and dependencies ``` Phase 0 -> Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 \_ Phase 5 (decide after Phase 1 device tests) ``` - Phase 2 may start in part while Phase 1 runs (rate limiting, Okta policy review). No crew uses the internet path before Phase 2 is done. - Phase 3 (storage move) and `BL-066` (retained drawings) are the same work. Do them together. - Phase 4 needs the Phase 2 and Phase 3 gates. Opening a second project to the internet first would repeat any gap twice. ## 4. Work that this path adds to the backlog | Id | Item | Phase | |---|---|---| | BL-062 to BL-068 | Already logged | 1, 3, 4 | | New | API rate limiting and login throttling | 2 | | New | Real client IP handling behind the proxy | 2 | | New | Session revocation (SEC-06) brought forward | 2 | | New | Device policy check with IT (PIN, encryption, remote wipe) | 1, 2 | | New | Okta group gate and MFA/device-trust conditions for the outside path | 2 | | New | Object storage and lifecycle rules for files, one prefix per customer | 3 | | New | Asset picker when the Micron database is unreachable | 3 | | New | Organization (customer) level above `Project`, with the isolation model chosen first | 3, 4 | | New | Per-customer cost codes, asset catalog, and SOP templates | 4 | | New | Okta group to organization and project mapping | 4 | | New | Cross-customer access tests (a test that tries to cross the boundary) | 4 | | New | Customer onboarding runbook | 4 | | New | Load test and capacity targets | 4 | Log these in `docs/waves/backlog.md` when Matt agrees with the plan. This file does not add them, so the backlog stays free of unconfirmed scope. ## 5. Risks 1. **Customer data on lost devices.** Offline data for 7 days on a phone or tablet. Devices are company-managed, which lowers this risk a lot, but only if the device policy (PIN, disk encryption, remote wipe) is real and covers every device. An offline device cannot receive a wipe until it connects. Keep the 7 day window only if IT confirms the policy. 2. **Customer boundary added late.** The data model has no organization level. If Phases 1 to 3 are built without it, every later change touches every table and every query. Choose the isolation model in Phase 0 and design Phase 3 storage around it. 3. **Contract terms.** Customer drawings and asset data may have rules about where they are stored and who can reach them. With several customers, each contract may differ. Check before Phase 3 (cloud storage) and before Phase 2 (internet access). 4. **Okta.** The app has no password of its own. A weak Okta policy for the outside path is a weak app. The Okta admin owns that setting. 5. **Single database host.** The current database is one container with a host-folder backup. Phase 3 fixes this. Until then, do not add projects that need high availability. 6. **Sequence risk.** T13.1 (idle timeout) must wait for T14.1 (outbox). A short idle timeout can end a session while a crew is offline. Settle the rule in Phase 1. ## 6. What does not change These decisions stay as recorded: Actual Hours stays (CR-017), localization stays (A7), uppercase card headers stay (A5), the logged-override path for predecessors stays (A1), removed fields are hidden and not deleted (CR-002, CR-016), and the token rule for CSS. Mobile work follows the accessibility rules (C1): real buttons, visible focus, `aria-live` for status, hover is not enough on tablets. ## 7. Questions that decide the plan Answered on 2026-10-12: - Who are the outside users? **All end users will be in the Okta group.** No separate sign-in design is needed. - What does "multiple projects" mean? **Multiple customers.** See Phase 4. - Which devices? **Company-managed.** Answer these before Phase 0 ends. The first four are new and follow from the answers above. 1. **Can one person work for more than one customer?** For example, a Prime Controls planner on two customers' projects. This sets how the organization level and the Okta groups map to each other. 2. **Which isolation model?** One database with an organization id on every row, a schema per customer, or a database or stack per customer. Do any customers already require a separate stack in their contract? 3. **Who manages the Okta groups?** One group for all users, or one group per customer or project? Does the Okta admin accept that mapping? 4. **What does the device policy enforce today?** PIN, disk encryption, remote wipe, and a time limit for a device to check in. Ask IT. 5. **Connectivity on site.** No signal for days, or weak signal that comes and goes? This sets how long the offline window must really be, and how big the photo queue gets. 6. **AWS.** Is the AWS move approved? Who owns the account? Which region? Can the Micron database be reached from it? 7. **Contract.** Can customer drawings and asset data be stored in cloud storage and reached from the internet? Does each customer have its own terms? 8. **Distribution.** Is an installed PWA enough, or does the company need an app-store app? Company-managed devices can often install a web app from a device policy. Ask IT. 9. **Targets.** How many customers, projects, and users, and how many crews syncing at the same time, in the first year?