A community based topic aggregation platform built on atproto
bretton.dev
1package comments
2
3import "context"
4
5// Repository defines the data access interface for comments
6// Used by Jetstream consumer to index comments from firehose
7//
8// Architecture: Comments are written directly by clients to their PDS using
9// com.atproto.repo.createRecord/updateRecord/deleteRecord. This AppView indexes
10// comments from Jetstream for aggregation and querying.
11type Repository interface {
12 // Create inserts a new comment into the AppView database
13 // Called by Jetstream consumer after comment is created on PDS
14 // Idempotent: ON CONFLICT DO NOTHING for duplicate URIs
15 Create(ctx context.Context, comment *Comment) error
16
17 // Update modifies an existing comment's content fields
18 // Called by Jetstream consumer after comment is updated on PDS
19 // Preserves vote counts and created_at timestamp
20 Update(ctx context.Context, comment *Comment) error
21
22 // GetByURI retrieves a comment by its AT-URI
23 // Used for Jetstream UPDATE/DELETE operations and queries
24 GetByURI(ctx context.Context, uri string) (*Comment, error)
25
26 // Delete soft-deletes a comment (sets deleted_at)
27 // Called by Jetstream consumer after comment is deleted from PDS
28 Delete(ctx context.Context, uri string) error
29
30 // ListByRoot retrieves all comments in a thread (flat)
31 // Used for fetching entire comment threads on posts
32 ListByRoot(ctx context.Context, rootURI string, limit, offset int) ([]*Comment, error)
33
34 // ListByParent retrieves direct replies to a post or comment
35 // Used for building nested/threaded comment views
36 ListByParent(ctx context.Context, parentURI string, limit, offset int) ([]*Comment, error)
37
38 // CountByParent counts direct replies to a post or comment
39 // Used for showing reply counts in threading UI
40 CountByParent(ctx context.Context, parentURI string) (int, error)
41
42 // ListByCommenter retrieves all comments by a specific user
43 // Future: Used for user comment history
44 ListByCommenter(ctx context.Context, commenterDID string, limit, offset int) ([]*Comment, error)
45
46 // ListByParentWithHotRank retrieves direct replies to a post or comment with sorting and pagination
47 // Supports hot, top, and new sorting with cursor-based pagination
48 // Returns comments with author info hydrated and next page cursor
49 ListByParentWithHotRank(
50 ctx context.Context,
51 parentURI string,
52 sort string, // "hot", "top", "new"
53 timeframe string, // "hour", "day", "week", "month", "year", "all" (for "top" only)
54 limit int,
55 cursor *string,
56 ) ([]*Comment, *string, error)
57
58 // GetByURIsBatch retrieves multiple comments by their AT-URIs in a single query
59 // Returns map[uri]*Comment for efficient lookups
60 // Used for hydrating comment threads without N+1 queries
61 GetByURIsBatch(ctx context.Context, uris []string) (map[string]*Comment, error)
62
63 // GetVoteStateForComments retrieves the viewer's votes on a batch of comments
64 // Returns map[commentURI]*Vote for efficient lookups
65 // Future: Used when votes table is implemented
66 GetVoteStateForComments(ctx context.Context, viewerDID string, commentURIs []string) (map[string]interface{}, error)
67
68 // ListByParentsBatch retrieves direct replies to multiple parents in a single query
69 // Returns map[parentURI][]*Comment grouped by parent
70 // Used to prevent N+1 queries when loading nested replies
71 // Limits results per parent to avoid memory exhaustion
72 ListByParentsBatch(
73 ctx context.Context,
74 parentURIs []string,
75 sort string,
76 limitPerParent int,
77 ) (map[string][]*Comment, error)
78}