···

       
55
       
 
       


     

       
56
       
 
       
We're going to accomplish this using OAuth ([spec](#todo)). You can find a [more extensive OAuth guide here](#todo), but for now just know that most of the OAuth flows are going to be handled for us using the [@atproto/oauth-client-node](#todo) library. This is the arrangement we're aiming toward:

     

       
57
       
 
       


     

       
58
       
-
       
```

     

       
59
       
-
       
  ┌─App Server───────────────────┐

     

       
60
       
-
       
  │    ┌─► Session store ◄┐      │

     

       
61
       
-
       
  │    │                  │      │    ┌───────────────┐

     

       
62
       
-
       
  │ App code ──────►OAuth client─┼───►│ User's server │

     

       
63
       
-
       
  └────▲─────────────────────────┘    └───────────────┘

     

       
64
       
-
       
  ┌────┴──────────┐

     

       
65
       
-
       
  │  Web browser  │

     

       
66
       
-
       
  └───────────────┘

     

       
67
       
-
       
```

     

       
68
       
 
       


     

       
69
       
 
       
When the user logs in, the OAuth client will create a new session with their repo server and give us read/write access along with basic user info.

     

       
70
       
 
       


     
···

       
244
       
 
       


     

       
245
       
 
       
You can think of the user repositories as collections of JSON records:

     

       
246
       
 
       


     

       
247
       
-
       
```

     

       
248
       
-
       
                                   ┌────────┐

     

       
249
       
-
       
                               ┌───| record │

     

       
250
       
-
       
               ┌────────────┐  │   └────────┘

     

       
251
       
-
       
           ┌───| collection |◄─┤   ┌────────┐

     

       
252
       
-
       
┌──────┐   │   └────────────┘  └───| record │

     

       
253
       
-
       
│ repo |◄──┤                       └────────┘

     

       
254
       
-
       
└──────┘   │   ┌────────────┐      ┌────────┐

     

       
255
       
-
       
           └───┤ collection |◄─────| record │

     

       
256
       
-
       
               └────────────┘      └────────┘

     

       
257
       
-
       
```

     

       
258
       
 
       


     

       
259
       
 
       
Let's look again at how we read the "profile" record:

     

       
260
       
 
       


     
···

       
446
       
 
       


     

       
447
       
 
       
Remember how we referred to our app as being like a Google, crawling around the repos to get their records? One advantage we have in the AT Protocol is that each repo publishes an event log of their updates.

     

       
448
       
 
       


     

       
449
       
-
       
```

     

       
450
       
-
       
┌──────┐                                       

     

       
451
       
-
       
│ REPO │  Event stream                                     

     

       
452
       
-
       
├──────┘                                       

     

       
453
       
-
       
│   ┌───────────────────────────────────────────┐

     

       
454
       
-
       
├───┼  1 PUT /app.bsky.feed.post/3l244rmrxjx2v  │

     

       
455
       
-
       
│   └───────────────────────────────────────────┘

     

       
456
       
-
       
│   ┌───────────────────────────────────────────┐

     

       
457
       
-
       
├───┼  2 DEL /app.bsky.feed.post/3l244rmrxjx2v  │

     

       
458
       
-
       
│   └───────────────────────────────────────────┘

     

       
459
       
-
       
│   ┌───────────────────────────────────────────┐

     

       
460
       
-
       
├───┼  3 PUT /app.bsky.actor.profile/self       │

     

       
461
       
-
       
▼   └───────────────────────────────────────────┘

     

       
462
       
-
       
```

     

       
463
       
 
       


     

       
464
       
 
       
