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