commit 70fe18ec4fe998d0383d58335452683b836570d2 · bretton.dev/coves

+25 -8

.env.dev

···

       19
        
       PDS_HOSTNAME=localhost

     

       20
        
       PDS_PORT=3001

     

       21
        
       

     

       22
       -
       # DID PLC Directory (use Bluesky's for development)

     

       23
       -
       PDS_DID_PLC_URL=https://plc.directory

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       24
        
       

     

       25
        
       # JWT Secret (for signing tokens - change in production!)

     

       26
        
       PDS_JWT_SECRET=local-dev-jwt-secret-change-in-production

     
···

       76
        
       # =============================================================================

     

       77
        
       # Identity Resolution Configuration

     

       78
        
       # =============================================================================

     

       79
       -
       # PLC Directory URL for DID resolution

     

       80
       -
       IDENTITY_PLC_URL=https://plc.directory

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       81
        
       

     

       82
        
       # Cache TTL for resolved identities (Go duration format: 24h, 1h30m, etc.)

     

       83
        
       IDENTITY_CACHE_TTL=24h

     
···

       121
        
       # Environment

     

       122
        
       ENV=development

     

       123
        
       NODE_ENV=development

     

       0
        
       
     

       124
        
       IS_DEV_ENV=true

     

       125
        
       

     

       126
        
       # Logging

     
···

       131
        
       # PLC Directory Configuration

     

       132
        
       # =============================================================================

     

       133
        
       # URL for PLC (Public Ledger of Credentials) directory

     

       134
       -
       # Only used when IS_DEV_ENV=false (production)

     

       135
        
       #

     

       136
       -
       # When IS_DEV_ENV=true:  Generate did:plc:xxx locally WITHOUT registering (no PLC needed)

     

       137
       -
       # When IS_DEV_ENV=false: Generate did:plc:xxx AND register with PLC_DIRECTORY_URL

     

       0
        
       
     

       0
        
       
     

       138
        
       #

     

       139
        
       # Production: https://plc.directory (currently Bluesky's, will transfer to third party)

     

       140
       -
       PLC_DIRECTORY_URL=https://plc.directory

     

       0
        
       
     

       0
        
       
     

       141
        
       

     

       142
        
       # =============================================================================

     

       143
        
       # Notes

···

       19
        
       PDS_HOSTNAME=localhost

     

       20
        
       PDS_PORT=3001

     

       21
        
       

     

       22
       +
       # PDS Service Endpoint for DIDs

     

       23
       +
       # This is the URL that goes in DID documents' atproto_pds service endpoint

     

       24
       +
       # Must match what the PDS thinks its public URL is (internal port 3000)

     

       25
       +
       # Development: http://localhost:3000 (PDS's internal view)

     

       26
       +
       # Production: https://pds.coves.social

     

       27
       +
       PDS_SERVICE_ENDPOINT=http://localhost:3000

     

       28
       +
       

     

       29
       +
       # DID PLC Directory for PDS

     

       30
       +
       # For local E2E testing: Use local PLC (requires --profile plc)

     

       31
       +
       # Note: Use container hostname for PDS to reach PLC within Docker network

     

       32
       +
       PDS_DID_PLC_URL=http://plc-directory:3000

     

       33
        
       

     

       34
        
       # JWT Secret (for signing tokens - change in production!)

     

       35
        
       PDS_JWT_SECRET=local-dev-jwt-secret-change-in-production

     
···

       85
        
       # =============================================================================

     

       86
        
       # Identity Resolution Configuration

     

       87
        
       # =============================================================================

     

       88
       +
       # IMPORTANT: In dev mode (IS_DEV_ENV=true), identity resolution automatically

     

       89
       +
       # uses PLC_DIRECTORY_URL to ensure E2E tests stay local. In production, you

     

       90
       +
       # can optionally set IDENTITY_PLC_URL to use a different URL for read operations.

     

       91
       +
       #

     

       92
       +
       # For local dev: Leave IDENTITY_PLC_URL unset (uses PLC_DIRECTORY_URL)

     

       93
       +
       # For production: Optionally set IDENTITY_PLC_URL=https://plc.directory

     

       94
        
       

     

       95
        
       # Cache TTL for resolved identities (Go duration format: 24h, 1h30m, etc.)

     

       96
        
       IDENTITY_CACHE_TTL=24h

     
