nandi.uk
This repository has no description
1# Firehose Event Handlers Implementation Guide - Reusing Existing Use Cases
2
3## Overview
4
5This implementation reuses existing use cases as much as possible for handling firehose events. The key insight is that firehose events represent already-published records, so we need to skip the publishing step and use the provided AT URI + CID as the published record ID.
6
7## Architecture Approach
8
91. **Reuse existing use cases** - Leverage existing business logic in use cases
102. **Skip publishing for firehose events** - Add optional `publishedRecordId` parameter to use cases
113. **Use AT URI resolution** - Convert AT URIs from firehose events to domain entities
124. **Minimal changes** - Keep modifications as simple as possible
13
14## Implementation Strategy
15
16### Core Pattern
17
18Each firehose processor will:
19
201. Parse the AT URI and extract relevant data from the record
212. Use `IAtUriResolutionService` to resolve AT URIs to domain entities
223. Call existing use cases with an optional `publishedRecordId` parameter
234. When `publishedRecordId` is provided, skip publishing and use that ID for marking as published
24
25### Use Case Modifications
26
27Add optional `publishedRecordId?: PublishedRecordId` parameter to these use cases:
28
29- `AddUrlToLibraryUseCase`
30- `CreateCollectionUseCase`
31- `UpdateCollectionUseCase`
32- `DeleteCollectionUseCase`
33- `RemoveCardFromLibraryUseCase`
34
35For `UpdateUrlCardAssociationsUseCase`, we'll need a more complex approach since it handles multiple operations. We'll add optional parameters for collection link published record IDs.
36
37## Event Handling Implementation
38
39### URL Card Events
40
41#### Create
42
43- Extract URL and curator DID from record
44- Call `AddUrlToLibraryUseCase` with `publishedRecordId` from event
45
46#### Update
47
48- Skip for now (URL cards don't typically update)
49
50#### Delete
51
52- Resolve AT URI to card ID
53- Call `RemoveCardFromLibraryUseCase` with `publishedRecordId` to skip unpublishing
54
55### Note Card Events
56
57#### Create/Update
58
59- Extract parent card AT URI, note text, and curator DID
60- Resolve parent card AT URI to card ID
61- Call `UpdateUrlCardAssociationsUseCase` with note and `publishedRecordId`
62
63#### Delete
64
65- Resolve AT URI to card ID
66- Verify it's a note card
67- Call `RemoveCardFromLibraryUseCase` with `publishedRecordId`
68
69### Collection Events
70
71#### Create
72
73- Extract name, description, curator DID from record
74- Call `CreateCollectionUseCase` with `publishedRecordId` from event
75
76#### Update
77
78- Resolve AT URI to collection ID
79- Extract updated fields from record
80- Call `UpdateCollectionUseCase` with `publishedRecordId`
81
82#### Delete
83
84- Resolve AT URI to collection ID
85- Call `DeleteCollectionUseCase` with `publishedRecordId` to skip unpublishing
86
87### Collection Link Events
88
89#### Create
90
91- Extract collection and card strong refs from record
92- Resolve AT URIs to collection ID and card ID
93- Call `UpdateUrlCardAssociationsUseCase` with `addToCollections` and link `publishedRecordId`
94
95#### Delete
96
97- Extract collection and card strong refs from record
98- Resolve AT URIs to collection ID and card ID
99- Call `UpdateUrlCardAssociationsUseCase` with `removeFromCollections` and link `publishedRecordId`
100
101## Key Benefits
102
1031. **Reuses existing business logic** - No duplication of validation and domain rules
1042. **Minimal code changes** - Just add optional parameters to existing use cases
1053. **Consistent behavior** - Same validation and error handling as normal operations
1064. **Simple to test** - Can test firehose handling by calling existing use cases with mock data
107
108## Files to Modify
109
110### Use Cases (add optional publishedRecordId parameter):
111
112- `AddUrlToLibraryUseCase.ts`
113- `CreateCollectionUseCase.ts`
114- `UpdateCollectionUseCase.ts`
115- `DeleteCollectionUseCase.ts`
116- `RemoveCardFromLibraryUseCase.ts`
117- `UpdateUrlCardAssociationsUseCase.ts` (more complex - add collection link published record IDs)
118
119### Firehose Processors (simplify to call existing use cases):
120
121- `ProcessCardFirehoseEventUseCase.ts`
122- `ProcessCollectionFirehoseEventUseCase.ts`
123- `ProcessCollectionLinkFirehoseEventUseCase.ts`
124
125### Services (add mapping storage methods):
126
127- `IAtUriResolutionService.ts` (already has the methods we need)
128
129This approach maintains clean separation of concerns while maximizing code reuse and minimizing the complexity of firehose event handling.