Using a [Relay service](#todo) we can listen to an aggregated firehose of these events across all users in the network. In our case what we're looking for are valid `com.example.status` records.

     

       
465
       
 
       


     
···

       
535
       
 
       


     

       
536
       
 
       
You can almost think of information flowing in a loop:

     

       
537
       
 
       


     

       
538
       
-
       
```

     

       
539
       
-
       
       ┌─────Repo put─────┐

     

       
540
       
-
       
       │                  ▼

     

       
541
       
-
       
┌──────┴─────┐      ┌───────────┐

     

       
542
       
-
       
│ App server │      │ User repo │

     

       
543
       
-
       
└────────────┘      └─────┬─────┘

     

       
544
       
-
       
       ▲                  │

     

       
545
       
-
       
       └────Event log─────┘

     

       
546
       
-
       
```

     

       
547
       
 
       


     

       
548
       
 
       
Why read from the event log? Because there are other apps in the network that will write the records we're interested in. By subscribing to the event log, we ensure that we catch all the data we're interested in -- including data published by other apps.

     

       
549
       
 
       


     
···

       
603
       
 
       


     

       
604
       
 
       
As a final optimization, let's introduce "optimistic updates." Remember the information flow loop with the repo write and the event log? Since we're updating our users' repos locally, we can short-circuit that flow to our own database:

     

       
605
       
 
       


     

       
606
       
-
       
```

     

       
607
       
-
       
       ┌───Repo put──┬──────┐

     

       
608
       
-
       
       │             │      ▼

     

       
609
       
-
       
┌──────┴─────┐       │  ┌───────────┐

     

       
610
       
-
       
│ App server │◄──────┘  │ User repo │

     

       
611
       
-
       
└────────────┘          └───┬───────┘

     

       
612
       
-
       
       ▲                    │        

     

       
613
       
-
       
       └────Event log───────┘        

     

       
614
       
-
       
```

     

       
615
       
 
       


     

       
616
       
 
       
This is an important optimization to make, because it ensures that the user sees their own changes while using your app. When the event eventually arrives from the firehose, we just discard it since we already have it saved locally.

     

       
617
       
 
       


     
···

       
679
       
 
       


     

       
680
       
 
       
Remember this flow of information throughout:

     

       
681
       
 
       


     

       
682
       
-
       
```

     

       
683
       
-
       
       ┌─────Repo put─────┐

     

       
684
       
-
       
       │                  ▼

     

       
685
       
-
       
┌──────┴─────┐      ┌───────────┐

     

       
686
       
-
       
│ App server │      │ User repo │

     

       
687
       
-
       
└────────────┘      └─────┬─────┘

     

       
688
       
-
       
       ▲                  │

     

       
689
       
-
       
       └────Event log─────┘

     

       
690
       
-
       
```

     

       
691
       
 
       


     

       
692
       
 
       
This is how every app in the Atmosphere works, including the [Bluesky social app](https://bsky.app).

     

       
693
       
 
       


     

···

       
55
       
 
       


     

       
56
       
 
       
We're going to accomplish this using OAuth ([spec](#todo)). You can find a [more extensive OAuth guide here](#todo), but for now just know that most of the OAuth flows are going to be handled for us using the [@atproto/oauth-client-node](#todo) library. This is the arrangement we're aiming toward:

     

       
57
       
 
       


     

       
58
       
+
       
![A diagram of the OAuth elements](./docs/diagram-oauth.png)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
59
       
 
       


     

       
60
       
 
       
When the user logs in, the OAuth client will create a new session with their repo server and give us read/write access along with basic user info.

     

       
61
       
 
       


     
···

       
235
       
 
       


     

       
236
       
 
       
You can think of the user repositories as collections of JSON records:

     

       
237
       
 
       


     

       
238
       
+
       
![A diagram of a repository](./docs/diagram-repo.png)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
239
       
 
       


     

       
240
       
 
       
Let's look again at how we read the "profile" record:

     

       
241
       
 
       


     
···

       
427
       
 
       


     

       
428
       
 
       
Remember how we referred to our app as being like a Google, crawling around the repos to get their records? One advantage we have in the AT Protocol is that each repo publishes an event log of their updates.

     

       
429
       
 
       


     

       
430
       
+
       
![A diagram of the event stream](./docs/diagram-event-stream.png)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
431
       
 
       


     

       
432
       
 
       
Using a [Relay service](#todo) we can listen to an aggregated firehose of these events across all users in the network. In our case what we're looking for are valid `com.example.status` records.

     

       
433
       
 
       


     
···

       
503
       
 
       


     

       
504
       
 
       
You can almost think of information flowing in a loop:

     

       
505
       
 
       


     

       
506
       
+
       
![A diagram of the flow of information](./docs/diagram-info-flow.png)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
507
       
 
       


     

       
508
       
 
       
Why read from the event log? Because there are other apps in the network that will write the records we're interested in. By subscribing to the event log, we ensure that we catch all the data we're interested in -- including data published by other apps.

     

       
509
       
 
       


     
···

       
563
       
 
       


     

       
564
       
 
       
As a final optimization, let's introduce "optimistic updates." Remember the information flow loop with the repo write and the event log? Since we're updating our users' repos locally, we can short-circuit that flow to our own database:

     

       
565
       
 
       


     

       
566
       
+
       
![A diagram illustrating optimistic updates](./docs/diagram-optimistic-update.png)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
567
       
 
       


     

       
568
       
 
       
This is an important optimization to make, because it ensures that the user sees their own changes while using your app. When the event eventually arrives from the firehose, we just discard it since we already have it saved locally.

     

       
569
       
 
       


     
···

       
631
       
 
       


     

       
632
       
 
       
Remember this flow of information throughout:

     

       
633
       
 
       


     

       
634
       
+
       
![A diagram of the flow of information](./docs/diagram-info-flow.png)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
635
       
 
       


     

       
636
       
 
       
This is how every app in the Atmosphere works, including the [Bluesky social app](https://bsky.app).

     

       
637