# dklasens/vodalens-au architecture

> Architecture diagram of the GitHub repository dklasens/vodalens-au, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dklasens/vodalens-au
- Repository: https://github.com/dklasens/vodalens-au

## Overview

VodaLens is an Android companion for viewing Vodafone AU usage, service-level daily history, billing-cycle pace, historical cycles, and bills. The main workflow is sign in to Vodafone, retain the connection and cached account data securely on-device, then refresh and present account information. The repository also includes a separate optional desktop research backend and earlier browser-extension research; neither is required by Android. Android source references and README statements support the main links; backend links are limited to shown imports and wiring.

Main entry points: [`services/api/src/oauth.cjs`](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/oauth.cjs) (OAuth auth), [`services/api/src/server.cjs`](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/server.cjs) (Backend startup), [`apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt`](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt) (Vodafone API), [`services/api/src/app.cjs`](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/app.cjs) (HTTP API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android companion"]
  node_activity["App screens<br/>[MainActivity.kt]"]
  node_viewmodel["Account state<br/>[LensViewModel.kt]"]
  node_models["Account models<br/>[Models.kt]"]
  node_codec["Cache codec<br/>[JsonCodec.kt]"]
  node_secure[("Encrypted storage<br/>[SecureStore.kt]")]
  node_remove["Connection removal"]
  node_colors["Service accents<br/>[AccentColors.kt]"]
end

subgraph group_provider["Vodafone access"]
  node_login["Sign-in flow<br/>[VodafoneLogin.kt]"]
  node_loginsecurity["Login safeguards<br/>[LoginSecurity.kt]"]
  node_api["Vodafone API<br/>[VodafoneApi.kt]"]
  node_renewal["Session renewal<br/>[SessionRenewal.kt]"]
  node_reads["Concurrent reads<br/>[ConcurrentReads.kt]"]
end

subgraph group_backend["Desktop research backend"]
  node_server["Backend startup<br/>[server.cjs]"]
  node_app["HTTP API routes<br/>[app.cjs]"]
  node_auth["Auth selection<br/>[auth.cjs]"]
  node_session["Browser session auth<br/>[session.cjs]"]
  node_oauth["OAuth auth<br/>[oauth.cjs]"]
  node_store[("Backend vault<br/>[store.cjs]")]
  node_config["Backend config<br/>[config.cjs]"]
  node_research["Renewal experiment"]
  node_account["Account checks<br/>[account.cjs]"]
end

subgraph group_shared["Backend packages"]
  node_domain["Usage domain<br/>[index.cjs]"]
  node_providerclient["Provider adapter<br/>[index.cjs]"]
  node_backendclient["Backend client<br/>[index.cjs]"]
end

node_person(("Phone user"))
node_vodafone["Vodafone AU"]

node_person -->|"uses"| node_activity
node_activity -->|"drives"| node_viewmodel
node_viewmodel -->|"reads and writes"| node_secure
node_viewmodel -->|"requests account data"| node_api
node_login -->|"saves credentials"| node_secure
node_login -->|"authenticates"| node_vodafone
node_api -->|"fetches account data"| node_vodafone
node_api -->|"loads credentials"| node_secure
node_api -->|"renews session"| node_renewal
node_activity -.->|"styles services"| node_colors
node_server -->|"loads"| node_config
node_server -->|"creates"| node_store
node_server -->|"creates"| node_auth
node_server -->|"creates"| node_app
node_server -->|"creates"| node_research
node_auth -->|"selects"| node_session
node_auth -->|"selects"| node_oauth
node_app -->|"uses"| node_domain
node_app -->|"requests provider data"| node_providerclient
node_app -->|"uses auth errors"| node_oauth
node_session -->|"verifies account access"| node_providerclient
node_session -->|"uses auth errors"| node_oauth
node_oauth -->|"verifies API access"| node_providerclient
node_oauth -->|"checks account data"| node_account
node_research -->|"uses provider adapter"| node_providerclient
node_research -->|"checks account data"| node_account
node_research -->|"uses auth errors"| node_oauth

click node_activity "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/MainActivity.kt"
click node_viewmodel "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/LensViewModel.kt"
click node_models "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/Models.kt"
click node_codec "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/JsonCodec.kt"
click node_secure "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/SecureStore.kt"
click node_login "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/VodafoneLogin.kt"
click node_loginsecurity "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/LoginSecurity.kt"
click node_api "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt"
click node_renewal "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/SessionRenewal.kt"
click node_reads "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/ConcurrentReads.kt"
click node_remove "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/ConnectionRemoval.kt"
click node_colors "https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/AccentColors.kt"
click node_server "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/server.cjs"
click node_app "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/app.cjs"
click node_auth "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/auth.cjs"
click node_session "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/session.cjs"
click node_oauth "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/oauth.cjs"
click node_store "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/store.cjs"
click node_config "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/config.cjs"
click node_research "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/renewal-research.cjs"
click node_account "https://github.com/dklasens/vodalens-au/blob/main/services/api/src/account.cjs"
click node_domain "https://github.com/dklasens/vodalens-au/blob/main/packages/domain/src/index.cjs"
click node_providerclient "https://github.com/dklasens/vodalens-au/blob/main/packages/vodafone-client/src/index.cjs"
click node_backendclient "https://github.com/dklasens/vodalens-au/blob/main/packages/backend-client/src/index.cjs"

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_activity,node_viewmodel,node_models,node_codec,node_secure,node_remove,node_colors,node_person toneBlue
class node_login,node_loginsecurity,node_api,node_renewal,node_reads toneAmber
class node_server,node_app,node_auth,node_session,node_oauth,node_store,node_config,node_research,node_account toneMint
class node_domain,node_providerclient,node_backendclient toneRose
class node_vodafone toneIndigo
```

## Components

### Android companion

- [App screens](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/MainActivity.kt): `apps/android/app/src/main/java/au/com/vodalens/MainActivity.kt`
- [Account state](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/LensViewModel.kt): `apps/android/app/src/main/java/au/com/vodalens/LensViewModel.kt`
- [Account models](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/Models.kt): `apps/android/app/src/main/java/au/com/vodalens/Models.kt`
- [Cache codec](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/JsonCodec.kt): `apps/android/app/src/main/java/au/com/vodalens/JsonCodec.kt`
- [Encrypted storage](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/SecureStore.kt): `apps/android/app/src/main/java/au/com/vodalens/SecureStore.kt`
- [Connection removal](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/ConnectionRemoval.kt): `apps/android/app/src/main/java/au/com/vodalens/ConnectionRemoval.kt`
- [Service accents](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/AccentColors.kt): `apps/android/app/src/main/java/au/com/vodalens/AccentColors.kt`

### Vodafone access

- [Sign-in flow](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/VodafoneLogin.kt): `apps/android/app/src/main/java/au/com/vodalens/VodafoneLogin.kt`
- [Login safeguards](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/LoginSecurity.kt): `apps/android/app/src/main/java/au/com/vodalens/LoginSecurity.kt`
- [Vodafone API](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt): `apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt`
- [Session renewal](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/SessionRenewal.kt): `apps/android/app/src/main/java/au/com/vodalens/SessionRenewal.kt`
- [Concurrent reads](https://github.com/dklasens/vodalens-au/blob/main/apps/android/app/src/main/java/au/com/vodalens/ConcurrentReads.kt): `apps/android/app/src/main/java/au/com/vodalens/ConcurrentReads.kt`

### Desktop research backend

- [Backend startup](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/server.cjs): `services/api/src/server.cjs`
- [HTTP API routes](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/app.cjs): `services/api/src/app.cjs`
- [Auth selection](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/auth.cjs): `services/api/src/auth.cjs`
- [Browser session auth](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/session.cjs): `services/api/src/session.cjs`
- [OAuth auth](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/oauth.cjs): `services/api/src/oauth.cjs`
- [Backend vault](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/store.cjs): `services/api/src/store.cjs`
- [Backend config](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/config.cjs): `services/api/src/config.cjs`
- [Renewal experiment](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/renewal-research.cjs): `services/api/src/renewal-research.cjs`
- [Account checks](https://github.com/dklasens/vodalens-au/blob/main/services/api/src/account.cjs): `services/api/src/account.cjs`

### Backend packages

- [Usage domain](https://github.com/dklasens/vodalens-au/blob/main/packages/domain/src/index.cjs): `packages/domain/src/index.cjs`
- [Provider adapter](https://github.com/dklasens/vodalens-au/blob/main/packages/vodafone-client/src/index.cjs): `packages/vodafone-client/src/index.cjs`
- [Backend client](https://github.com/dklasens/vodalens-au/blob/main/packages/backend-client/src/index.cjs): `packages/backend-client/src/index.cjs`

### Other components

- **Phone user**
- **Vodafone AU**

## Connections

- Phone user → App screens: uses (evidence: `README.md`)
- App screens → Account state: drives (evidence: `apps/android/app/src/main/java/au/com/vodalens/MainActivity.kt`)
- Account state → Encrypted storage: reads and writes (evidence: `apps/android/app/src/main/java/au/com/vodalens/LensViewModel.kt`)
- Account state → Vodafone API: requests account data (evidence: `apps/android/app/src/main/java/au/com/vodalens/LensViewModel.kt`)
- Sign-in flow → Encrypted storage: saves credentials (evidence: `apps/android/app/src/main/java/au/com/vodalens/VodafoneLogin.kt`)
- Sign-in flow → Vodafone AU: authenticates (evidence: `README.md`)
- Vodafone API → Vodafone AU: fetches account data (evidence: `README.md`)
- Vodafone API → Encrypted storage: loads credentials (evidence: `apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt`)
- Vodafone API → Session renewal: renews session (evidence: `apps/android/app/src/main/java/au/com/vodalens/VodafoneApi.kt`)
- App screens → Service accents: styles services
- Backend startup → Backend config: loads (evidence: `services/api/src/server.cjs`)
- Backend startup → Backend vault: creates (evidence: `services/api/src/server.cjs`)
- Backend startup → Auth selection: creates (evidence: `services/api/src/server.cjs`)
- Backend startup → HTTP API routes: creates (evidence: `services/api/src/server.cjs`)
- Backend startup → Renewal experiment: creates (evidence: `services/api/src/server.cjs`)
- Auth selection → Browser session auth: selects (evidence: `services/api/src/auth.cjs`)
- Auth selection → OAuth auth: selects (evidence: `services/api/src/auth.cjs`)
- HTTP API routes → Usage domain: uses (evidence: `services/api/src/app.cjs`)
- HTTP API routes → Provider adapter: requests provider data (evidence: `services/api/src/app.cjs`)
- HTTP API routes → OAuth auth: uses auth errors (evidence: `services/api/src/app.cjs`)
- Browser session auth → Provider adapter: verifies account access (evidence: `services/api/src/session.cjs`)
- Browser session auth → OAuth auth: uses auth errors (evidence: `services/api/src/session.cjs`)
- OAuth auth → Provider adapter: verifies API access (evidence: `services/api/src/oauth.cjs`)
- OAuth auth → Account checks: checks account data (evidence: `services/api/src/oauth.cjs`)
- Renewal experiment → Provider adapter: uses provider adapter (evidence: `services/api/src/renewal-research.cjs`)
- Renewal experiment → Account checks: checks account data (evidence: `services/api/src/renewal-research.cjs`)
- Renewal experiment → OAuth auth: uses auth errors (evidence: `services/api/src/renewal-research.cjs`)
