How sbccorpitdept/starbikecorp-aacms works
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: supabase.js Supabase client · outbox.js Mutation outbox · form.js Audit form · capacitor.config.json Capacitor packaging
Components 19
Browser Application
Vite-served multi-page staff application.
- Vite route build · Registers the root HTML page inputs.
vite.config.js - Page controllers · Dashboard, audit, admin, reports, and itinerary workflows.
- Shared UI · Navigation and reusable tabular presentation.
- Domain APIs · UI-facing APIs for accounts, auth, reports, staff, and assignments.
- Supabase client · Environment-based browser connection boundary.
src/lib/supabase.js - Audit form · Central visit outcome and evidence workflow.
src/pages/audit/form.js - Capture services · Evidence, signatures, and geolocation handling.
src/lib/capture.js - Visit review
src/lib/visitReview.js
Offline Pipeline
Deferred mutation handling for mobile work.
- Offline state · Manages locally captured offline work.
src/lib/offline.js - Mutation outbox · Holds deferred audit-capable writes.
src/lib/outbox.js - Sync reconciler · Replays queued work when connectivity returns.
src/lib/sync.js - Offline outbox design · 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 · Immutable audit history and soft-archived customers.
supabase/schema.sql - Audit submit operations · Audit-oriented persistence operations.
supabase/submit-audit.sql - RLS and storage security · Protects database rows and object storage.
supabase/rls.sql - Staff edge functions · Creates staff and resets staff passwords.
supabase/functions/create-staff/index.ts
Native Containers
Capacitor hosts the web application on devices.
- Capacitor packaging · Packages the Vite web runtime for devices.
capacitor.config.json - Android host
android/app/src/main/java/com/starbike/aacms/MainActivity.java - iOS host
ios/App/App/AppDelegate.swift
Connections 19
- 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