Skip to main content

Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Concurrency and Locking Strategy

In a multi-tenant platform where multiple team members may be working on the same grant pursuit simultaneously, managing race conditions is critical to data integrity.

​
🏗️ Locking Lifecycle Visual

​
🏗️ Optimistic Concurrency Control (OCC)

We primarily use Optimistic Updates on the frontend combined with Firestore Transactions on the backend.

​
1. Frontend Optimism

When a user updates a status or title, the UI updates immediately using the local listenerManager cache. If the server fails, the UI rolls back.

​
2. Backend Transactions

For critical operations (e.g., claiming a grant), we use Firestore transactions:
  • The function reads the current state of the document.
  • It performs the increment or status change.
  • It commits only if the document hasn’t changed during the read/write window.

​
🔒 Document Locking (Soft Locking)

For critical long-form editing (like drafting a grant application), we implement Soft Locking:

​
1. The Lease System

  • Acquisition: Entering the “Edit Mode” creates a _lock field in Firestore with uid, timestamp, and expiresAt (5 minutes from now).
  • Heartbeat: The frontend sends a “pulse” every 60 seconds to extend the lease.
  • Implicit Release: If the user closes the tab without saving, the heartbeat stops, and the lock naturally expires in 5 minutes.

​
2. Collision Handling

When a second user tries to edit a locked document:
  • They see a “Currently being edited by [User]” banner.
  • The “Save” button is disabled.
  • They can still view the content in real-time as the first user types (via Firestore listeners).

​
🛠️ Implementation Details

Lock logic is centralized in src/shared/locking/lockManager.ts. 
// Example usage in a component
const { isLocked, owner, releaseLock } = useLock(`grants/${grantId}`);

​
🚨 Edge Cases

  • Network Failure: If the editor loses internet, the heartbeat fails. After 5 minutes, another user can claim the lock. The original user is notified to “Reconnect to continue editing.”
  • SuperAdmin Override: SuperAdmins have a “Force Unlock” capability to clear stuck sessions.