This is my attempt at trying to break down some of the different terms floating around about Bluesky in a (hopefully) less technical manor. There's a lot, and a lot of times you see developers and others using terms like PDS, atproto, did, and things like that. But what does any of that actually mean in regular terms? Don't worry, if it doesn't make sense, just keep going. Each section I hit the high points with the key analogies.

If you are already familiar with atproto this may not be the post for you and may have some "not exactly correct" or "You forgot this edge case" parts. That's intentional, not to misdirect or mislead but to break the basic concepts down and give a base layer of knowledge. Every adventure starts with the first step, and this is meant to be the second one after being on Bluesky for a while.

ATProto, Atmosphere, ATProtocol, etc

So a lot of times you will see one of these words. They're all the same thing, atproto (shorten version of it). What is that exactly? Well it's the technology that runs Bluesky. Think about an iPhone vs Android. Each are phones, but each have a different technology running them. When you say you're using a Samsung Galaxy, that's Android. When you say you're using an iPhone that's iOS. Just two different ways to solve a problem, a modern cellphone. Same for Bluesky to atproto. You can install many apps on an iPhone/Android, you can also install(use) many apps on atproto! All with the same device(Bluesky(atproto) login). Some examples are stream.place, leaflet.pub, skylight.social, 2048.blue, etc. All of those websites/apps are powered by the same technology, atproto. With all of those you have the same login. Kind of like "Sign in with apple/google/microsoft" but you use your Bluesky(atproto) login instead and have much more ownership of that login.

• iPhone = iOS

• Samsung Galaxy/Google Pixel = Android

• Bluesky = ATProtocol

Identity

Alright this is going be a long one, and I will try my best to split it up. But hold with me, trying my best not to Pepe Silvia it.

did/phone number

A big cornerstone of Bluesky(atproto) is your Identity, and by Identity I mean by what connects everything in Bluesky(atproto) back to you. What makes you, well you. Think of it like a phone number. Sure you can change your phone number, and many do. But you can also keep it forever, everyone knows you by it. When you verify on a lot of websites they call you or send you a text to verify that it is you. That's the same for Bluesky(atproto), expect it is called a did. There are a few different kind's of did's. But just know if you see something like this did:plc:rnpkyqnmsw4ipey6eotbdnnf that's a did(phone number). Just like (555) 555-5555 is a phone number. When someone says "Your Bluesky(atproto) id" they mean the did(phone number). It's unique, there are many like it, but yours is the only exact one, and it's yours forever. That's your identity on Bluesky(atproto). When someone loads your profile, the software is using that did(phone number) to look you up. When someone sends you a DM, they're sending it to your did(phone number). You cannot get a new one, but you can create a brand new account and get a new one. When you create a brand new account can think of that like adding a line to your phone plan, or a home phone.

Note "creating a brand new account" is different than an account move/migration.

handle

Your handle is just a friendly name for your did(phone number). For instance @jcsalterego.bsky.social is a handle for the did(phone number) did:plc:vc7f4oafdgxsihk4cry2xpze. Very similar to when you pick up your phone to call or text someone, you're not going to dial the phone number each time. You are going to look them up by their name. Same for Bluesky(atproto) handles. You can change the name in the address book, but it is still the same phone number. Same for handles.

Will also notice that when you look at a handle it looks an awful lot like a website URL like google.com, well that's because it is! Go ahead, click jcsalterego.bsky.social and see what happens. It should have taken you to Jerry's Bluesky profile. It's important to know that handles are like names in an address book, and website URLs for the next part.

handle lookup/address book

So I keep talking about looking up phone numbers in an address book. What does that look like for Bluesky(atproto)? Well there's actually 2 address books. One that looks up your did(phone number) from your handle, and one that looks up your PDS from your did(phone number).

First address book: did(phone number) look up from your handle

There's a couple of ways to look up that did(phone number) from the handle depending on the handle type.

First is done by looking it up via going to a website built from your handle like https://jcsalterego.bsky.social/.well-known/atproto-did you'll notice it shows just the text did:plc:vc7f4oafdgxsihk4cry2xpze. That's the handle's did(phone number).

But what about custom domain handles like @baileytownsend.dev. That is done by a DNS TXT record at _atproto.baileytownsend.dev. If you don't know what DNS, that's okay. That's a bit out of scope for this post. Can just go to this link and see under TXT records it shows my did(phone number). That's the other way to look up a handle.

There's another did(phone number) called did:web but that's out of scope for this. Just know that most people use did:plc and the flow works as above. If you adventurous can read more on that here. Just know it's very similar. You're looking up an address to get the information you need. Like an address book

Second address book: PDS look up via the did

