about things
rewrite atproto readme with proper architecture
- add diagram showing all components (PDS, Relay, AppView, Feed Generator, Labeler)
- explain each component factually
- show data flow step by step
- remove derivative philosophy, focus on how it works
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+40
-30
+40
-30
protocols/atproto/README.md
+40
-30
protocols/atproto/README.md
···
1
1
# atproto
2
2
3
-
the AT Protocol. a protocol for connected clouds.
4
-
5
-
## the problem
6
-
7
-
cloud computing won. it's convenient, scalable, everywhere. but the clouds are closed. your identity, data, and social graph live in silos that don't interoperate. if you want to connect to people, your computer becomes a portal to someone else's computer.
8
-
9
-
this wasn't inevitable. early federated systems (XMPP, RSS/Reader) proved interoperability was possible. they died when large providers realized closed networks were more profitable.
10
-
11
-
## the solution
12
-
13
-
bridge the clouds. my cloud talks to your cloud. a bigger cloud does bigger things, a smaller cloud does smaller things, but they all talk.
14
-
15
-
the AT Protocol is the technical foundation for this. it standardizes identity, data storage, event streams, and API contracts so that independent services can interoperate without direct coordination.
3
+
the AT Protocol. an open protocol for decentralized social applications.
16
4
17
5
## architecture
18
6
19
-
two roles matter:
20
-
21
7
```
22
-
┌─────────────┐ ┌─────────────┐
23
-
│ PDS │ ◄─────► │ Application │
24
-
│ (account) │ │ (app logic) │
25
-
└─────────────┘ └─────────────┘
8
+
┌─────────┐ ┌─────────┐ ┌─────────┐
9
+
│ PDS │ │ PDS │ │ PDS │ user repos
10
+
└────┬────┘ └────┬────┘ └────┬────┘
11
+
│ │ │
12
+
└───────────────┼───────────────┘
13
+
│ firehose
14
+
▼
15
+
┌───────────┐
16
+
│ Relay │ aggregates events
17
+
└─────┬─────┘
18
+
│ firehose
19
+
┌─────────────┼─────────────┐
20
+
▼ ▼ ▼
21
+
┌─────────┐ ┌───────────┐ ┌─────────┐
22
+
│ AppView │ │ Feed │ │ Labeler │ consume & process
23
+
│ │ │ Generator │ │ │
24
+
└────┬────┘ └───────────┘ └─────────┘
25
+
│
26
+
│ read/write
27
+
▼
28
+
┌─────────┐
29
+
│ PDS │ back to user repos
30
+
└─────────┘
26
31
```
27
32
28
-
**PDS (Personal Data Server)** hosts user accounts and data. each user is one database. the PDS produces a signed event log that anyone can consume.
33
+
### components
29
34
30
-
**Applications** subscribe to these event logs and build aggregated views. bluesky, leaflet, tangled - they're all applications consuming the same underlying data.
35
+
**PDS (Personal Data Server)** hosts user accounts. stores the data repo (a signed merkle tree of records), handles authentication, emits changes to a firehose stream. each user's data lives on one PDS, but users can migrate between providers.
31
36
32
-
this separation matters for moderation. if an application suspends you, it affects only that application. if a PDS takes down your account, it affects all applications until you migrate. PDS takedowns should be reserved for network abuse and illegal content.
37
+
**Relay** aggregates firehose streams from many PDSes into one. an optimization - downstream services subscribe to one relay instead of thousands of PDSes. multiple relays can exist; anyone can run one.
33
38
34
-
## key properties
39
+
**AppView** indexes firehose data into queryable databases. serves the application UI - timelines, search, notifications. also proxies writes back to user PDSes. this is what most people think of as "the app."
35
40
36
-
**sharded by user, aggregated by app.** each user's data lives in their PDS with strict serial ordering. applications aggregate across users with only causal ordering between them.
41
+
**Feed Generator** subscribes to firehose, applies custom selection logic, returns post URIs on request. enables algorithmic choice - the "For You" feed on bluesky runs on someone's gaming PC.
37
42
38
-
**authenticated data.** records are signed. event logs can be gossiped across organizational boundaries without trusting the messenger - you verify by checking proofs, not providers.
43
+
**Labeler** produces signed metadata about content (spam, nsfw, etc). appviews and clients subscribe to labelers they trust. enables moderation without centralized control.
39
44
40
-
**schema interoperability.** applications agree on record schemas (lexicons) so they can read each other's data. your bluesky posts can appear in leaflet because both understand the schema.
45
+
### data flow
41
46
42
-
**migration.** because identity is separate from hosting, you can move your account between PDS providers without losing your identity or social graph.
47
+
1. user creates a record (post, like, follow) via client
48
+
2. client sends write to appview, which forwards to user's PDS
49
+
3. PDS commits record to repo, emits event to firehose
50
+
4. relay aggregates, downstream services consume
51
+
5. appviews update their indices, labelers apply labels
52
+
6. next time someone requests that content, appview serves from index
43
53
44
54
## contents
45
55
···
52
62
53
63
## sources
54
64
55
-
- [atmospheric computing](https://pfrazee.com/blog/atmospheric-computing) - paul frazee
56
-
- [update on protocol moderation](https://leaflet.pub/pfrazee.com/3lgy73zy4bc2a) - paul frazee
57
-
- [atproto.com](https://atproto.com)
65
+
- [atproto.com](https://atproto.com) - official documentation
66
+
- [introduction to atproto](https://mackuba.eu/2025/08/20/introduction-to-atproto/) - mackuba
67
+
- [federation architecture](https://bsky.social/about/blog/5-5-2023-federation-architecture) - bluesky
58
68
- [plyr.fm](https://github.com/zzstoatzz/plyr.fm) - music streaming on atproto
59
69
- [pdsx](https://github.com/zzstoatzz/pdsx) - atproto CLI/MCP