Repositories and project tracking

In this sprint each member implemented one new business question, different from the six of Sprint 2 and taken from the list we defined in Sprint 1. On Android the questions are about the reservation flow, the use of the forecast and the drivers we send to nearby lots. On iOS they are about the forecast shown to the driver, the speed and stability of the reservation flow, and the accessible and charging spots.

All twelve questions, the six of Sprint 2 and the six of this sprint, are answered in one dashboard that reads the same database the apps use (section 2).

• BQ8 asks for sessions where the prediction was "checked before leaving home". The app cannot know where the driver is, so we count a day as planned when the driver opened the forecast or changed the arrival time before the first live map or spot search of that day.
• BQ9 was left out in Sprint 2 because we are not connected to any nearby lot. The Sprint 1 definition already allowed user-confirmed arrivals as the data source, and that is what we use now: after tapping Navigate, the app asks the driver once whether they parked in that lot.
• BQ11 talks about crashes. We do not use an external crash service, so the iOS app saves a mark when the Reserve screen opens and removes it when the screen closes or the app goes to the background. If the app opens and the mark is still there, the previous session ended inside the reservation flow without closing normally, and it is counted as a crash.

The pipeline of Sprint 2 stays the same: both apps send telemetry events, the backend records reservations, check-ins and occupancy snapshots, and everything goes to one PostgreSQL database. In this sprint we added the six new questions and a dashboard that shows all of them together.

flowchart TD
    subgraph Collect["1. Collection (phone)"]
        direction TB
        Droid["Android app<br/>TelemetryClient"]
        IOS["iOS app<br/>TelemetryService"]
        Queue[("Offline queues<br/>events and actions")]
    end

    subgraph Ingest["2. Ingestion (Moviles-Backend)"]
        direction TB
        Tel["POST /telemetry"]
        Ops["/reservations and /levels"]
        Sim["Occupancy simulator<br/>snapshot every 15 min"]
    end

    subgraph Store["3. Storage (one PostgreSQL on Neon)"]
        direction TB
        Events[("telemetry_events")]
        Res[("reservations")]
        Snap[("occupancy_snapshots<br/>with free accessible and EV")]
    end

    subgraph Agg["4. Aggregation (one SQL query per BQ)"]
        direction TB
        S2["BQ1 to BQ6"]
        S3["BQ7 to BQ12"]
    end

    subgraph Use["5. Consumption"]
        direction TB
        Dash["Team<br/>dashboard /dashboard/"]
        Driver["Driver, inside the app<br/>BQ2, BQ6, BQ10, BQ12"]
    end

    Collect --> Ingest --> Store --> Agg --> Use

Diagram Rationale

• Collection: events produced without signal wait in the queue of each app and are sent when the connection returns, so the questions also count what happens underground.
• Storage: the only change to the database is two columns in the occupancy snapshots, the free accessible and the free charging spots of each level, which BQ12 needs.
• Aggregation: each question is one SQL query in its own file in src/analytics/, and GET /api/v1/analytics/summary puts them together.
• Consumption: the Type 2 questions go back to the driver inside the app. All twelve are shown to the team in the dashboard.
• Privacy: the dashboard needs a session and only shows aggregated values. User ids never leave the backend.

All the business questions are in one dashboard at https://parkwise-api-a1f0.onrender.com/dashboard/. It is part of Moviles-Backend, so it reads the same PostgreSQL database that both apps use. There is no second database and no exported file.

• The page signs in with a ParkWise account and calls GET /api/v1/analytics/summary. Each section of that answer is computed with SQL at the moment the page asks for it.
• It refreshes every 30 seconds while the tab is visible, and there is a Refresh button.
• There is one card per question with its owner and type, and a table view under each chart.
• The charts are drawn with plain SVG served by the backend itself, so the security headers (script-src 'self') did not have to be relaxed.

(screenshot of the dashboard)

ParkWise is used in the place with the worst signal on campus. P2 and P3 are underground and have no signal at all, and the ramps and the gate have a weak one. These are the scenarios both apps handle:

We do not use one generic message for the whole app. In Sprint 2 the iOS app showed the same banner on every screen when the connection was lost. In this sprint it was replaced: each view below has its own behavior and its own message, and the driver can keep navigating between views without signal.

These are the strategies we use, with the names we give them in the tables:

• Network, then saved copy: ask the server first, and if it cannot be reached show the last copy saved on the phone with the time it was saved.
• Saved copy first: show what is on the phone at once, and ask the server only if the copy is old.
• Prefetch: download what will be needed underground while there is still signal.
• Local queue: save the action on the phone and send it when the signal returns.
• Optimistic update: show the result of a queued action at once, as if the server had already accepted it.
• Online only, with a reason: for actions that only the server can decide, disable the button and explain why, keeping what the driver already chose.
• Local computation: compute on the phone what can be computed with saved data, such as filters, search and recommendations.

Both apps follow the same sequence. The names are the Android ones.

sequenceDiagram
    autonumber
    actor Driver
    participant VM as ReserveViewModel
    participant Outbox as Offline-first repository
    participant DB as SQLite on the phone
    participant API as Moviles-Backend

    Driver->>VM: I parked (no signal)
    VM->>Outbox: checkIn(id)
    Outbox->>API: POST /reservations/:id/check-in
    API--xOutbox: network error
    Outbox->>DB: save pending action
    Outbox-->>VM: reservation shown as parked
    VM-->>Driver: "Saved on this phone, 1 action waiting"
    Note over Outbox: the signal returns, or the app opens again
    Outbox->>DB: read pending actions in order
    Outbox->>API: POST /reservations/:id/check-in
    alt Accepted
        API-->>Outbox: fulfilled
        Outbox->>DB: delete the action
    else The hold expired before it arrived (409)
        API-->>Outbox: 409
        Outbox->>DB: delete the action
        Outbox-->>VM: message for the driver
    end

Diagram Rationale

• The queue keeps the order of the actions. A driver can tap "I parked" and later "I left" without signal, and the server must receive them in that order.
• Only one sending runs at a time. The signal returning, the app opening and the Reserve screen loading can all ask to send at the same moment, and without that rule an action could be sent twice.
• A network error keeps the action in the queue. Any other answer from the server removes it, because sending it again would fail again, and the driver is told what happened.

(screenshots of each view without signal, Android and iOS)

The SQLite code is in lib/infrastructure/storage/, behind ports of the domain layer, so the ViewModels never use SQL directly. The tables of the nearby lots arrive in version 2 of parkwise.db, which upgrades the database of a phone that already had version 1.

flowchart LR
    subgraph Android["Android"]
        direction TB
        A1[("SQLite<br/>actions, history, lots, redirects")]
        A2[("Hive<br/>copies, drafts, events")]
        A3[("Files<br/>forecast, images")]
        A4[("SharedPreferences<br/>arrival time, level")]
        A5[("Secure storage<br/>JWT")]
    end
    subgraph IOS["iOS"]
        direction TB
        I1[("SwiftData<br/>actions, history")]
        I2[("Files<br/>server copies, images")]
        I3[("UserDefaults<br/>drafts, choices, events")]
        I4[("Keychain<br/>JWT")]
    end

Diagram Rationale

• Each kind of data goes where it fits: lists that are queried go to a relational database, whole documents go to files, small values go to preferences, and credentials go to encrypted storage.
• Both platforms keep the same data for the same reasons, so a view behaves the same on Android and iOS without signal.

LRU cache in memory for Find a spot (Rodrigo García, lib/core/cache/lru_cache.dart)

• Structure: a LinkedHashMap that keeps the keys in order of use. Reading an entry moves it to the end, so the first key is always the least recently used one, and it is the one removed when the cache is full. Reading and writing take constant time.
• Key: destination building plus the selected filters. Value: the spots of the three levels with their time.
• maxEntries = 16: there are four filters, so a destination has 2⁴ = 16 combinations, and all of them fit.
• ttl = 30 s: spots change in minutes. Within 30 seconds, turning a filter on and off shows the list at once without asking for the three levels again. After that the entry counts as a miss.
• Only answers from the server go into memory. A copy read from disk without signal is never stored as if it were fresh, and pull to refresh skips the memory.