We will talk about the PDS itself in the next section. Just know it holds your data (pictures, posts, likes, etc). When Bluesky or another atproto application needs to sign you in or when you make a post, or like a post it all happens on the PDS. So it's pretty important. Since Bluesky(atproto) is decentralized it needs a road map to get there. That's the point of everything so far under the "Identity" heading. It's the "How do I save or read that data to my PDS". Well once we have the did(phone number) from that proces a atprotocol app,this includes Bluesky, looks up your PDS on something called the PLC, shorten for Public Ledger of Credentials. Aka a global address book. This is the Yellow Pages of Bluesky(atproto). If you go to https://web.plc.directory/did/did:plc:rnpkyqnmsw4ipey6eotbdnnf you'll notice at the top is my PDS. https://selfhosted.social

did:web's are different, but that's another day. So by this point you should know how to go from handle -> did(phone number) -> PDS

PDS

Whew. Alright, hopefully I did not lose you too much. If I did that's fine. This is the high points of what we learned.

• A did is like a phone number. It's unique to you and what is called when directing posts, likes, etc to you. It's your phone number on the atmosphere

• A handle is a friendly name for a did(phone number). A contact name in your phone book

• You can look your did(phone number) by the handle since it is a website URL. Like a address book in your phone

• You can look up your PDS by the did(phone number) in the Yellow Pages/Global Address book

Now. What the hell is a PDS? A PDS stands for Personal Data Server. It's a bit of a cross between your phone provider, like AT&T, Verizon, etc. And it's your actual physical phone.

The PDS handles all of your traffic like making post, uploading an image, sending a DM, etc. Just like a phone provider handles all of your texts, calls, cell data, etc making sure it goes where it is supposed to go.

It's also like a phone as in it holds all your data. You may text a message or a picture to your friend, but it's still on your phone. Same with a PDS. When you make a post yes it's on Bluesky or Blacksky, but it's also on your PDS. Same for pictures and videos. There's a lot there that we will not go in here. But take a minute and look up your handle on https://pdsls.dev. You'll see an input at the top enter your handle there. Should see a screen about like this

In that picture is every single like, post, repost, reply, picture, follow, block, etc I've ever made on Bluesky(atproto). It's all right there on the PDS I host at https://selfhosted.social. It's the source of truth and Bluesky(atproto) is made in a way it can be proved I did make all of those by my identity. Also as we saw you can find all that data by following the breadcrumbs to the PDS. Now how does it show up on Bluesky or Blacksky will be a post for another day. Just know the PDS is the source of truth, it's your data on your cellphone. It's yours and you have full control of it.

Moving to a new PDS

Okay so now we have an idea of a PDS. Well like if you decide to move from one provider like AT&T to Verizon to get a better deal or better coverage. You may decide to do the same thing with your Bluesky(atproto) PDS. Bluesky(atproto) is setup just like. You can buy a brand new phone plan, brand new phone. Load it up with your texts, call records, pictures, phone numbers and it's exactly the same as before. When someone calls you, it goes to that shinny new phone with a new phone plan. You do the same exact thing when you migrate to a new PDS. At this point that's probably all you need to really know. Buttttt if you're curious about how that move works. It looks a bit like this.

This is in spoken language what programs like goat, atpairport.com, tektite.cc, and pdsmoover.com do when they move your Bluesky(atproto) account to a new PDS.

1. Signs into your account on your current PDS and says "I want to move to a new PDS, give me a password to prove it's me and I want to create an account there"

2. A call to the new PDS says "Hey this is my did(phone number), I want the handle xyz, this is my email, this is the password I want, oh yeah btw here is this password my old PDS gave me to prove it's me." If all that checks out it creates a new account with the did(phone number). Hint that's why the error "Repo already exists" happens sometimes. It tries to do this step again

3. Now that there is an account on both the current PDS and new one it migrates your data. It makes a call to get all your posts, likes, etc in a single file (like a giant excel file). Then uploads it to your new PDS like you always been there. Same with pictures/videos (called blobs). But this is done one at a time. Downloads one, up loads one, etc till it's all done. This is what takes so long. Then it also gets your preferences like mutes, etc and moves them over (also like an excel file, but smaller)

4. Once everything is moved over it sends you an email with a token called a PLC token. This is to confirm you do want to move over by telling the PLC(Yellow Pages/Global address book) that yes when looking up my did(phone number) tell them to use this PDS to get my data(posts, likes, pictures, etc). This is what I call signing the papers. Once you enter the PLC token into the tool it then tells your old PDS to tell the PLC to change that URL over.

5. Finally it deactivates your old account. If everything is following the road map nothing should call your old PDS. But if you deactivate the old one that tells the PDS to say "Hey if someone calls tell em I ain't here no more" if they call looking for you.

And that's pretty much it in a nutshell.

What the hell is a Relay? AppView? Client? JetStream? FireHose? Gigawatt?

Okay that last one is a reference to the Four Year Strong song. Not really a Bluesky(atproto) thing. We'll get there and I'll make more posts explaining these concepts. But I think that's enough for now. I'm tired and got a soccer game to watch. So till next time