# sbccorpitdept/starbikecorp-aacms architecture

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

- Interactive diagram: https://gitdiagram.com/sbccorpitdept/starbikecorp-aacms
- Repository: https://github.com/sbccorpitdept/starbikecorp-aacms

## Overview

#### Purpose and Entry Points
StarbikeCop AACMS is an internal account-audit and collections system. Staff search customer accounts, record field visits (including payments, contact/address updates, repossessions, GPS/capture artifacts), review itineraries and reports, and administer assignments/staff.

Vite serves a multi-page browser application from root HTML routes: `index.html`, `audit.html`, `itinerary.html`, `reports.html`, `admin.html`, `login.html`, and `change-password.html`. Route registration/build inputs are centralized in `vite.config.js`.

#### Page-Level Application Layer
Each route loads a focused page controller under `src/pages/`; page modules orchestrate DOM behavior and call library APIs rather than querying the backend directly. Key workflows are:
- Dashboard: `src/pages/index/main.js`, `src/pages/index/dashboard.js`
- Audit capture and review: `src/pages/audit/main.js`, `src/pages/audit/form.js`
- Administration and assignment map: `src/pages/admin/main.js`, `src/pages/admin/visitMap.js`
- Reporting and itinerary: `src/pages/reports/main.js`, `src/pages/itinerary/main.js`

Shared browser UI is framework-agnostic: navigation and reusable tabular presentation reside in `src/components/navbar.js` and `src/components/dataTable.js`.

#### Backend Access Boundary
`src/lib/` is the application’s backend boundary: UI/page code should use it exclusively. The Supabase client and environment-based connection setup are in `src/lib/supabase.js`; domain APIs are divided by responsibility:
- Accounts, visits, payments, and collections: `src/lib/accounts.js`
- Authentication/account session behavior: `src/lib/auth.js`
- Audit report lifecycle: `src/lib/auditReport.js`
- Staff/admin and assignments: `src/lib/admin.js`, `src/lib/assignments.js`

This separation permits Supabase query, RPC, and storage changes without changing page controllers.

#### Audit Capture and Immutable History
The audit form is the central transactional workflow. It gathers visit outcomes and supporting evidence, then delegates persistence through domain libraries. Capture-specific concerns are separated into `src/lib/capture.js`, `src/lib/signaturePad.js`, and `src/lib/geo.js`; visit-review behavior is in `src/lib/visitReview.js`.

The database defines the durable audit model and invariants in `supabase/schema.sql`, with audit-oriented operations in `supabase/submit-audit.sql` and evolving visit fields in migrations such as `supabase/migrations/020_audit_report.sql`. The stated model preserves an insert-only/immutable audit trail and soft-archives customers rather than deleting them.

#### Offline-First Synchronization
Mobile/offline work introduces a local persistence and deferred-write pipeline. `src/lib/offline.js` manages offline state, `src/lib/outbox.js` represents queued mutations, and `src/lib/sync.js` reconciles queued work when connectivity returns. The intended audit-outbox design is documented in `docs/superpowers/specs/2026-07-07-offline-audit-outbox-design.md`.

The critical boundary is between locally captured visit data and server-confirmed Supabase writes; pages should not bypass the outbox/sync path for offline-capable mutations.

#### Supabase Data, Security, and Server Functions
Supabase provides PostgreSQL, authentication-related schema, object storage, and server-side functions. Bootstrap/schema material is under `supabase/schema.sql`, `supabase/auth.sql`, `supabase/storage-security.sql`, and `supabase/rls.sql`; incremental production evolution is in `supabase/migrations/`.

Privileged staff operations are implemented as Supabase Edge Functions: `supabase/functions/create-staff/index.ts` and `supabase/functions/reset-staff-password/index.ts`. Browser credentials come from `.env` keys documented in `.env.example`; sensitive administrative actions should remain behind these server-side boundaries.

#### Mobile Runtime and Delivery
The web application is packaged for native devices through Capacitor (`capacitor.config.json`). Android hosts the web runtime in `android/app/src/main/java/com/starbike/aacms/MainActivity.java`; iOS does so from `ios/App/App/AppDelegate.swift`. Native projects are containers rather than separate product implementations, so application behavior remains primarily in the Vite/JavaScript source tree.

