From 8a91b1610f8ea832cf8aba4332dff6a4f306344e Mon Sep 17 00:00:00 2001 From: Markus Blomqvist Date: Thu, 29 Feb 2024 22:44:30 +0200 Subject: [PATCH] Add architecture docs --- ARCHITECTURE.md | 15 ++ docs/static/high-level-architecture | 189 ++++++++++++++++++++++++ docs/static/high-level-architecture.svg | 4 + 3 files changed, 208 insertions(+) create mode 100644 ARCHITECTURE.md create mode 100644 docs/static/high-level-architecture create mode 100644 docs/static/high-level-architecture.svg diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..9e6a952 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,15 @@ +# Architecture + +Next REST Framework is heavily tied to the Next.js APIs and the high-level architecture of the framework consists of two main parts, the CLI and the public used for runtime: + +![High-level architecture](./docs/static/high-level-architecture.svg) + +## Public API + +The public API of Next REST Framework contains all of the functions you need to use the framework and build your APIs. These are the entry points that handle the request validation and they also provide internal methods for generating the open API spec for the given single endpoint, used by the CLI. + +## CLI + +The CLI contains most of the logic when it comes to actually building the OpenAPI spec from your APIs and generating the `openapi.json` file. Note that generating the OpenAPI spec and exposing a public documentation are completely optional and Next REST Framework can be used without them for it's type-safety features. + +For the CLI to be able to generate the OpenAPI spec, it needs to parse and read your code that is built using the methods from the public API. This process includes an intermediate step of bundling the relevant code to a common format regardless of the environment the CLI is run. For this, ESBuild is used to generate a temporary bundle of a subset of the application in a folder called `.next-rest-framework`. This build output is then analyzed by the CLI and the Zod schemas are parsed from each endpoint and included to a single output written in the `openapi.json` file. diff --git a/docs/static/high-level-architecture b/docs/static/high-level-architecture new file mode 100644 index 0000000..1599a79 --- /dev/null +++ b/docs/static/high-level-architecture @@ -0,0 +1,189 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/high-level-architecture.svg b/docs/static/high-level-architecture.svg new file mode 100644 index 0000000..46a644b --- /dev/null +++ b/docs/static/high-level-architecture.svg @@ -0,0 +1,4 @@ + + + +
Next.js
Next.js
App router
App router
Pages router
Pages router
Route handlers
Route handlers
API routes
API routes
Next REST Framework
Next REST Framework
CLI
CLI
Public API
Public API
App router
App router
docsRoute
docsRoute
route
route
Pages router
Pages router
docsApiRoute
docsApiRoute
apiRoute
apiRoute
Commands
Commands
generate
generate
validate
validate
Temporary build output
Temporary build output
Route compilation
Route compilation
Route discovery & OpenAPI conversion
Route discovery & OpenA...
openapi.json
openapi.json
rpcRoute
rpcRoute
rpcApiRoute
rpcApiRouteText is not SVG - cannot display \ No newline at end of file