chadtmiller.com / pds.js
A zero-dependency AT Protocol Personal Data Server written in JavaScript
atproto pds
fork atom
pds.js / docs / plans / 2026-01-06-pds-file-reorganization.md
at main 16 kB view raw view code

PDS File Reorganization Implementation Plan#

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Reorganize pds.js into logical domain sections with box-style headers for improved readability.

Architecture: Reorder existing code into 12 logical domains without changing functionality. Add Unicode box-style section headers. Group related utilities that are currently scattered.

Tech Stack: JavaScript, JSDoc

Box Header Format#

All section headers use this format (80 chars wide):

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ SECTION NAME                                                                 ║
// ║ Brief description of what this section contains                              ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Task 1: Types & Constants Section#

Files:

  • Modify: src/pds.js (lines 17-84, plus scattered constants)

Step 1: Create the new section header and gather all types/constants

Move these items to the top (after the file header comment):

  • CBOR_FALSE, CBOR_TRUE, CBOR_NULL, CBOR_TAG_CID (from lines 19-24)
  • CODEC_DAG_CBOR, CODEC_RAW (from lines 480-481)
  • TID_CHARS, clockId, lastTimestamp (from lines 563-566)
  • P256_N, P256_N_DIV_2 (from lines 638-641)
  • All typedefs: Env, BlockRow, RecordRow, CommitRow, SeqEventRow, BlobRow, JwtPayload

Add header:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ TYPES & CONSTANTS                                                            ║
// ║ Environment bindings, SQL row types, protocol constants                      ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck to verify no breakage

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: consolidate types and constants section"

Task 2: Utilities Section#

Files:

  • Modify: src/pds.js

Step 1: Create utilities section after types/constants

Move these functions together:

  • errorResponse() (from line 92)
  • bytesToHex() (from line 990)
  • hexToBytes() (from line 1001)
  • bytesToBigInt() (from line 647)
  • bigIntToBytes() (from line 660)
  • base32Encode() (from line 538)
  • base32Decode() (from line 1237)
  • base64UrlEncode() (from line 745)
  • base64UrlDecode() (from line 759)
  • varint() (from line 1211)

Add header:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ UTILITIES                                                                    ║
// ║ Error responses, byte conversion, base encoding                              ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: consolidate utilities section"

Task 3: CBOR Encoding Section#

Files:

  • Modify: src/pds.js

Step 1: Create CBOR section

Keep together (already grouped, just add new header):

  • encodeHead()
  • cborEncode()
  • cborEncodeDagCbor()
  • cborDecode()

Replace // === CBOR ENCODING === with:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CBOR ENCODING                                                                ║
// ║ RFC 8949 CBOR and DAG-CBOR for content-addressed data                        ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: add CBOR encoding section header"

Task 4: Content Identifiers Section#

Files:

  • Modify: src/pds.js

Step 1: Create CID/TID section

Group together:

  • class CID (from line 238)
  • createCidWithCodec() (from line 489)
  • createCid() (from line 510)
  • createBlobCid() (from line 519)
  • cidToString() (from line 528)
  • cidToBytes() (from line 1226)
  • createTid() (from line 572)

Add header:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CONTENT IDENTIFIERS                                                          ║
// ║ CIDs (content hashes) and TIDs (timestamp IDs)                               ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: consolidate content identifiers section"

Task 5: Cryptography Section#

Files:

  • Modify: src/pds.js

Step 1: Create cryptography section

Group together:

  • sha256() (from line 1016)
  • importPrivateKey() (from line 606)
  • generateKeyPair() (from line 705)
  • compressPublicKey() (from line 728)
  • sign() (from line 675)

Add header:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CRYPTOGRAPHY                                                                 ║
// ║ P-256 signing with low-S normalization, key management                       ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: create cryptography section"

Task 6: Authentication Section#

Files:

  • Modify: src/pds.js

Step 1: Create authentication section