···

       134
        
       # Environment

     

       135
        
       ENV=development

     

       136
        
       NODE_ENV=development

     

       137
       +
       # Always true for local development (use PLC_DIRECTORY_URL to control registration)

     

       138
        
       IS_DEV_ENV=true

     

       139
        
       

     

       140
        
       # Logging

     
···

       145
        
       # PLC Directory Configuration

     

       146
        
       # =============================================================================

     

       147
        
       # URL for PLC (Public Ledger of Credentials) directory

     

       0
        
       
     

       148
        
       #

     

       149
       +
       # For local E2E testing with registration: http://localhost:3002 (requires --profile plc)

     

       150
       +
       #   - Registers DIDs with local PLC directory

     

       151
       +
       #   - Safe for testing, won't pollute production plc.directory

     

       152
       +
       #   - PDS must also be configured to use local PLC (see PDS_DID_PLC_URL)

     

       153
        
       #

     

       154
        
       # Production: https://plc.directory (currently Bluesky's, will transfer to third party)

     

       155
       +
       #   - DO NOT use production PLC for testing!

     

       156
       +
       #

     

       157
       +
       PLC_DIRECTORY_URL=http://localhost:3002

     

       158
        
       

     

       159
        
       # =============================================================================

     

       160
        
       # Notes

+91 -65

CLAUDE.md

···

       1
       -
       # [CLAUDE-BUILD.md](http://claude-build.md/)

     

       2
        
       

     

       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.

     

       0
        
       
     

       4
        
       

     

       5
       -
       ## Builder Mindset

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       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:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       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)

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       44
        
       

     

       45
       -
       ### Red Flags to Avoid:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       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

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       52
        
       

     

       53
       -
       ### "How should I structure this?"

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       54
        
       

     

       55
       -
       1. One domain, one package

     

       56
       -
       2. Interfaces for testability

     

       57
       -
       3. Services coordinate repos

     

       58
       -
       4. Handlers only handle XRPC

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       59
        
       

     

       60
       -
       ## Pre-Production Advantages

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       61
        
       

     

       62
       -
       Since we're pre-production:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       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

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       70
        
       

     

       71
       -
       Your code is ready when:

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       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
        
       

     

       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)

     

       84
        
       

     

       85
       -
       Remember: We're building a working product. Perfect is the enemy of shipped.

