bluesky-social · bnewbold · Oct 10, 2023 · Oct 7, 2023 · Oct 7, 2023 · Oct 7, 2023
diff --git a/README.md b/README.md
@@ -1,37 +1,93 @@
-# AT Protocol (Authenticated Transfer Protocol)
+# AT Protocol Reference Implementation (TypeScript)
 
-This is a working repository for the AT Protocol, aka the Authenticated Transfer Protocol.
+Welcome friends!
 
----
+This repository contains Bluesky's reference implementation of AT Protocol, and of the `app.bsky` microblogging application service backend.
 
-**⚠️ This is not production-ready software. This project is in active development ⚠️**
+## What is in here?
 
----
+**TypeScript Packages:**
 
-## ℹ️ About this project
+| Package                                                                       | Docs                                       | NPM                                                                                                             |
+| ----------------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `@atproto/api`: client library                                                | [README](./packages/api/README.md)         | [![NPM](https://img.shields.io/npm/v/@atproto/api)](https://www.npmjs.com/package/@atproto/api)                 |
+| `@atproto/common-web`: shared code and helpers which can run in web browsers  | [README](./packages/common-web/README.md)  | [![NPM](https://img.shields.io/npm/v/@atproto/common-web)](https://www.npmjs.com/package/@atproto/common-web)   |
+| `@atproto/common`: shared code and helpers which doesn't work in web browsers | [README](./packages/common/README.md)      | [![NPM](https://img.shields.io/npm/v/@atproto/common)](https://www.npmjs.com/package/@atproto/common)           |
+| `@atproto/crypto`: cryptographic signing and key serialization                | [README](./packages/crypto/README.md)      | [![NPM](https://img.shields.io/npm/v/@atproto/crypto)](https://www.npmjs.com/package/@atproto/crypto)           |
+| `@atproto/identity`: DID and handle resolution                                | [README](./packages/identity/README.md)    | [![NPM](https://img.shields.io/npm/v/@atproto/identity)](https://www.npmjs.com/package/@atproto/identity)       |
+| `@atproto/lexicon`: schema definition language                                | [README](./packages/lexicon/README.md)     | [![NPM](https://img.shields.io/npm/v/@atproto/lexicon)](https://www.npmjs.com/package/@atproto/lexicon)         |
+| `@atproto/repo`: data storage structure, including MST                        | [README](./packages/repo/README.md)        | [![NPM](https://img.shields.io/npm/v/@atproto/repo)](https://www.npmjs.com/package/@atproto/repo)               |
+| `@atproto/syntax`: string parsers for identifiers                             | [README](./packages/syntax/README.md)      | [![NPM](https://img.shields.io/npm/v/@atproto/syntax)](https://www.npmjs.com/package/@atproto/syntax)           |
+| `@atproto/xrpc`: client-side HTTP API helpers                                 | [README](./packages/xrpc/README.md)        | [![NPM](https://img.shields.io/npm/v/@atproto/xrpc)](https://www.npmjs.com/package/@atproto/xrpc)               |
+| `@atproto/xrpc-server`: server-side HTTP API helpers                          | [README](./packages/xrpc-server/README.md) | [![NPM](https://img.shields.io/npm/v/@atproto/xrpc-server)](https://www.npmjs.com/package/@atproto/xrpc-server) |
 
-To learn more about atproto, see:
+**TypeScript Services:**
 
-- [Protocol Documentation](https://atproto.com/docs)
-  - [Overview Guide](https://atproto.com/guides/overview) 👈 Good place to start
-- The [Blogpost on self-authenticating data structures](https://blueskyweb.xyz/blog/3-6-2022-a-self-authenticating-social-protocol)
+- `pds`: "Personal Data Server", hosting repo content for atproto accounts. Most implementation code in `packages/pds`, with runtime wrapper in `services/pds`. See [bluesky-social/pds](https://github.com/bluesky-social/pds) for directions on self-hosting in the [federation sandbox network](https://atproto.com/blog/federation-developer-sandbox).
+- `bsky`: AppView implementation of the `app.bsky.*` API endpoints. Running on main network at `api.bsky.app`. Most implementation code in `packages/bsky`, with runtime wrapper in `services/bsky`.
 
-## Rules & Guidelines
+**Lexicons:** for both the `com.atproto.*` and `app.bsky.*` are canonically versioned in this repo, for now, under `./lexicons/`. These are JSON files in the [Lexicon schema definition language](https://atproto.com/specs/lexicon), similar to JSON Schema or OpenAPI.
 
-While we do accept contributions, we prioritize high-quality issues and pull requests. Adhering to the below guidelines will ensure a more timely review.
+**Interoperability Test Data:** the language-neutral test files in `./interop-test-files/` may be useful for other protocol implementations to ensure that they follow the specification correctly
 
-### Rules:
+The source code for the Bluesky Social client app (for web and mobile) can be found at [bluesky-social/social-app](https://github.com/bluesky-social/social-app).
+
+Go programming language source code is in [bluesky-social/indigo](https://github.com/bluesky-social/indigo), including the BGS implementation.
+
+## Developer Quickstart
+
+We recommend [`nvm`](https://github.com/nvm-sh/nvm) for managing Node.js installs. This project requires Node.js version 18. `pnpm` is used to manage the workspace of multiple packages. You can install it with `npm install --global pnpm`.
+
+There is a Makefile which can help with basic development tasks:
+
+```shell
+# use existing nvm to install node 18 and pnpm
+make nvm-setup
+
+# pull dependencies and build all local packages
+make deps
+make build
+
+# run the tests, using Docker services as needed
+make test
+
+# run a local PDS and AppView with fake test accounts and data
+make run-dev-env
+
+# show all other commands
+make help
+```
+
+## About AT Protocol
+
+The Authenticated Transfer Protocol ("ATP" or "atproto") is a decentralized social media protocol, developed by [Bluesky PBC](https://blueskyweb.xyz). Learn more at:
+
+- [Overview and Guides](https://atproto.com/guides/overview) 👈 Best starting point
+- [Github Discussions](https://github.com/bluesky-social/atproto/discussions) 👈 Great place to ask questions
+- [Protocol Specifications](https://atproto.com/specs/atp)
+- [Blogpost on self-authenticating data structures](https://blueskyweb.xyz/blog/3-6-2022-a-self-authenticating-social-protocol)
+
+The Bluesky Social application encompasses a set of schemas and APIs built in the overall AT Protocol framework. The namespace for these "Lexicons" is `app.bsky.*`.
+
+## Contributions
+
+> While we do accept contributions, we prioritize high quality issues and pull requests. Adhering to the below guidelines will ensure a more timely review.
+
+**Rules:**
 
 - We may not respond to your issue or PR.
 - We may close an issue or PR without much feedback.
 - We may lock discussions or contributions if our attention is getting DDOSed.
+- We do not provide support for build issues.
 
-### Guidelines:
+**Guidelines:**
 
 - Check for existing issues before filing a new one, please.
 - Open an issue and give some time for discussion before submitting a PR.
 - If submitting a PR that includes a lexicon change, please get sign off on the lexicon change _before_ doing the implementation.
-- Issues are for bugs & feature requests related to the TypeScript implementation of atproto and related services. For high-level discussions, please you the [Discussion Forum](https://github.com/bluesky-social/atproto/discussions). For client issues, please use the relevant [social-app](https://github.com/bluesky-social/social-app) repo
+- Issues are for bugs & feature requests related to the TypeScript implementation of atproto and related services.
+  - For high-level discussions, please use the [Discussion Forum](https://github.com/bluesky-social/atproto/discussions).
+  - For client issues, please use the relevant [social-app](https://github.com/bluesky-social/social-app) repo.
 - Stay away from PRs that:
   - Refactor large parts of the codebase
   - Add entirely new features without prior discussion
@@ -52,6 +108,4 @@ If you discover any security issues, please send an email to [email protected].
 
 ## License
 
-MIT License
-
-Copyright (c) 2023 Bluesky PBC
+MIT License. See [LICENSE](./LICENSE) for full text.