Batch Insert RPC Adapter
Component Detail
Description
Thin adapter wrapping the Supabase RPC function responsible for atomically inserting multiple activity rows in a single database call. Handles serialization of the batch payload, invocation of the RPC endpoint, and deserialization of per-row results, shielding the bulk registration service from Supabase-specific details.
batch-insert-rpc-adapter
Summaries
The Batch Insert RPC Adapter ensures that activity registrations are recorded reliably and efficiently in a single atomic operation, eliminating the risk of partial data loss when logging multiple sessions simultaneously. By consolidating database writes, this component reduces operational costs associated with failed or duplicate submissions, protects the integrity of reimbursement calculations, and ensures peer mentors are accurately compensated. Its built-in duplicate detection prevents erroneous payouts, directly reducing financial risk. The adapter also insulates the application from vendor-specific database changes, reducing long-term maintenance costs and vendor lock-in risk.
This medium-complexity adapter sits at the boundary between application logic and the Supabase database layer. It has no external dependencies, making it a self-contained deliverable with low integration risk. However, its correct functioning is a hard dependency for the bulk registration feature — any delays here directly block end-to-end testing of activity logging.
Key delivery considerations include RPC function availability in the Supabase project, authentication context setup for test environments, and thorough testing of constraint violation scenarios such as duplicate activity detection. Estimate 3–5 days for implementation and unit testing, plus additional time for integration testing against a staging Supabase instance.
The Batch Insert RPC Adapter is a thin anti-corruption layer that wraps a Supabase RPC endpoint for atomic multi-row activity insertion. It exposes `executeBatchInsert(activities)` as the primary entry point, internally calling `serializeBatchPayload()` to transform the domain activity list into the Supabase RPC-compatible wire format, then invoking the RPC via the Supabase client with the correct auth context. The `deserializeRpcResponse()` method maps per-row success/failure results back to domain objects. Constraint violations (e.g., duplicate activity rows) are caught in `handleConstraintViolation()` and surfaced as structured domain errors rather than raw Supabase exceptions.
`getInsertedIds()` extracts the newly created row IDs from the response for downstream use. The adapter operates in both mobile (Flutter Supabase client) and backend contexts. Maintenance focus should be on keeping serialization aligned with any schema changes to the `activity` data model.
Responsibilities
- Serialize list of activity payloads into Supabase RPC-compatible format
- Invoke Supabase RPC batch-insert function with proper authentication context
- Deserialize RPC response into per-mentor success/failure results
- Surface database constraint violations (duplicate detection at DB level) as structured errors
Interfaces
executeBatchInsert(activities)
serializeBatchPayload(activities)
deserializeRpcResponse(response)
handleConstraintViolation(error)
getInsertedIds(response)
Relationships
Dependents (2)
Components that depend on this component