A community based topic aggregation platform built on atproto
bretton.dev
1# [CLAUDE-BUILD.md](http://claude-build.md/)
2
3Project: 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.
4
5## Builder Mindset
6
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
12
13#### Human & LLM Readability Guidelines:
14
15- Descriptive Naming: Use full words over abbreviations (e.g., CommunityGovernance not CommGov)
16
17## atProto Essentials for Coves
18
19### Architecture
20
21- **PDS is Self-Contained**: Uses internal SQLite + CAR files (in Docker volume)
22- **PostgreSQL for AppView Only**: One database for Coves AppView indexing
23- **Don't Touch PDS Internals**: PDS manages its own storage, we just read from firehose
24- **Data Flow**: Client → PDS → Firehose → AppView → PostgreSQL
25
26### Always Consider:
27
28- [ ] **Identity**: Every action needs DID verification
29- [ ] **Record Types**: Define custom lexicons (e.g., `social.coves.post`, `social.coves.community`)
30- [ ] **Is it federated-friendly?** (Can other PDSs interact with it?)
31- [ ] **Does the Lexicon make sense?** (Would it work for other forums?)
32- [ ] **AppView only indexes**: We don't write to CAR files, only read from firehose
33
34## Security-First Building
35
36### Every Feature MUST:
37
38- [ ] **Validate all inputs** at the handler level
39- [ ] **Use parameterized queries** (never string concatenation)
40- [ ] **Check authorization** before any operation
41- [ ] **Limit resource access** (pagination, rate limits)
42- [ ] **Log security events** (failed auth, invalid inputs)
43- [ ] **Never log sensitive data** (passwords, tokens, PII)
44
45### Red Flags to Avoid:
46
47- `fmt.Sprintf` in SQL queries → Use parameterized queries
48- Missing `context.Context` → Need it for timeouts/cancellation
49- No input validation → Add it immediately
50- Error messages with internal details → Wrap errors properly
51- Unbounded queries → Add limits/pagination
52
53### "How should I structure this?"
54
551. One domain, one package
562. Interfaces for testability
573. Services coordinate repos
584. Handlers only handle XRPC
59
60## Pre-Production Advantages
61
62Since we're pre-production:
63
64- **Break things**: Delete and rebuild rather than complex migrations
65- **Experiment**: Try approaches, keep what works
66- **Simplify**: Remove unused code aggressively
67- **But never compromise security basics**
68
69## Success Metrics
70
71Your code is ready when:
72
73- [ ] Tests pass (including security tests)
74- [ ] Follows atProto patterns
75- [ ] Handles errors gracefully
76- [ ] Works end-to-end with auth
77
78## Quick Checks Before Committing
79
801. **Will it work?** (Integration test proves it)
812. **Is it secure?** (Auth, validation, parameterized queries)
823. **Is it simple?** (Could you explain to a junior?)
834. **Is it complete?** (Test, implementation, documentation)
84
85Remember: We're building a working product. Perfect is the enemy of shipped.