# bcgov/visitz-app architecture

> Architecture diagram of the GitHub repository bcgov/visitz-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bcgov/visitz-app
- Repository: https://github.com/bcgov/visitz-app

## Overview

Visitz is a cross-platform MAUI mobile app for CFD workers. Its principal workflow is to authenticate, retrieve caseload and related records from the REST API, synchronize them for local/offline use, and let workers review or update record details such as contacts, notes, visits, attachments, and safety assessments. The app also supports drafts and navigation across these workflows. The graph preserves documented capabilities and indexed modules; unsampled UI wiring and many API-to-service relationships are not asserted unless the supplied evidence shows them.

Main entry points: [`visitz/VisitzApi/Vpi.cs`](https://github.com/bcgov/visitz-app/blob/production/visitz/VisitzApi/Vpi.cs) (API client), [`visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs`](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs) (Offline sync), [`visitz/Visitz/Services`](https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Services) (Record services), [`visitz/Visitz/Navigator.cs`](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Navigator.cs) (App navigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Mobile application"]
  node_maui["MAUI app<br/>[MauiProgram.cs]"]
  node_navigation["App navigation<br/>[Navigator.cs]"]
  node_recordui["Record workflows"]
  node_caseloadui["Caseload views"]
end

subgraph group_services["Business services"]
  node_servicehandler["Service dispatch<br/>[ServiceHandler.cs]"]
  node_offline["Offline sync"]
  node_caseloadservices["Caseload retrieval"]
  node_recordservices["Record services"]
end

subgraph group_api["REST API"]
  node_vpi["API client<br/>[Vpi.cs]"]
  node_endpoints["REST endpoints"]
  node_payloads["API payloads"]
end

subgraph group_domain["Domain and storage"]
  node_domainmodels["Business records"]
  node_realm[("Local Realm stores<br/>[VisitzRealms.cs]")]
  node_preferences[("Sync timestamps")]
end

subgraph group_identity["Authentication"]
  node_oidc["OIDC client"]
  node_token["JWT handling<br/>[TokenHolder.cs]"]
end

node_worker(("CFD worker"))

node_worker -->|"uses app"| node_maui
node_maui -.->|"starts navigation"| node_navigation
node_navigation -.->|"opens caseload"| node_caseloadui
node_navigation -.->|"opens records"| node_recordui
node_worker -->|"authenticates"| node_oidc
node_oidc -->|"handles JWTs"| node_token
node_servicehandler -->|"dispatches services"| node_offline
node_offline -->|"requests API data"| node_vpi
node_offline -->|"synchronizes records"| node_realm
node_offline -->|"reads timestamps"| node_preferences
node_caseloadservices -.->|"retrieves caseload"| node_vpi
node_recordservices -->|"retrieves record data"| node_vpi
node_recordservices -->|"stores synchronized data"| node_realm
node_recordservices -->|"uses pagination state"| node_preferences
node_vpi -->|"dispatches requests"| node_endpoints
node_vpi -->|"parses API data"| node_payloads
node_domainmodels -->|"maps API models"| node_payloads
node_recordui -.->|"loads record data"| node_recordservices
node_caseloadui -.->|"loads caseload"| node_caseloadservices

click node_maui "https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/MauiProgram.cs"
click node_navigation "https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Navigator.cs"
click node_recordui "https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Views/Entity"
click node_caseloadui "https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Views/Caseload"
click node_oidc "https://github.com/bcgov/visitz-app/blob/production/visitz/Oidc/AuthenticationClient.cs"
click node_token "https://github.com/bcgov/visitz-app/blob/production/visitz/Oidc/TokenHolder.cs"
click node_servicehandler "https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Services/ServiceHandler.cs"
click node_offline "https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs"
click node_caseloadservices "https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Services/Caseload"
click node_recordservices "https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Services"
click node_vpi "https://github.com/bcgov/visitz-app/blob/production/visitz/VisitzApi/Vpi.cs"
click node_endpoints "https://github.com/bcgov/visitz-app/tree/production/visitz/VisitzApi/Endpoints"
click node_payloads "https://github.com/bcgov/visitz-app/tree/production/visitz/VisitzApi/Models"
click node_domainmodels "https://github.com/bcgov/visitz-app/tree/production/visitz/VisitzModel/Models"
click node_realm "https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Storage/VisitzRealms.cs"
click node_preferences "https://github.com/bcgov/visitz-app/blob/production/visitz/VisitzModel/Storage/LastUpdatedPrefs.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_maui,node_navigation,node_recordui,node_caseloadui toneBlue
class node_servicehandler,node_offline,node_caseloadservices,node_recordservices toneAmber
class node_vpi,node_endpoints,node_payloads toneMint
class node_domainmodels,node_realm,node_preferences,node_worker toneRose
class node_oidc,node_token toneIndigo
```

## Components

### Mobile application

- [MAUI app](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/MauiProgram.cs): `visitz/Visitz/MauiProgram.cs`
- [App navigation](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Navigator.cs): `visitz/Visitz/Navigator.cs`
- [Record workflows](https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Views/Entity): `visitz/Visitz/Views/Entity`
- [Caseload views](https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Views/Caseload): `visitz/Visitz/Views/Caseload`

### Business services

- [Service dispatch](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Services/ServiceHandler.cs): `visitz/Visitz/Services/ServiceHandler.cs`
- [Offline sync](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs): `visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs`
- [Caseload retrieval](https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Services/Caseload): `visitz/Visitz/Services/Caseload`
- [Record services](https://github.com/bcgov/visitz-app/tree/production/visitz/Visitz/Services): `visitz/Visitz/Services`

### REST API

- [API client](https://github.com/bcgov/visitz-app/blob/production/visitz/VisitzApi/Vpi.cs): `visitz/VisitzApi/Vpi.cs`
- [REST endpoints](https://github.com/bcgov/visitz-app/tree/production/visitz/VisitzApi/Endpoints): `visitz/VisitzApi/Endpoints`
- [API payloads](https://github.com/bcgov/visitz-app/tree/production/visitz/VisitzApi/Models): `visitz/VisitzApi/Models`

### Domain and storage

- [Business records](https://github.com/bcgov/visitz-app/tree/production/visitz/VisitzModel/Models): `visitz/VisitzModel/Models`
- [Local Realm stores](https://github.com/bcgov/visitz-app/blob/production/visitz/Visitz/Storage/VisitzRealms.cs): `visitz/Visitz/Storage/VisitzRealms.cs`
- [Sync timestamps](https://github.com/bcgov/visitz-app/blob/production/visitz/VisitzModel/Storage/LastUpdatedPrefs.cs): `visitz/VisitzModel/Storage/LastUpdatedPrefs.cs`

### Authentication

- [OIDC client](https://github.com/bcgov/visitz-app/blob/production/visitz/Oidc/AuthenticationClient.cs): `visitz/Oidc/AuthenticationClient.cs`
- [JWT handling](https://github.com/bcgov/visitz-app/blob/production/visitz/Oidc/TokenHolder.cs): `visitz/Oidc/TokenHolder.cs`

### Other components

- **CFD worker**

## Connections

- CFD worker → MAUI app: uses app (evidence: `README.md`)
- MAUI app → App navigation: starts navigation
- App navigation → Caseload views: opens caseload
- App navigation → Record workflows: opens records
- CFD worker → OIDC client: authenticates (evidence: `README.md`)
- OIDC client → JWT handling: handles JWTs (evidence: `visitz/Oidc/AuthenticationClient.cs`)
- Service dispatch → Offline sync: dispatches services (evidence: `visitz/Visitz/Services/ServiceHandler.cs`)
- Offline sync → API client: requests API data (evidence: `visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs`)
- Offline sync → Local Realm stores: synchronizes records (evidence: `visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs`)
- Offline sync → Sync timestamps: reads timestamps (evidence: `visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs`)
- Caseload retrieval → API client: retrieves caseload (evidence: `visitz/Visitz/Services/Caseload/GetAllDataForOfflineService.cs`)
- Record services → API client: retrieves record data (evidence: `visitz/Visitz/Services/People/GetContactLegalAuthorityService.cs`)
- Record services → Local Realm stores: stores synchronized data (evidence: `visitz/Visitz/Services/People/GetContactLegalAuthorityService.cs`)
- Record services → Sync timestamps: uses pagination state (evidence: `visitz/Visitz/Services/People/GetContactLegalAuthorityService.cs`)
- API client → REST endpoints: dispatches requests (evidence: `visitz/VisitzApi/Vpi.cs`)
- API client → API payloads: parses API data (evidence: `visitz/VisitzApi/Vpi.cs`)
- Business records → API payloads: maps API models (evidence: `visitz/VisitzModel/Models/People/ContactLegalAuthority.cs`)
- Record workflows → Record services: loads record data
- Caseload views → Caseload retrieval: loads caseload