docs: Update docs

kevinmichaelchen · Jan 14, 2024 · 5718f86 · 5718f86
1 parent fe0e0db
commit 5718f86
Show file tree

Hide file tree

Showing 15 changed files with 147 additions and 100 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 <p align="center">
 
-![./docs/diagrams/architecture.svg](./docs/diagrams/architecture.svg)
+![./docs/diagrams/architecture.svg](./diagrams/architecture.svg)
 
 </p>
 

diff --git a/docs-md/diagrams/architecture.d2 → diagrams/architecture.d2 b/docs-md/diagrams/architecture.d2 → diagrams/architecture.d2
@@ -3,7 +3,7 @@ direction: right
 vars: {
   icons: {
     gopher: https://www.svgrepo.com/show/373635/go-gopher.svg
-    temporal: ./docs/diagrams/temporal.svg
+    temporal: ./diagrams/temporal.svg
     database: https://icons.terrastruct.com/essentials%2F117-database.svg
   }
 }

diff --git a/docs-md/diagrams/architecture.svg → diagrams/architecture.svg b/docs-md/diagrams/architecture.svg → diagrams/architecture.svg
diff --git a/docs-md/diagrams/temporal.svg → diagrams/temporal.svg b/docs-md/diagrams/temporal.svg → diagrams/temporal.svg
diff --git a/docs-md/buf-repo.png b/docs-md/buf-repo.png
diff --git a/docs-md/buf.md b/docs-md/buf.md
diff --git a/docs-md/reservations.md b/docs-md/reservations.md
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -19,12 +19,20 @@ export default defineConfig({
       lastUpdated: true,
       sidebar: [
         {
-          label: "Guides",
+          label: "Architecture",
           items: [
             // Each item here is one entry in the navigation menu.
             {
-              label: "Example Guide",
-              link: "/guides/example/",
+              label: "Overview",
+              link: "/architecture/overview/",
+            },
+            {
+              label: "Why Temporal?",
+              link: "/architecture/why-temporal/",
+            },
+            {
+              label: "Buf",
+              link: "/architecture/buf/",
             },
           ],
         },

diff --git a/docs/src/content/docs/architecture/buf.md b/docs/src/content/docs/architecture/buf.md
@@ -0,0 +1,28 @@
+---
+title: Buf
+description: Using Buf for developing with Protocol Buffers
+---
+
+## What is Buf?
+
+Buf provides value in two forms:
+
+1. The [Buf CLI][cli] for code generation, breaking change detection, linting, and formatting.
+1. The [Buf Schema Registry][bsr] for storing and managing Protobuf files as versioned modules, allowing you to consume and publish APIs without friction.
+
+[bsr]: https://buf.build/docs/bsr/introduction
+[cli]: https://buf.build/docs/ecosystem/cli-overview
+
+## Buf Schema Registry
+
+We've published our 4 modules to the BSR:
+
+- [licenseapis]
+- [orgapis]
+- [profileapis]
+- [temporalapis]
+
+[licenseapis]: https://buf.build/kevinmichaelchen/licenseapis/docs/main:license.v1beta1
+[orgapis]: https://buf.build/kevinmichaelchen/orgapis/docs/main:org.v1beta1
+[profileapis]: https://buf.build/kevinmichaelchen/profileapis/docs/main:profile.v1beta1
+[temporalapis]: https://buf.build/kevinmichaelchen/temporalapis/docs/main:temporal.v1beta1
diff --git a/docs/src/content/docs/architecture/overview.md b/docs/src/content/docs/architecture/overview.md
@@ -0,0 +1,56 @@
+---
+title: Architectural Overview
+description: A guide to the overall architecture here.
+---
+
+Given the name of the project, we have to mention [Temporal][temporal] as an ideal solution for implementing not only “distributed transactions” that span across multiple microservices, but also most asynchronous, relatively long-lived processes, especially ones that involve human interaction.
+
+## Running things
+
+- [pkgx][pkgx] and [Taskfile][taskfile] for optimal local DevEx (seamless, portable, invisible)
+
+## APIs
+
+- [Tailcall][tailcall] and [GraphQL][graphql]
+- [Buf][buf] for [Protocol Buffer][protobuf] tooling
+- [ConnectRPC][connect] for backing APIs
+
+## Data
+
+- [Atlas][atlas] for declarative database migrations
+- [Postgres][postgres]
+
+## Observability
+
+- [OpenTelemetry][otel] (OTel)
+- [Jaeger][jaeger] (soon to be replaced by [HyperDX][hyperdx])
+
+## Frontend
+
+- [NextJS][nextjs] React framework
+- [shadcn/ui][shadcn-ui] for beautiful [Radix][radix]/[Tailwind][tailwind] components
+
+## Misc
+
+- [Docker][docker]
+- [Golang][golang]
+
+[atlas]: https://atlasgo.io/
+[buf]: https://buf.build/
+[connect]: https://connectrpc.com/
+[docker]: https://www.docker.com/
+[golang]: https://go.dev/
+[graphql]: https://graphql.org/
+[hyperdx]: https://www.hyperdx.io/
+[jaeger]: https://www.jaegertracing.io/
+[nextjs]: https://nextjs.org/
+[otel]: https://opentelemetry.io/
+[postgres]: https://www.postgresql.org/
+[pkgx]: https://pkgx.sh/
+[protobuf]: https://protobuf.dev/
+[radix]: https://www.radix-ui.com/
+[shadcn-ui]: https://ui.shadcn.com/
+[tailcall]: https://tailcall.run/
+[tailwind]: https://tailwindcss.com/
+[taskfile]: https://taskfile.dev/
+[temporal]: https://temporal.io/
diff --git a/docs-md/why-temporal.md → ...content/docs/architecture/why-temporal.md b/docs-md/why-temporal.md → ...content/docs/architecture/why-temporal.md
@@ -1,4 +1,7 @@
-# Why Temporal
+---
+title: Why Temporal?
+description: Why you might want to adopt Temporal
+---
 
 A single request from a web or mobile client needs to be ultimately result in
 the creation of several entities: an org, a user, a license, etc.
@@ -104,3 +107,38 @@ Executions. Workflow Executions are lightweight components. A Workflow Execution
 consumes few compute resources; in fact, if a Workflow Execution is suspended,
 such as when it is in a waiting state, the Workflow Execution consumes no
 compute resources at all.
+
+## Reservations
+
+### Is it mature enough?
+
+It's used by some [big names](https://temporal.io/use-cases):
+
+- [Snapchat](https://eng.snap.com/build_a_reliable_system_in_a_microservices_world_at_snap/)
+- [Netflix](https://www.youtube.com/watch?v=LliBP7YMGyA)
+- [Doordash](https://doordash.engineering/2020/08/14/workflows-cadence-event-driven-processing/)
+- [Stripe](https://www.youtube.com/watch?v=Crkcr1S-NSc)
+- [Coinbase](https://temporal.io/case-studies/reliable-crypto-transactions-at-coinbase)
+- [Datadog](https://www.youtube.com/watch?v=Hz7ZZzafBoE)
+- [Hashicorp](https://www.youtube.com/watch?v=kDlrM6sgk2k&t=1188s)
+- [Airbyte](https://temporal.io/case-studies/airbyte-case-study)
+- [Box](https://temporal.io/case-studies/temporal-a-central-brain-for-box)
+- [Checkr](https://temporal.io/case-studies/how-temporal-simplified-checkr-workflows/)
+- [Descript](https://temporal.io/case-studies/descript-case-study)
+- [Zebra Medical Vision](https://temporal.io/case-studies/zebra-medical-case-study/)
+
+### Does it have a Cloud offering?
+
+- Supports US East region
+- SOC2 compliant
+- Encryption means they don't see any of our data
+- VPC peering
+- Scalable (150,000 actions per second)
+- Public uptime reporting
+- Good SLA (99.9% uptime)
+- Latency SLO of 200ms per region for p99
+- Pricing
+  - simple, transparent, and controllable
+  - automatically adjusts based on volume within a namespace
+  - pay only for what you use, not what you might need.
+  - spend less on infrastructure and staff to run your applications
diff --git a/docs/src/content/docs/guides/example.md b/docs/src/content/docs/guides/example.md
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -1,14 +1,14 @@
 ---
-title: Welcome to Starlight
-description: Get started building your docs site with Starlight.
+title: Welcome!
+description: An ideal backend tech stack
 template: splash
 hero:
-  tagline: Congrats on setting up a new Starlight project!
+  tagline: This project started as a foray into Temporal's durable workflows, but it expanded into an overall amalgamation of what I consider valuable open-source tools and good engineering practices.
   image:
     file: ../../assets/houston.webp
   actions:
-    - text: Example Guide
-      link: /temporal-saga-grpc/guides/example/
+    - text: Dive In
+      link: /temporal-saga-grpc/architecture/overview/
       icon: right-arrow
       variant: primary
     - text: Source Code

diff --git a/docs/src/content/docs/reference/example.md b/docs/src/content/docs/reference/example.md
diff --git a/docs-md/upstreams.md → docs/src/content/docs/reference/overview.md b/docs-md/upstreams.md → docs/src/content/docs/reference/overview.md
@@ -1,3 +1,8 @@
+---
+title: Overview
+description: An overview of API references
+---
+
 This project has 3 gRPC servers that are upstream (called by) the License
 worker.
 
@@ -45,4 +50,4 @@ pkgx http POST \
     id="$(pkgx gum input --placeholder "id")"
 
 pkgx http http://localhost:9092/licenses/"$(pkgx gum input --placeholder "id")"
-```
+```