diff --git a/README.md b/README.md index 4af55d1..9991d9d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

-![./docs/diagrams/architecture.svg](./docs/diagrams/architecture.svg) +![./docs/diagrams/architecture.svg](./diagrams/architecture.svg)

diff --git a/docs-md/diagrams/architecture.d2 b/diagrams/architecture.d2 similarity index 97% rename from docs-md/diagrams/architecture.d2 rename to diagrams/architecture.d2 index b8282dc..e828def 100644 --- a/docs-md/diagrams/architecture.d2 +++ b/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 b/diagrams/architecture.svg similarity index 100% rename from docs-md/diagrams/architecture.svg rename to diagrams/architecture.svg diff --git a/docs-md/diagrams/temporal.svg b/diagrams/temporal.svg similarity index 100% rename from docs-md/diagrams/temporal.svg rename to diagrams/temporal.svg diff --git a/docs-md/buf-repo.png b/docs-md/buf-repo.png deleted file mode 100644 index 64cbc63..0000000 Binary files a/docs-md/buf-repo.png and /dev/null differ diff --git a/docs-md/buf.md b/docs-md/buf.md deleted file mode 100644 index 21c52f4..0000000 --- a/docs-md/buf.md +++ /dev/null @@ -1,34 +0,0 @@ -## Push to Buf Schema Registry (BSR) - -Follow the [instructions](https://docs.buf.build/tour/log-into-the-bsr) to: - -1. create a Buf account -2. create a Buf token -3. create a `~/.netrc` file with `buf registry login` -4. and create repositories for all your Buf modules - [here](https://buf.build/kevinmichaelchen/repositories) - -

- -

- -When you're ready to push, run: - -```shell -make buf-push -``` - -We now have code in the BSR for all our modules: - -- [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) - -## Updating modules - -After pushing up to the BSR, to update modules run: - -```shell -go list all | grep go.buf.build | xargs go get -v -``` diff --git a/docs-md/reservations.md b/docs-md/reservations.md deleted file mode 100644 index 7d989be..0000000 --- a/docs-md/reservations.md +++ /dev/null @@ -1,32 +0,0 @@ -## Maturity - -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/) - -## 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/astro.config.mjs b/docs/astro.config.mjs index a683efa..b5f18a4 100644 --- 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 new file mode 100644 index 0000000..c2a5b46 --- /dev/null +++ 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 new file mode 100644 index 0000000..7a8ee6b --- /dev/null +++ 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 b/docs/src/content/docs/architecture/why-temporal.md similarity index 76% rename from docs-md/why-temporal.md rename to docs/src/content/docs/architecture/why-temporal.md index 86dba7b..cd0c1a8 100644 --- a/docs-md/why-temporal.md +++ b/docs/src/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 deleted file mode 100644 index ebd0f3b..0000000 --- a/docs/src/content/docs/guides/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Guide -description: A guide in my new Starlight docs site. ---- - -Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. -Writing a good guide requires thinking about what your users are trying to do. - -## Further reading - -- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx index a9b1e2b..8848b32 100644 --- 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 deleted file mode 100644 index 0224f09..0000000 --- a/docs/src/content/docs/reference/example.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Example Reference -description: A reference page in my new Starlight docs site. ---- - -Reference pages are ideal for outlining how things work in terse and clear terms. -Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting. - -## Further reading - -- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/docs-md/upstreams.md b/docs/src/content/docs/reference/overview.md similarity index 95% rename from docs-md/upstreams.md rename to docs/src/content/docs/reference/overview.md index 13e5698..f21aaac 100644 --- a/docs-md/upstreams.md +++ b/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")" -``` \ No newline at end of file +```