Group together:

  • hmacSign() (from line 777)
  • createAccessJwt() (from line 800)
  • createRefreshJwt() (from line 829)
  • verifyJwt() (from line 876)
  • verifyAccessJwt() (from line 919)
  • verifyRefreshJwt() (from line 931)
  • createServiceJwt() (from line 952)

Add header:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ AUTHENTICATION                                                               ║
// ║ JWT creation/verification for sessions and service auth                      ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: create authentication section"

Task 7: Merkle Search Tree Section#

Files:

  • Modify: src/pds.js

Step 1: Update MST section header

Keep together (already grouped):

  • keyDepthCache
  • getKeyDepth()
  • commonPrefixLen()
  • class MST

Replace // === MERKLE SEARCH TREE === with:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ MERKLE SEARCH TREE                                                           ║
// ║ MST for ATProto repository structure                                         ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: update MST section header"

Task 8: CAR Files Section#

Files:

  • Modify: src/pds.js

Step 1: Update CAR section

Keep only:

  • buildCarFile()

(Note: varint(), cidToBytes(), base32Decode() moved to earlier sections)

Replace // === CAR FILE BUILDER === with:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ CAR FILES                                                                    ║
// ║ Content Addressable aRchive format for repo sync                             ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: update CAR files section"

Task 9: Blob Handling Section#

Files:

  • Modify: src/pds.js

Step 1: Create blob handling section

Group together:

  • sniffMimeType() (from line 105)
  • findBlobRefs() (from line 181)
  • CRAWL_NOTIFY_THRESHOLD, lastCrawlNotify (from lines 207-208)
  • notifyCrawlers() (from line 214)

Add header:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ BLOB HANDLING                                                                ║
// ║ MIME detection, blob reference scanning, crawler notification                ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: create blob handling section"

Task 10: Routing Section#

Files:

  • Modify: src/pds.js

Step 1: Add routing section header

Before RouteHandler callback typedef, add:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ ROUTING                                                                      ║
// ║ XRPC endpoint definitions                                                    ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

This section contains:

  • RouteHandler (callback typedef)
  • Route (typedef)
  • pdsRoutes

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: add routing section header"

Task 11: Personal Data Server Section#

Files:

  • Modify: src/pds.js

Step 1: Add PDS class section header

Before class PersonalDataServer, add:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ PERSONAL DATA SERVER                                                         ║
// ║ Durable Object class implementing ATProto PDS                                ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: add PDS class section header"

Task 12: Workers Entry Point Section#

Files:

  • Modify: src/pds.js

Step 1: Add workers entry point section header

Before corsHeaders, add:

// ╔══════════════════════════════════════════════════════════════════════════════╗
// ║ WORKERS ENTRY POINT                                                          ║
// ║ Request handling, CORS, auth middleware                                      ║
// ╚══════════════════════════════════════════════════════════════════════════════╝

This section contains:

  • corsHeaders
  • addCorsHeaders()
  • getSubdomain()
  • requireAuth()
  • handleAuthenticatedBlobUpload()
  • handleAuthenticatedRepoWrite()
  • handleRequest()
  • default export

Step 2: Run typecheck

Run: npm run typecheck Expected: 0 errors

Step 3: Commit

git add src/pds.js
git commit -m "refactor: add workers entry point section header"

Task 13: Final Verification#

Step 1: Run full typecheck

Run: npm run typecheck Expected: 0 errors

Step 2: Run tests

Run: npm test Expected: All tests pass

Step 3: Run e2e tests if available

Run: npm run test:e2e Expected: All tests pass

Step 4: Final commit if any cleanup needed

git add src/pds.js
git commit -m "refactor: complete pds.js reorganization with box headers"

Section Order Summary#

Final file structure (top to bottom):

  1. File header comment
  2. TYPES & CONSTANTS
  3. UTILITIES
  4. CBOR ENCODING
  5. CONTENT IDENTIFIERS
  6. CRYPTOGRAPHY
  7. AUTHENTICATION
  8. MERKLE SEARCH TREE
  9. CAR FILES
  10. BLOB HANDLING
  11. ROUTING
  12. PERSONAL DATA SERVER
  13. WORKERS ENTRY POINT