Image cache for the photos of buildings and lots (Andrés Cáceres, cached_network_image)

• One CacheManager for the whole app, used by Destinations and No campus spots.
• stalePeriod = 30 days: the photos almost never change, so a saved photo is used for a month before asking for it again.
• maxNrOfCacheObjects = 50: there are four buildings and two lots today, so 50 leaves room for new places while keeping the folder small. When the limit is passed, the photos used least recently are deleted first.
• Each photo is decoded at the size it is shown (memCacheWidth), so a large file does not take a large amount of memory.

Prefetch and saved copies (Andrés Cáceres and Sprint 2)

• When Home loads with signal, the three levels are downloaded and saved, so the map of P2 and P3 is ready before the driver goes down.
• Every answer of levels and spots is saved in Hive with its time and used when the network fails, as in Sprint 2.

Nearby lots with a time to live (Fabio Higuera)

• No campus spots reads the lots from SQLite first and asks the backend only when the copy is older than 24 hours or when the driver pulls to refresh. The lots change rarely, so the screen usually opens without waiting for the network.

NSCache for the results of Find spot (Felipe Sales)

• Key: destination plus the selected filter. Value: the sorted spots with the time they were received.
• countLimit = 16, for the same reason as Android: all the filter combinations of a destination fit.
• Entries older than 30 seconds are ignored and asked again.
• NSCache frees memory by itself when the system needs it, so the app never has to clean it by hand.

Two-level image cache for the photos of the lots (Julián Bohórquez, LotImageCache)

• Memory: NSCache with countLimit = 20 and totalCostLimit = 20 MB. The cost of each photo is its size in bytes once decoded, so a few large photos cannot fill the memory.
• Disk: if the photo is not in memory it is read from Caches/LotImages, and only if it is not there it is downloaded. The system may clean the Caches folder, which is fine for photos that can be downloaded again.

Saved answers and prefetch (Nicolas Bobadilla)

• ResponseCache now saves every answer that a view needs without signal, each one with its date, and the three levels are downloaded when Home loads with signal.

The occupancy of the spots is simulated by the backend. Reservations, check-ins, sessions, GPS positions and telemetry are real.

Both apps keep all the features of Sprint 2: login and register with JWT, live map refreshed every 5 seconds, Find a spot with filters and the recommended spot, reservation with countdown and check-in, Find my car with GPS, campus full with nearby lots, occupancy forecast and recommended level, profile with history, and the telemetry of BQ1 to BQ6. Since Sprint 2 the iOS app can also be used as a guest, and it asks for an account only to reserve, find the car or see the profile.

Views (Android):

• Rodrigo García: Login, Register, Find a spot and Reserve.
• Andrés Cáceres: Home, Level map, Forecast (new) and Destinations (new).
• Fabio Higuera: No campus spots, Find my car, Offline and Profile.

Views (iOS):

• Nicolas Bobadilla: Login, Register, Home, Parking map and Profile.
• Julián Bohórquez: Reserve spot, Campus full, Lot details (new) and My reservations (new).
• Felipe Sales: Find spot, Find car, Offline (new) and Accessible and EV spots (new).

• Dashboard at /dashboard/ with the twelve questions, served by the backend itself.
• One SQL query per new question, BQ7 to BQ12, in src/analytics/, added to GET /analytics/summary.
• Free accessible and charging spots saved in every occupancy snapshot, and GET /special-spots/availability for the iOS app.
• Photos of the buildings and the nearby lots served by the backend, taken by the team.
• Automated tests for every new question and for the dashboard.

• The iOS banner that appeared on every screen without signal was removed. Each view now has its own offline behavior, and the new Offline screen collects what still works.
• The answers of the business questions were only available as JSON in GET /analytics/summary. Now they are all in one dashboard that reads the same database.
• The work of this sprint is tracked in a Kanban board in GitHub Projects, linked to the issues and pull requests of the milestone.