chadtmiller.com/pds.js

Switch repository

Loading…

# README and Documentation Update

## Overview

Update README and setup documentation to reflect multi-platform support (Node.js and Cloudflare Workers).

## Design Decisions

- **Tagline**: Platform-agnostic ("A minimal AT Protocol Personal Data Server written in JavaScript")
- **Quick Start**: Node.js focused (simpler, no account required)
- **Platform guides**: Sections in README (not separate pages)
- **Setup script**: Single flow for both platforms
- **Audience**: Developers evaluating, self-hosters, contributors

## README Structure

### 1. Header and Overview
- New tagline without Cloudflare-specific language
- Feature list with link to endpoint comparison
- Mention both platform options

### 2. Quick Start (Node.js)
```bash
git clone https://github.com/your/pds.js
cd pds.js && npm install
npm run dev:node
npm run setup -- --pds http://localhost:3000
```

### 3. Configuration
Environment variables table:
| Variable | Required | Description |
|----------|----------|-------------|
| PDS_PASSWORD | Yes | Password for legacy auth and OAuth consent |
| JWT_SECRET | Yes | Secret for signing JWTs |
| PDS_DB_PATH | No | SQLite database path (default: ./pds.db) |
| PDS_BLOBS_DIR | No | Blob storage directory (default: ./blobs) |
| PORT | No | Server port (default: 3000) |
| HOSTNAME | No | Public hostname for the PDS |
| APPVIEW_URL | No | AppView URL for proxying |
| APPVIEW_DID | No | AppView DID for service auth |
| RELAY_URL | No | Relay URL for firehose notifications |

### 4. Deploy: Node.js
- Install dependencies
- Configure environment variables
- Start server (packages/node entry or examples/node)
- Run setup script
- DNS/TLS notes (reverse proxy)
- Storage considerations

### 5. Deploy: Cloudflare Workers
- Prerequisites (Workers Paid plan)
- Create R2 bucket and KV namespace
- Configure wrangler.toml (including SHARED_KV binding)
- Set secrets
- Deploy
- Run setup script

### 6. Testing
```bash
npm test                    # Unit tests
npm run test:e2e:node       # E2E against Node.js
npm run test:e2e:cloudflare # E2E against Cloudflare
npm run test:coverage       # Coverage
```

### 7. Architecture
- Hexagonal architecture diagram
- Ports explanation:
  - ActorStoragePort (per-user data)
  - SharedStoragePort (global data)
  - BlobPort (binary storage)
  - WebSocketPort (real-time)

### 8. Packages
Table of all packages with descriptions:
- @pdsjs/core
- @pdsjs/node
- @pdsjs/cloudflare
- @pdsjs/storage-better-sqlite3
- @pdsjs/blobs-fs
- @pdsjs/blobs-s3

Basic usage examples for Node.js and Cloudflare.

### 9. Contributing
- PR requirements (tests, format, typecheck)
- Development commands
- Project structure overview

## Additional Tasks

1. Update `examples/cloudflare/wrangler.toml` to include KV namespace binding
2. Add `npm run dev:node` script to package.json
3. Add `npm run dev:cloudflare` script to package.json
4. Update `.env.example` to include Node.js-specific variables

## Implementation Plan

### Task 1: Update package.json scripts
Add dev:node and dev:cloudflare scripts.

### Task 2: Update examples/cloudflare/wrangler.toml
Add SHARED_KV binding placeholder.

### Task 3: Update .env.example
Add Node.js-specific variables.

### Task 4: Rewrite README.md
Replace current Cloudflare-focused README with new multi-platform version.

### Verification
- Run `npm test` to ensure nothing broken
- Run `npm run dev:node` to verify script works
- Review README renders correctly