A community based topic aggregation platform built on atproto
bretton.dev
1Project:
2You are a distinguished developer helping build Coves, a forum like atProto social media platform (think reddit / lemmy).
3
4Human & LLM Readability Guidelines:
5- Clear Module Boundaries: Each feature is a self-contained module with explicit interfaces
6- Descriptive Naming: Use full words over abbreviations (e.g., CommunityGovernance not CommGov)
7- Structured Documentation: Each module includes purpose, dependencies, and example usage
8- Consistent Patterns: RESTful APIs, standard error handling, predictable data structures
9- Context-Rich Comments: Explain "why" not just "what" at decision points
10
11Core Principles:
12- When in doubt, choose the simpler implementation
13- Features are the enemy of shipping
14- A working tool today beats a perfect tool tomorrow
15
16Utilize existing tech stack
17- Before attempting to use an external tool, ensure it cannot be done via the current stack:
18- Go Chi (Web framework)
19- DB: PostgreSQL
20- atProto for federation & user identities
21
22## atProto Guidelines
23
24For comprehensive AT Protocol implementation details, see [ATPROTO_GUIDE.md](./ATPROTO_GUIDE.md).
25
26Key principles:
27- Utilize Bluesky's Indigo packages before building custom atProto functionality
28- Everything is XRPC - no separate REST API layer needed
29- Follow the two-database pattern: Repository (CAR files) and AppView (PostgreSQL)
30- Design for federation and data portability from the start
31
32# Architecture Guidelines
33
34## Required Layered Architecture
35Follow this strict separation of concerns:
36```
37Handler (XRPC) → Service (Business Logic) → Repository (Data Access) → Database
38```
39- Handlers: XRPC request/response only
40- Services: Business logic, uses both write/read repos
41- Write Repos: CAR store operations
42- Read Repos: AppView queries
43
44
45## Directory Structure
46
47For a detailed project structure with file-level details and implementation status, see [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md).
48
49The project follows a layered architecture with clear separation between:
50- **XRPC handlers** - atProto API layer
51 - Only handle XRPC concerns: parsing requests, formatting responses
52 - Delegate all business logic to services
53 - No direct database access
54- **Core business logic** - Domain services and models
55 - Contains all business logic
56 - Orchestrates between write and read repositories
57 - Manages transactions and complex operations
58- **Data repositories** - Split between CAR store writes and AppView reads
59 - **Write Repositories** (`internal/atproto/carstore/*_write_repo.go`)
60 - Modify CAR files (source of truth)
61- **Read Repositories** (`db/appview/*_read_repo.go`)
62 - Query denormalized PostgreSQL tables
63 - Optimized for performance
64
65## Strict Prohibitions
66- **NEVER** put SQL queries in handlers
67- **NEVER** import database packages in handlers
68- **NEVER** pass *sql.DB directly to handlers
69- **NEVER** mix business logic with XRPC concerns
70- **NEVER** bypass the service layer
71
72## Testing Requirements
73- Services must be easily mockable (use interfaces)
74- Integration tests should test the full stack
75- Unit tests should test individual layers in isolation
76
77Test File Naming:
78- Unit tests: `[file]_test.go` in same directory
79- Integration tests: `[feature]_integration_test.go` in tests/ directory
80
81## Claude Code Instructions
82
83### Code Generation Patterns
84When creating new features:
851. Generate interface first in core/[domain]/
862. Generate test file with failing tests
873. Generate implementation to pass tests
884. Generate handler with tests
895. Update routes in xrpc/routes/
90
91### Refactoring Checklist
92Before considering a feature complete:
93- All tests pass
94- No SQL in handlers
95- Services use interfaces only
96- Error handling follows patterns
97- API documented with examples
98
99## Database Migrations
100- Use golang-goose for version control
101- Migrations in db/migrations/
102- Never modify existing migrations
103- Always provide rollback migrations
104
105## Dependency Injection
106- Use constructor functions for all components
107- Pass interfaces, not concrete types
108- Wire dependencies in main.go or cmd/server/main.go
109
110Example dependency wiring:
111```go
112// main.go
113userWriteRepo := carstore.NewUserWriteRepository(carStore)
114userReadRepo := appview.NewUserReadRepository(db)
115userService := users.NewUserService(userWriteRepo, userReadRepo)
116userHandler := xrpc.NewUserHandler(userService)
117```
118
119## Error Handling
120- Define custom error types in core/errors/
121- Use error wrapping with context: fmt.Errorf("service: %w", err)
122- Services return domain errors, handlers translate to HTTP status codes
123- Never expose internal error details in API responses
124
125### Context7 Usage Guidelines:
126- Always check Context7 for best practices before implementing external integrations and packages
127- Use Context7 to understand proper error handling patterns for specific libraries
128- Reference Context7 for testing patterns with external dependencies
129- Consult Context7 for proper configuration patterns
130
131## XRPC Implementation
132
133For detailed XRPC patterns and Lexicon examples, see [ATPROTO_GUIDE.md](./ATPROTO_GUIDE.md#xrpc).
134
135### Key Points
136- All client interactions go through XRPC endpoints
137- Handlers validate against Lexicon schemas automatically
138- Queries are read-only, procedures modify repositories
139- Every endpoint must have a corresponding Lexicon definition
140
141Key note: we are pre-production, we do not need migration strategies, feel free to tear down and rebuild, however ensure to erase any unneeded data structures or code.