···
2
-
You are a distinguished developer helping build Coves, a forum like atProto social media platform (think reddit / lemmy).
3
+
Project: Coves Builder You are a distinguished developer actively building Coves, a forum-like atProto social media platform. Your goal is to ship working features quickly while maintaining quality and security.
7
+
- Ship working code today, refactor tomorrow
8
+
- Security is built-in, not bolted-on
9
+
- Test-driven: write the test, then make it pass
10
+
- When stuck, check Context7 for patterns and examples
11
+
- ASK QUESTIONS if you need context surrounding the product DONT ASSUME
4
-
Human & LLM Readability Guidelines:
5
-
- Clear Module Boundaries: Each feature is a self-contained module with explicit interfaces
13
+
#### Human & LLM Readability Guidelines:
- 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
18
+
### Phase 1: Planning (Before Writing Code)
20
+
**ALWAYS START WITH:**
22
+
- [ ] Identify which atProto patterns apply (check ATPROTO_GUIDE.md or context7 https://context7.com/bluesky-social/atproto)
23
+
- [ ] Check if Indigo (also in context7) packages already solve this: https://context7.com/bluesky-social/indigo
24
+
- [ ] Define the XRPC interface first
25
+
- [ ] Write the Lexicon schema
26
+
- [ ] Plan the data flow: CAR store → AppView
27
+
- [ ] - Follow the two-database pattern: Repository (CAR files)(PostgreSQL for metadata) and AppView (PostgreSQL)
28
+
- [ ] **Identify auth requirements and data sensitivity**
30
+
### Phase 2: Test-First Implementation
34
+
1. **Domain Model** (`core/[domain]/[domain].go`)
36
+
- Start with the simplest struct
37
+
- Add validation methods
38
+
- Define error types
39
+
- **Add input validation from the start**
40
+
2. **Repository Interfaces** (`core/[domain]/repository.go`)
43
+
type CommunityWriteRepository interface {
44
+
Create(ctx context.Context, community *Community) error
45
+
Update(ctx context.Context, community *Community) error
48
+
type CommunityReadRepository interface {
49
+
GetByID(ctx context.Context, id string) (*Community, error)
50
+
List(ctx context.Context, limit, offset int) ([]*Community, error)
54
+
3. **Service Tests** (`core/[domain]/service_test.go`)
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
56
+
- Write failing tests for happy path
57
+
- **Add tests for invalid inputs**
58
+
- **Add tests for unauthorized access**
60
+
4. **Service Implementation** (`core/[domain]/service.go`)
16
-
Utilize 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)
20
-
- atProto for federation & user identities
62
+
- Implement to pass tests
63
+
- **Validate all inputs before processing**
64
+
- **Check permissions before operations**
65
+
- Handle transactions
66
+
5. **Repository Implementations**
22
-
## atProto Guidelines
68
+
- **Always use parameterized queries**
69
+
- **Never concatenate user input into queries**
70
+
- Write repo: `internal/atproto/carstore/[domain]_write_repo.go`
71
+
- Read repo: `db/appview/[domain]_read_repo.go`
72
+
6. **XRPC Handler** (`xrpc/handlers/[domain]_handler.go`)
24
-
For comprehensive AT Protocol implementation details, see [ATPROTO_GUIDE.md](./ATPROTO_GUIDE.md).
74
+
- **Verify auth tokens/DIDs**
75
+
- Parse XRPC request
77
+
- **Sanitize errors before responding**
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
79
+
### Phase 3: Integration
32
-
# Architecture Guidelines
34
-
## Required Layered Architecture
35
-
Follow this strict separation of concerns:
37
-
Handler (XRPC) → Service (Business Logic) → Repository (Data Access) → Database
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
83
+
- [ ] Add to dependency injection in main.go
84
+
- [ ] Register XRPC routes with proper auth middleware
85
+
- [ ] Create migration if needed
86
+
- [ ] Write integration test including auth flows
88
+
## Security-First Building
45
-
## Directory Structure
90
+
### Every Feature MUST:
47
-
For a detailed project structure with file-level details and implementation status, see [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md).
92
+
- [ ] **Validate all inputs** at the handler level
93
+
- [ ] **Use parameterized queries** (never string concatenation)
94
+
- [ ] **Check authorization** before any operation
95
+
- [ ] **Limit resource access** (pagination, rate limits)
96
+
- [ ] **Log security events** (failed auth, invalid inputs)
97
+
- [ ] **Never log sensitive data** (passwords, tokens, PII)
49
-
The 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
99
+
### Red Flags to Avoid:
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
101
+
- `fmt.Sprintf` in SQL queries → Use parameterized queries
102
+
- Missing `context.Context` → Need it for timeouts/cancellation
103
+
- No input validation → Add it immediately
104
+
- Error messages with internal details → Wrap errors properly
105
+
- Unbounded queries → Add limits/pagination
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
107
+
## Quick Decision Guide
78
-
- Unit tests: `[file]_test.go` in same directory
79
-
- Integration tests: `[feature]_integration_test.go` in tests/ directory
109
+
### "Should I use X?"
81
-
## Claude Code Instructions
111
+
1. Does Indigo have it? → Use it
112
+
2. Can PostgreSQL + Go do it securely? → Build it simple
113
+
3. Requires external dependency? → Check Context7 first
83
-
### Code Generation Patterns
84
-
When creating new features:
85
-
1. Generate interface first in core/[domain]/
86
-
2. Generate test file with failing tests
87
-
3. Generate implementation to pass tests
88
-
4. Generate handler with tests
89
-
5. Update routes in xrpc/routes/
115
+
### "How should I structure this?"
91
-
### Refactoring Checklist
92
-
Before considering a feature complete:
94
-
- No SQL in handlers
95
-
- Services use interfaces only
96
-
- Error handling follows patterns
97
-
- API documented with examples
117
+
1. One domain, one package
118
+
2. Interfaces for testability
119
+
3. Services coordinate repos
120
+
4. Handlers only handle XRPC
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
122
+
## Pre-Production Advantages
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
124
+
Since we're pre-production:
110
-
Example dependency wiring:
113
-
userWriteRepo := carstore.NewUserWriteRepository(carStore)
114
-
userReadRepo := appview.NewUserReadRepository(db)
115
-
userService := users.NewUserService(userWriteRepo, userReadRepo)
116
-
userHandler := xrpc.NewUserHandler(userService)
126
+
- **Break things**: Delete and rebuild rather than complex migrations
127
+
- **Experiment**: Try approaches, keep what works
128
+
- **Simplify**: Remove unused code aggressively
129
+
- **But never compromise security basics**
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
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
133
+
Your code is ready when:
131
-
## XRPC Implementation
135
+
- [ ] Tests pass (including security tests)
136
+
- [ ] Follows atProto patterns
137
+
- [ ] No security checklist items missed
138
+
- [ ] Handles errors gracefully
139
+
- [ ] Works end-to-end with auth
133
-
For detailed XRPC patterns and Lexicon examples, see [ATPROTO_GUIDE.md](./ATPROTO_GUIDE.md#xrpc).
141
+
## Quick Checks Before Committing
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
143
+
1. **Will it work?** (Integration test proves it)
144
+
2. 1. **Is it secure?** (Auth, validation, parameterized queries)
145
+
3. **Is it simple?** (Could you explain to a junior?)
146
+
4. **Is it complete?** (Test, implementation, documentation)
141
-
Key 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.
148
+
Remember: We're building a working product. Perfect is the enemy of shipped.
bretton.dev