perlsky is a Perl 5 implementation of an AT Protocol Personal Data Server.
Document current facade and helper layout
+112
+2
README.md
+2
README.md
···
11
11
12
12
The immediate goal is a PDS that is pleasant to hack on and interoperable enough to be exercised with real AT Protocol clients and repo sync tooling.
13
13
14
+
Developer-oriented notes about the current facade/module split live in `docs/CODE_STRUCTURE.md`.
15
+
14
16
Reference differential validation:
15
17
16
18
- Run `script/differential-validate` to compare `perlsky` against the official published `@atproto/pds` on a focused set of account, repo, moderation, sync, firehose, and `importRepo` snapshot-restore behaviors.
+110
docs/CODE_STRUCTURE.md
+110
docs/CODE_STRUCTURE.md
···
1
+
# Code Structure
2
+
3
+
This repo is intentionally keeping a few stable public facades while moving dense implementation details into smaller internal modules. The current split points are:
4
+
5
+
## Store
6
+
7
+
`lib/ATProto/PDS/Store/SQLite.pm` remains the public SQLite store facade.
8
+
9
+
Internal slices currently live in:
10
+
11
+
- `lib/ATProto/PDS/Store/SQLite/ActionTokens.pm`
12
+
- `lib/ATProto/PDS/Store/SQLite/Events.pm`
13
+
- `lib/ATProto/PDS/Store/SQLite/Invites.pm`
14
+
- `lib/ATProto/PDS/Store/SQLite/Labels.pm`
15
+
- `lib/ATProto/PDS/Store/SQLite/Moderation.pm`
16
+
- `lib/ATProto/PDS/Store/SQLite/Operations.pm`
17
+
- `lib/ATProto/PDS/Store/SQLite/Preferences.pm`
18
+
- `lib/ATProto/PDS/Store/SQLite/Reservations.pm`
19
+
20
+
Labels and event persistence are treated as a high-sensitivity area. Prefer small behavior-preserving edits there, with direct coverage in `t/labels.t`, `t/firehose.t`, and `t/store-sqlite.t`.
21
+
22
+
## Repo Manager
23
+
24
+
`lib/ATProto/PDS/Repo/Manager.pm` is still the entry point for repo initialization and normal write flows.
25
+
26
+
Internal helper slices:
27
+
28
+
- `lib/ATProto/PDS/Repo/Manager/Artifacts.pm`
29
+
- snapshot CAR generation
30
+
- commit artifact assembly
31
+
- firehose path shaping
32
+
- `lib/ATProto/PDS/Repo/Manager/Import.pm`
33
+
- `importRepo`
34
+
- invalid TID repair
35
+
- imported-record rewriting and diffing
36
+
37
+
If you add more helpers here, keep normal write-path semantics easy to audit from the facade and avoid mixing import/repair logic back into the hot path.
38
+
39
+
## Service Proxy
40
+
41
+
`lib/ATProto/PDS/ServiceProxy.pm` is now a slim facade that keeps:
42
+
43
+
- request entrypoint
44
+
- local-handler dispatch
45
+
- service-auth JWT forwarding
46
+
47
+
Internal helper slices:
48
+
49
+
- `lib/ATProto/PDS/ServiceProxy/Upstream.pm`
50
+
- upstream request retries
51
+
- target selection
52
+
- proxy-header parsing
53
+
- config lookup
54
+
- `lib/ATProto/PDS/ServiceProxy/Preferences.pm`
55
+
- actor preferences
56
+
- notification preferences
57
+
- `lib/ATProto/PDS/ServiceProxy/Profile.pm`
58
+
- local profile views
59
+
- blob URL shaping
60
+
- `lib/ATProto/PDS/ServiceProxy/Posts.pm`
61
+
- local post URI parsing
62
+
- post/thread helper primitives
63
+
- `lib/ATProto/PDS/ServiceProxy/Threads.pm`
64
+
- author feed
65
+
- local posts/threads
66
+
- request-scoped post index
67
+
- embed rendering
68
+
69
+
The important contract is unchanged: local handlers can return `undef` to fall through to upstream proxying. Keep that behavior exact.
70
+
71
+
## Reference Differential Harness
72
+
73
+
`script/differential-validate` still owns:
74
+
75
+
- scenario sequencing
76
+
- semantic normalizers
77
+
- reference/perlsky state mutation
78
+
- final mismatch reporting
79
+
80
+
Low-level harness mechanics now live in:
81
+
82
+
- `lib/ATProto/PDS/Test/Differential/HTTP.pm`
83
+
- authenticated XRPC request helpers
84
+
- request body variants
85
+
- `lib/ATProto/PDS/Test/Differential/Firehose.pm`
86
+
- websocket quiet checks
87
+
- commit-frame capture
88
+
- frame draining helpers
89
+
90
+
The current rule of thumb is:
91
+
92
+
- okay to extract transport/plumbing helpers
93
+
- okay to extract scenario wrappers when they do not hide important state transitions
94
+
- keep normalizers explicit unless a refactor is obviously behavior-preserving
95
+
96
+
The differential harness is validated by:
97
+
98
+
- `PERLSKY_RUN_REFERENCE_DIFF=1 prove -lv t/reference-differential.t`
99
+
- `PERLSKY_RUN_REFERENCE_DIFF=1 prove -lv t/reference-differential-plc.t`
100
+
101
+
## Refactor Pattern
102
+
103
+
The pattern used for these splits is:
104
+
105
+
1. keep the public facade stable
106
+
2. extract one cohesive internal slice at a time
107
+
3. verify the most relevant focused suites first
108
+
4. only then move to the next slice
109
+
110
+
That is the safest way to keep simplifying the codebase without losing reference parity or label/moderation correctness.