Main entry points: [`src/lib/supabase.js`](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/supabase.js) (Supabase client), [`src/lib/outbox.js`](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/outbox.js) (Mutation outbox), [`src/pages/audit/form.js`](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/pages/audit/form.js) (Audit form), [`capacitor.config.json`](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/capacitor.config.json) (Capacitor packaging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser Application"]
  node_vite{{"Vite route build<br/>build configuration<br/>[vite.config.js]"}}
  node_pages["Page controllers<br/>browser controllers"]
  node_ui["Shared UI<br/>browser components"]
  node_domain["Domain APIs<br/>backend boundary"]
  node_supabase_client["Supabase client<br/>connection setup<br/>[supabase.js]"]
  node_audit_form["Audit form<br/>capture controller<br/>[form.js]"]
  node_capture["Capture services<br/>capture APIs<br/>[capture.js]"]
  node_visit_review["Visit review<br/>review API<br/>[visitReview.js]"]
end

subgraph group_offline["Offline Pipeline"]
  node_offline_state[("Offline state<br/>local persistence<br/>[offline.js]")]
  node_outbox["Mutation outbox<br/>queued mutations<br/>[outbox.js]"]
  node_sync{{"Sync reconciler<br/>connectivity sync<br/>[sync.js]"}}
  node_offline_design["Offline outbox design<br/>design specification"]
end

subgraph group_supabase["Supabase Backend"]
  node_database[("PostgreSQL audit model<br/>durable data model<br/>[schema.sql]")]
  node_audit_ops["Audit submit operations<br/>database operations<br/>[submit-audit.sql]"]
  node_security["RLS and storage security<br/>access policy<br/>[rls.sql]"]
  node_edge_functions{{"Staff edge functions<br/>privileged server functions<br/>[index.ts]"}}
end

subgraph group_native["Native Containers"]
  node_capacitor{{"Capacitor packaging<br/>native bridge"}}
  node_android["Android host<br/>native container<br/>[MainActivity.java]"]
  node_ios["iOS host<br/>native container<br/>[AppDelegate.swift]"]
end

node_vite -->|"serves page routes"| node_pages
node_pages -->|"renders shared UI"| node_ui
node_pages -->|"uses exclusively"| node_domain
node_audit_form -->|"captures evidence"| node_capture
node_audit_form -->|"reviews visits"| node_visit_review
node_audit_form -->|"queues offline mutations"| node_outbox
node_capture -->|"persists local work"| node_offline_state
node_offline_state -->|"supplies deferred writes"| node_outbox
node_outbox -->|"drains when online"| node_sync
node_offline_design -.->|"specifies"| node_outbox
node_domain -->|"connects through"| node_supabase_client
node_sync -->|"replays confirmed writes"| node_supabase_client
node_supabase_client -->|"queries and RPC"| node_database
node_supabase_client -->|"is constrained by"| node_security
node_audit_ops -->|"persists audit trail"| node_database
node_domain -->|"invokes privileged staff actions"| node_edge_functions
node_capacitor -->|"packages web runtime"| node_vite
node_android -->|"hosts"| node_capacitor
node_ios -->|"hosts"| node_capacitor

click node_vite "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/vite.config.js"
click node_supabase_client "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/supabase.js"
click node_audit_form "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/pages/audit/form.js"
click node_capture "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/capture.js"
click node_visit_review "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/visitReview.js"
click node_offline_state "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/offline.js"
click node_outbox "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/outbox.js"
click node_sync "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/sync.js"
click node_offline_design "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/docs/superpowers/specs/2026-07-07-offline-audit-outbox-design.md"
click node_database "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/schema.sql"
click node_audit_ops "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/submit-audit.sql"
click node_security "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/rls.sql"
click node_edge_functions "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/functions/create-staff/index.ts"
click node_capacitor "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/capacitor.config.json"
click node_android "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/android/app/src/main/java/com/starbike/aacms/MainActivity.java"
click node_ios "https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/ios/App/App/AppDelegate.swift"

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_vite,node_pages,node_ui,node_domain,node_supabase_client,node_audit_form,node_capture,node_visit_review toneBlue
class node_offline_state,node_outbox,node_sync,node_offline_design toneAmber
class node_database,node_audit_ops,node_security,node_edge_functions toneMint
class node_capacitor,node_android,node_ios toneRose
```

## Components

### Browser Application

Vite-served multi-page staff application.

- [Vite route build](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/vite.config.js): build configuration · Registers the root HTML page inputs. · `vite.config.js`
- **Page controllers**: browser controllers · Dashboard, audit, admin, reports, and itinerary workflows.
- **Shared UI**: browser components · Navigation and reusable tabular presentation.
- **Domain APIs**: backend boundary · UI-facing APIs for accounts, auth, reports, staff, and assignments.
- [Supabase client](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/supabase.js): connection setup · Environment-based browser connection boundary. · `src/lib/supabase.js`
- [Audit form](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/pages/audit/form.js): capture controller · Central visit outcome and evidence workflow. · `src/pages/audit/form.js`
- [Capture services](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/capture.js): capture APIs · Evidence, signatures, and geolocation handling. · `src/lib/capture.js`
- [Visit review](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/visitReview.js): review API · `src/lib/visitReview.js`

### Offline Pipeline

Deferred mutation handling for mobile work.

- [Offline state](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/offline.js): local persistence · Manages locally captured offline work. · `src/lib/offline.js`
- [Mutation outbox](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/outbox.js): queued mutations · Holds deferred audit-capable writes. · `src/lib/outbox.js`
- [Sync reconciler](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/src/lib/sync.js): connectivity sync · Replays queued work when connectivity returns. · `src/lib/sync.js`
- [Offline outbox design](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/docs/superpowers/specs/2026-07-07-offline-audit-outbox-design.md): design specification · Defines the audit outbox boundary. · `docs/superpowers/specs/2026-07-07-offline-audit-outbox-design.md`

### Supabase Backend

Durable data, security, storage, and privileged operations.

- [PostgreSQL audit model](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/schema.sql): durable data model · Immutable audit history and soft-archived customers. · `supabase/schema.sql`
- [Audit submit operations](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/submit-audit.sql): database operations · Audit-oriented persistence operations. · `supabase/submit-audit.sql`
- [RLS and storage security](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/rls.sql): access policy · Protects database rows and object storage. · `supabase/rls.sql`
- [Staff edge functions](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/supabase/functions/create-staff/index.ts): privileged server functions · Creates staff and resets staff passwords. · `supabase/functions/create-staff/index.ts`

### Native Containers

Capacitor hosts the web application on devices.

- [Capacitor packaging](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/capacitor.config.json): native bridge · Packages the Vite web runtime for devices. · `capacitor.config.json`
- [Android host](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/android/app/src/main/java/com/starbike/aacms/MainActivity.java): native container · `android/app/src/main/java/com/starbike/aacms/MainActivity.java`
- [iOS host](https://github.com/sbccorpitdept/starbikecorp-aacms/blob/main/ios/App/App/AppDelegate.swift): native container · `ios/App/App/AppDelegate.swift`

## Connections

- Vite route build → Page controllers: serves page routes
- Page controllers → Shared UI: renders shared UI
- Page controllers → Domain APIs: uses exclusively
- Audit form → Capture services: captures evidence
- Audit form → Visit review: reviews visits
- Audit form → Mutation outbox: queues offline mutations
- Capture services → Offline state: persists local work
- Offline state → Mutation outbox: supplies deferred writes
- Mutation outbox → Sync reconciler: drains when online
- Offline outbox design → Mutation outbox: specifies
- Domain APIs → Supabase client: connects through
- Sync reconciler → Supabase client: replays confirmed writes
- Supabase client → PostgreSQL audit model: queries and RPC
- Supabase client → RLS and storage security: is constrained by
- Audit submit operations → PostgreSQL audit model: persists audit trail
- Domain APIs → Staff edge functions: invokes privileged staff actions
- Capacitor packaging → Vite route build: packages web runtime
- Android host → Capacitor packaging: hosts
- iOS host → Capacitor packaging: hosts