Claim Events Repository
Component Detail
Description
Data access layer for the claim_events audit table. Inserts timestamped event records for every state transition and exposes ordered read access for timeline display. Ensures no event is ever deleted or mutated to preserve audit integrity.
claim-events-repository
Summaries
The Claim Events Repository provides the immutable audit trail that underpins organisational accountability and regulatory compliance for all expense claim decisions. By recording every state transition — including who acted, when, and why — the organisation gains a complete, tamper-proof history that can satisfy internal audit requirements and external reporting obligations such as Bufdir accountability standards. This audit capability directly reduces risk exposure in dispute resolution, as coordinators and administrators can always reconstruct the exact sequence of events for any claim. The immutability guarantee, which explicitly prevents deletion or modification of records, protects the organisation from data integrity challenges and supports trust in the platform's record-keeping.
This is a low-complexity component with a tightly scoped responsibility: insert and read records from the claim_events table. Development effort is minimal, and it can be delivered early in the sprint as a foundational dependency for the approval workflow and timeline display features. The key delivery consideration is ensuring the database schema enforces immutability at the row-level security (RLS) policy layer in Supabase, so that the application-level restriction on updates and deletes is backed by database-enforced constraints. The `bulkInsertEvents` interface should be tested under concurrent batch approval scenarios to verify there are no race conditions.
No external service dependencies means this component can be developed and unit tested in isolation with minimal integration risk.
This data-layer component wraps direct Supabase client calls to the `claim_events` table and enforces an append-only access pattern. The `insertEvent` method constructs a record containing `claim_id`, `actor_id`, `from_status`, `to_status`, `comment`, and a server-generated `created_at` timestamp — the timestamp should use `now()` at the database level rather than being passed from the client to prevent clock skew issues. `getEventsForClaim` must return results ordered ascending by `created_at` for correct timeline rendering. The `bulkInsertEvents` method should use a single `INSERT` statement with multiple value rows rather than looping individual inserts, to ensure atomicity within a transaction.
No `UPDATE` or `DELETE` wrappers should be exposed; Supabase RLS policies on the `claim_events` table must additionally deny these operations at the database level as a defence-in-depth measure.
Responsibilities
- Insert new claim_event records with actor, timestamp, status, and comment
- Fetch ordered event history for a given claim
- Prevent update and delete operations to preserve immutable audit log
- Support bulk event insertion for batch approval operations
Interfaces
insertEvent(claimId, actorId, fromStatus, toStatus, comment)
getEventsForClaim(claimId)
getLatestEvent(claimId)
bulkInsertEvents(events)
Relationships
Dependents (3)
Components that depend on this component
Used Integrations (1)
External integrations and APIs this component relies on