simple list of pds servers with open registration
Add CLAUDE.md with project guidance for Claude Code
+63
+63
CLAUDE.md
+63
CLAUDE.md
···
1
+
# CLAUDE.md
2
+
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## What This Is
6
+
7
+
OpenPDS is a directory of AT Protocol PDS servers with open registration. It runs on Val Town as a serverless app with two entry points: an HTTP server and a daily cron job. Data comes from [mary-ext/atproto-scraping](https://github.com/mary-ext/atproto-scraping) and gets enriched with health, geo-IP, version, and trust metadata.
8
+
9
+
## Commands
10
+
11
+
```bash
12
+
deno task check # Type check entry points
13
+
deno task test # Run tests (--allow-net --allow-read --allow-import)
14
+
deno fmt # Format all files
15
+
deno lint # Lint all .ts files
16
+
deno task deploy # fmt + lint + check + test + vt push (full deploy pipeline)
17
+
```
18
+
19
+
Do **not** use `vt push` directly — always use `deno task deploy` which runs quality checks first.
20
+
21
+
## Architecture
22
+
23
+
**Runtime:** Deno on Val Town. **Framework:** Hono. **Database:** Val Town SQLite. **Imports:** via `esm.sh` (not npm/node_modules).
24
+
25
+
### Entry Points
26
+
27
+
- `backend/index.http.ts` — HTTP trigger. Hono app serving HTML directory (`/`) and JSON API (`/api/servers`). Runs migrations on first request.
28
+
- `cron/refresh.cron.ts` — Cron trigger. Daily refresh: fetch PDS list → sync to DB → fetch latest version → enrich batch of servers.
29
+
30
+
### Data Flow (Cron)
31
+
32
+
1. `pds-fetcher.ts` downloads state.json (~2900 PDSes)
33
+
2. Each PDS upserted to SQLite with open/closed status
34
+
3. `version-checker.ts` gets latest PDS version from GitHub API
35
+
4. `pds-enricher.ts` enriches a batch (configurable, default 20): DNS resolve → health check → describeServer → listRepos user count → geo-IP batch lookup
36
+
5. Results written back to DB via `updateEnrichment()`
37
+
38
+
### Module Layout
39
+
40
+
- `backend/database/` — `migrations.ts` (schema), `queries.ts` (all SQL operations, row-to-object mapping)
41
+
- `backend/routes/` — `pages.ts` (server-rendered HTML), `api.ts` (JSON endpoint)
42
+
- `backend/services/` — Pure async functions: `pds-fetcher`, `pds-enricher`, `geo-resolver`, `version-checker`
43
+
- `shared/` — `types.ts` (all TypeScript interfaces), `constants.ts` (config values, country flag helper)
44
+
- `cron/` — Scheduled job orchestration
45
+
46
+
### Trust Score
47
+
48
+
5 boolean signals, each worth 20%: contact email, ToS, privacy policy, active users (>5), latest PDS version. Calculated in SQL via CASE expressions.
49
+
50
+
## Val Town Specifics
51
+
52
+
- Exports use Val Town conventions: HTTP files export `app.fetch`, cron files export a default async function
53
+
- SQLite accessed via `https://esm.town/v/stevekrouse/sqlite`
54
+
- Schema changes: create new table names (append `_2`, `_3`) rather than ALTER TABLE
55
+
- No `Deno` namespace in `shared/` code (must work in browser context too)
56
+
- Secrets via `Deno.env.get()`, never hardcoded
57
+
58
+
## Conventions
59
+
60
+
- Database columns: `snake_case`. TypeScript code: `camelCase`. `rowToServer()` maps between them.
61
+
- Per-request timeouts via `AbortSignal.timeout()` (5s for PDS endpoints, 10s for geo batch)
62
+
- Batch operations use `Promise.allSettled()` for partial-failure resilience
63
+
- HTML output uses custom `esc()` function for XSS prevention