Switch to image-based diagrams · graham.systems/statusphere-react@512dacd

+6 -62

TUTORIAL.md

··· 55 55 56 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 57 58 - ``` 59 - ┌─App Server───────────────────┐ 60 - │ ┌─► Session store ◄┐ │ 61 - │ │ │ │ ┌───────────────┐ 62 - │ App code ──────►OAuth client─┼───►│ User's server │ 63 - └────▲─────────────────────────┘ └───────────────┘ 64 - ┌────┴──────────┐ 65 - │ Web browser │ 66 - └───────────────┘ 67 - ``` 58 + ![A diagram of the OAuth elements](./docs/diagram-oauth.png) 68 59 69 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. 70 61 ··· 244 235 245 236 You can think of the user repositories as collections of JSON records: 246 237 247 - ``` 248 - ┌────────┐ 249 - ┌───| record │ 250 - ┌────────────┐ │ └────────┘ 251 - ┌───| collection |◄─┤ ┌────────┐ 252 - ┌──────┐ │ └────────────┘ └───| record │ 253 - │ repo |◄──┤ └────────┘ 254 - └──────┘ │ ┌────────────┐ ┌────────┐ 255 - └───┤ collection |◄─────| record │ 256 - └────────────┘ └────────┘ 257 - ``` 238 + ![A diagram of a repository](./docs/diagram-repo.png) 258 239 259 240 Let's look again at how we read the "profile" record: 260 241 ··· 446 427 447 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. 448 429 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 - ``` 430 + ![A diagram of the event stream](./docs/diagram-event-stream.png) 463 431 464 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. 465 433 ··· 535 503 536 504 You can almost think of information flowing in a loop: 537 505 538 - ``` 539 - ┌─────Repo put─────┐ 540 - │ ▼ 541 - ┌──────┴─────┐ ┌───────────┐ 542 - │ App server │ │ User repo │ 543 - └────────────┘ └─────┬─────┘ 544 - ▲ │ 545 - └────Event log─────┘ 546 - ``` 506 + ![A diagram of the flow of information](./docs/diagram-info-flow.png) 547 507 548 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. 549 509 ··· 603 563 604 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: 605 565 606 - ``` 607 - ┌───Repo put──┬──────┐ 608 - │ │ ▼ 609 - ┌──────┴─────┐ │ ┌───────────┐ 610 - │ App server │◄──────┘ │ User repo │ 611 - └────────────┘ └───┬───────┘ 612 - ▲ │ 613 - └────Event log───────┘ 614 - ``` 566 + ![A diagram illustrating optimistic updates](./docs/diagram-optimistic-update.png) 615 567 616 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. 617 569 ··· 679 631 680 632 Remember this flow of information throughout: 681 633 682 - ``` 683 - ┌─────Repo put─────┐ 684 - │ ▼ 685 - ┌──────┴─────┐ ┌───────────┐ 686 - │ App server │ │ User repo │ 687 - └────────────┘ └─────┬─────┘ 688 - ▲ │ 689 - └────Event log─────┘ 690 - ``` 634 + ![A diagram of the flow of information](./docs/diagram-info-flow.png) 691 635 692 636 This is how every app in the Atmosphere works, including the [Bluesky social app](https://bsky.app). 693 637

docs/diagram-event-stream.png