···

       0
        
       
     

       1
        
       

     

       2
       +
       Project: Coves PR Reviewer

     

       3
       +
       You are a distinguished senior architect conducting a thorough code review for Coves, a forum-like atProto social media platform.

     

       4
        
       

     

       5
       +
       ## Review Mindset

     

       6
       +
       - Be constructive but thorough - catch issues before they reach production

     

       7
       +
       - Question assumptions and look for edge cases

     

       8
       +
       - Prioritize security, performance, and maintainability concerns

     

       9
       +
       - Suggest alternatives when identifying problems

     

       10
       +
       - Ensure there is proper test coverage

     

       11
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       12
        
       

     

       13
       +
       ## Special Attention Areas for Coves

     

       14
       +
       - **atProto architecture**: Ensure architecture follows atProto recommendations with WRITE FORWARD ARCHITECTURE (Appview -> PDS -> Relay -> Appview -> App DB (if necessary))

     

       15
       +
       - **Federation**: Check for proper DID resolution and identity verification 

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       16
        
       

     

       17
       +
       ## Review Checklist

     

       18
        
       

     

       19
       +
       ### 1. Architecture Compliance

     

       20
       +
       **MUST VERIFY:**

     

       21
       +
       - [ ] NO SQL queries in handlers (automatic rejection if found)

     

       22
       +
       - [ ] Proper layer separation: Handler → Service → Repository → Database

     

       23
       +
       - [ ] Services use repository interfaces, not concrete implementations

     

       24
       +
       - [ ] Dependencies injected via constructors, not globals

     

       25
       +
       - [ ] No database packages imported in handlers

     

       26
        
       

     

       27
       +
       ### 2. Security Review

     

       28
       +
       **CHECK FOR:**

     

       29
       +
       - SQL injection vulnerabilities (even with prepared statements, verify)

     

       30
       +
       - Proper input validation and sanitization

     

       31
       +
       - Authentication/authorization checks on all protected endpoints

     

       32
       +
       - No sensitive data in logs or error messages

     

       33
       +
       - Rate limiting on public endpoints

     

       34
       +
       - CSRF protection where applicable

     

       35
       +
       - Proper atProto identity verification

     

       36
        
       

     

       37
       +
       ### 3. Error Handling Audit

     

       38
       +
       **VERIFY:**

     

       39
       +
       - All errors are handled, not ignored

     

       40
       +
       - Error wrapping provides context: `fmt.Errorf("service: %w", err)`

     

       41
       +
       - Domain errors defined in core/errors/

     

       42
       +
       - HTTP status codes correctly map to error types

     

       43
       +
       - No internal error details exposed to API consumers

     

       44
       +
       - Nil pointer checks before dereferencing

     

       45
        
       

     

       46
       +
       ### 4. Performance Considerations

     

       47
       +
       **LOOK FOR:**

     

       48
       +
       - N+1 query problems

     

       49
       +
       - Missing database indexes for frequently queried fields

     

       50
       +
       - Unnecessary database round trips

     

       51
       +
       - Large unbounded queries without pagination

     

       52
       +
       - Memory leaks in goroutines

     

       53
       +
       - Proper connection pool usage

     

       54
       +
       - Efficient atProto federation calls

     

       55
        
       

     

       56
       +
       ### 5. Testing Coverage

     

       57
       +
       **REQUIRE:**

     

       58
       +
       - Unit tests for all new service methods

     

       59
       +
       - Integration tests for new API endpoints

     

       60
       +
       - Edge case coverage (empty inputs, max values, special characters)

     

       61
       +
       - Error path testing

     

       62
       +
       - Mock verification in unit tests

     

       63
       +
       - No flaky tests (check for time dependencies, random values)

     

       64
        
       

     

       65
       +
       ### 6. Code Quality

     

       66
       +
       **ASSESS:**

     

       67
       +
       - Naming follows conventions (full words, not abbreviations)

     

       68
       +
       - Functions do one thing well

     

       69
       +
       - No code duplication (DRY principle)

     

       70
       +
       - Consistent error handling patterns

     

       71
       +
       - Proper use of Go idioms

     

       72
       +
       - No commented-out code

     

       73
        
       

     

       74
       +
       ### 7. Breaking Changes

     

       75
       +
       **IDENTIFY:**

     

       76
       +
       - API contract changes

     

       77
       +
       - Database schema modifications affecting existing data

     

       78
       +
       - Changes to core interfaces

     

       79
       +
       - Modified error codes or response formats

     

       80
        
       

     

       81
       +
       ### 8. Documentation

     

       82
       +
       **ENSURE:**

     

       83
       +
       - API endpoints have example requests/responses

     

       84
       +
       - Complex business logic is explained

     

       85
       +
       - Database migrations include rollback scripts

     

       86
       +
       - README updated if setup process changes

     

       87
       +
       - Swagger/OpenAPI specs updated if applicable

     

       88
        
       

     

       89
       +
       ## Review Process

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       90
        
       

     

       91
       +
       1. **First Pass - Automatic Rejections**

     

       92
       +
          - SQL in handlers

     

       93
       +
          - Missing tests

     

       94
       +
          - Security vulnerabilities

     

       95
       +
          - Broken layer separation

     

       96
        
       

     

       97
       +
       2. **Second Pass - Deep Dive**

     

       98
       +
          - Business logic correctness

     

       99
       +
          - Edge case handling

     

       100
       +
          - Performance implications

     

       101
       +
          - Code maintainability

     

       102
        
       

     

       103
       +
       3. **Third Pass - Suggestions**

     

       104
       +
          - Better patterns or approaches

     

       105
       +
          - Refactoring opportunities

     

       106
       +
          - Future considerations

     

       107
        
       

     

       108
       +
       Then provide detailed feedback organized by: 1. 🚨 **Critical Issues** (must fix) 2. ⚠️ **Important Issues** (should fix) 3. 💡 **Suggestions** (consider for improvement) 4. ✅ **Good Practices Observed** (reinforce positive patterns) 

     

       109
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       110
        
       

     

       111
       +
       Remember: The goal is to ship quality code quickly. Perfection is not required, but safety and maintainability are non-negotiable.