···
1
-
# [CLAUDE-BUILD.md](http://claude-build.md/)
1
+
# Coves Mobile - Developer Guide
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.
3
+
Project: Coves Builder You are a distinguished developer actively building a cross-platform iOS/Android client for Coves, a forum-like atProto social media platform. Ship working features quickly while maintaining quality and security.
5
+
## Mobile Builder Mindset
7
-
- Ship working code today, refactor tomorrow
7
+
- Ship working features today, refactor tomorrow
- 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
9
+
- Test on real devices, not just simulators
10
+
- When stuck, check official Expo/React Native docs
11
+
- ASK QUESTIONS about product requirements - DON'T ASSUME
13
-
#### Human & LLM Readability Guidelines:
13
+
## Tech Stack Essentials
15
-
- Descriptive Naming: Use full words over abbreviations (e.g., CommunityGovernance not CommGov)
15
+
**Framework**: Expo + React Native + TypeScript
16
+
**Navigation**: Expo Router (file-based routing)
17
+
**Auth**: @atproto/oauth-client-expo (official Bluesky OAuth)
18
+
**State**: Zustand + TanStack Query
19
+
**UI**: NativeWind (Tailwind CSS for RN)
20
+
**Storage**: MMKV (encrypted), AsyncStorage (persistence)
17
-
## atProto Essentials for Coves
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
22
+
## atProto Mobile Patterns
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
25
+
- [ ] **Session management**: Does it persist across app restarts?
26
+
- [ ] **Deep linking**: Do both HTTPS and custom schemes work?
27
+
- [ ] **Token refresh**: Does the Agent handle expired tokens?
28
+
- [ ] **Offline state**: What happens with no network?
29
+
- [ ] **Platform differences**: Does it work on both iOS and Android?
34
-
## Security-First Building
31
+
## Security-First Mobile Development
34
+
- [ ] **Validate inputs** before API calls
35
+
- [ ] **Handle auth errors** gracefully (expired sessions, network failures)
36
+
- [ ] **Never log tokens** or sensitive user data
37
+
- [ ] **Use secure storage** (MMKV for tokens, not AsyncStorage)
38
+
- [ ] **Check permissions** before accessing device features
39
+
- [ ] **Handle background state** (app pause/resume)
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)
41
+
### Mobile-Specific Red Flags:
42
+
- Storing tokens in AsyncStorage → Use MMKV encrypted storage
43
+
- No error boundaries → Wrap screens in ErrorBoundary
44
+
- No loading states → Users see blank screens
45
+
- Missing keyboard handling → Input fields hidden on focus
46
+
- Unbounded lists → Use FlatList/virtualization for performance
47
+
- Missing deep link handling → OAuth callbacks will fail
45
-
### Red Flags to Avoid:
49
+
## Project Structure Rules
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
51
+
- **app/**: Expo Router screens (file = route)
52
+
- **lib/**: Shared utilities (OAuth client, API wrapper)
53
+
- **stores/**: Zustand state (keep minimal, prefer TanStack Query)
54
+
- **components/**: Reusable UI components
55
+
- **constants/**: Config values (never hardcode URLs)
53
-
### "How should I structure this?"
57
+
### Component Guidelines:
58
+
- One component per file
59
+
- Props with TypeScript interfaces
60
+
- Handle loading/error states in every component
61
+
- Use className for styling (NativeWind)
55
-
1. One domain, one package
56
-
2. Interfaces for testability
57
-
3. Services coordinate repos
58
-
4. Handlers only handle XRPC
63
+
## React Native Best Practices
65
+
- Use FlatList for any list over 20 items
66
+
- Memoize expensive computations with useMemo
67
+
- Debounce search inputs to avoid excessive API calls
68
+
- Test keyboard behavior on both platforms
69
+
- Use SafeAreaView for proper notch/home indicator handling
70
+
- Handle orientation changes (or lock orientation)
## Pre-Production Advantages
Since we're pre-production:
64
-
- **Break things**: Delete and rebuild rather than complex migrations
65
-
- **Experiment**: Try approaches, keep what works
75
+
- **Break things**: Delete screens and rebuild rather than complex refactors
76
+
- **Experiment**: Try UI patterns, keep what works
- **Simplify**: Remove unused code aggressively
67
-
- **But never compromise security basics**
78
+
- **But never compromise**: Security, accessibility, error handling
71
-
Your code is ready when:
73
-
- [ ] Tests pass (including security tests)
74
-
- [ ] Follows atProto patterns
75
-
- [ ] Handles errors gracefully
76
-
- [ ] Works end-to-end with auth
82
+
Your feature is ready when:
83
+
- [ ] Works on both iOS and Android (physical devices)
84
+
- [ ] Handles offline/error states gracefully
85
+
- [ ] Auth session persists across app restarts
86
+
- [ ] No console warnings or errors
87
+
- [ ] Loading states prevent user confusion
88
+
- [ ] TypeScript compiles without errors
## Quick Checks Before Committing
80
-
1. **Will it work?** (Integration test proves it)
81
-
2. **Is it secure?** (Auth, validation, parameterized queries)
82
-
3. **Is it simple?** (Could you explain to a junior?)
83
-
4. **Is it complete?** (Test, implementation, documentation)
92
+
1. **Will it work?** (Test on real device, not just simulator)
93
+
2. **Is it secure?** (No tokens in logs, proper storage)
94
+
4. **Does it handle errors?** (Network fails, tokens expire)
95
+
5. **Is it complete?** (Loading states, error boundaries, TypeScript types)
85
-
Remember: We're building a working product. Perfect is the enemy of shipped.
97
+
Remember: Mobile users expect instant feedback and graceful degradation. Perfect is the enemy of shipped.
bretton.dev