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).
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# Architecture Guidelines
23
24## Required Layered Architecture
25Follow this strict separation of concerns:
26```
27Handler (HTTP) → Service (Business Logic) → Repository (Data Access) → Database
28```
29
30## Directory Structure
31```
32internal/
33├── api/
34│ ├── handlers/ # HTTP request/response handling ONLY
35│ └── routes/ # Route definitions
36├── core/
37│ └── [domain]/ # Business logic, domain models, service interfaces
38│ ├── service.go # Business logic implementation
39│ ├── repository.go # Data access interface
40│ └── [domain].go # Domain models
41└── db/
42 └── postgres/ # Database implementation details
43 └── [domain]_repo.go # Repository implementations
44```
45
46## Strict Prohibitions
47- **NEVER** put SQL queries in handlers
48- **NEVER** import database packages in handlers
49- **NEVER** pass *sql.DB directly to handlers
50- **NEVER** mix business logic with HTTP concerns
51- **NEVER** bypass the service layer
52
53## Required Patterns
54
55### Handlers (HTTP Layer)
56- Only handle HTTP concerns: parsing requests, formatting responses
57- Delegate all business logic to services
58- No direct database access
59
60Example:
61```go
62func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
63 var req CreateUserRequest
64 json.NewDecoder(r.Body).Decode(&req)
65
66 user, err := h.userService.CreateUser(req) // Delegate to service
67 // Handle response formatting only
68}
69```
70
71### Services (Business Layer)
72- Contain all business logic and validation
73- Use repository interfaces, never concrete implementations
74- Handle transactions and complex operations
75
76Example:
77```go
78type UserService struct {
79 userRepo UserRepository // Interface, not concrete type
80}
81```
82
83### Repositories (Data Layer)
84- Define interfaces in core/[domain]/
85- Implement in db/postgres/
86- Handle all SQL queries and database operations
87
88Example:
89```go
90// Interface in core/users/repository.go
91type UserRepository interface {
92 Create(user User) (*User, error)
93 GetByID(id int) (*User, error)
94}
95
96// Implementation in db/postgres/user_repo.go
97type PostgresUserRepo struct {
98 db *sql.DB
99}
100```
101
102## Testing Requirements
103- Services must be easily mockable (use interfaces)
104- Integration tests should test the full stack
105- Unit tests should test individual layers in isolation
106
107Test File Naming:
108- Unit tests: `[file]_test.go` in same directory
109- Integration tests: `[feature]_integration_test.go` in tests/ directory
110
111## Claude Code Instructions
112
113### Code Generation Patterns
114When creating new features:
1151. Generate interface first in core/[domain]/
1162. Generate test file with failing tests
1173. Generate implementation to pass tests
1184. Generate handler with tests
1195. Update routes in api/routes/
120
121### Refactoring Checklist
122Before considering a feature complete:
123- All tests pass
124- No SQL in handlers
125- Services use interfaces only
126- Error handling follows patterns
127- API documented with examples
128
129## Database Migrations
130- Use golang-goose for version control
131- Migrations in db/migrations/
132- Never modify existing migrations
133- Always provide rollback migrations
134
135
136
137## Dependency Injection
138- Use constructor functions for all components
139- Pass interfaces, not concrete types
140- Wire dependencies in main.go or cmd/server/main.go
141
142Example dependency wiring:
143```go
144// main.go
145userRepo := postgres.NewUserRepository(db)
146userService := users.NewUserService(userRepo)
147userHandler := handlers.NewUserHandler(userService)
148```
149
150## Error Handling
151- Define custom error types in core/errors/
152- Use error wrapping with context: fmt.Errorf("service: %w", err)
153- Services return domain errors, handlers translate to HTTP status codes
154- Never expose internal error details in API responses
155
156### Context7 Usage Guidelines:
157- Always check Context7 for best practices before implementing external integrations
158- Use Context7 to understand proper error handling patterns for specific libraries
159- Reference Context7 for testing patterns with external dependencies
160- Consult Context7 for proper configuration patterns