perlsky is a Perl 5 implementation of an AT Protocol Personal Data Server.
1# Code Structure
2
3This 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
9Internal 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
20Labels 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
26Internal 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
37If 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
47Internal 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
69The 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
80Low-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
90The 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
96The 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
103The pattern used for these splits is:
104
1051. keep the public facade stable
1062. extract one cohesive internal slice at a time
1073. verify the most relevant focused suites first
1084. only then move to the next slice
109
110That is the safest way to keep simplifying the codebase without losing reference parity or label/moderation correctness.
111
112## Local Reference Sources
113
114`tools/reference` is a local-only convenience bundle for source checkouts of the upstream Bluesky reference repos used during audits and parity work.
115
116- it is intentionally not tracked
117- it may contain nested `.git` directories
118- it should not be treated as production input or committed project content
119
120If you need those sources again on a fresh machine, reclone them locally instead of trying to recover them from this repo history.