feat: Mermaid diagrams

docs/apis.mdx

@@ -6,6 +6,19 @@ description: 'Building HTTP APIs with Nitric'
 
 Nitric has built-in support for web apps and HTTP API development. The `api` resource allows you to create APIs in your applications, including routing, middleware and request handlers.
 
+## Architecture
+
+```mermaid
+graph LR;
+    classDef default line-height:1.2;
+
+    A(Admin Api)-->B(Service A);
+    A-->C(Service B);
+    D(Public Api)-->B(Service A)
+```
+
+> An API can route to many nitric services, and services can handle many APIs.
+
 ## Creating APIs
 
 Nitric allows you define named APIs, each with their own routes, middleware, handlers and security.

docs/messaging.mdx

@@ -14,6 +14,20 @@ A topic is a named resource where events can be published. They can be thought o
 
 Topics are often the first choice for communication between services, since they offer stateless, scalable and highly decoupled communication.
 
+### Architecture
+
+```mermaid
+graph LR;
+    classDef default line-height:1.2;
+    classDef edgeLabel line-height:1.2;
+
+    A(Topic)-- on message -->B(Message Service);
+    C(Publisher Service) -- publish message --> A;
+    D(Publisher Batch Service) -- publish message --> A;
+```
+
+`Services` can both publish and subscribe to topics. `Batch Services` may only publish messages.
+
 ### Subscriptions
 
 A subscription is a binding between a topic and a service. You can think of it as a channel that notifies your services when something new arrives on the topic.

docs/schedules.mdx

@@ -10,6 +10,17 @@ The `schedule` resource lets you define named schedules, including their frequen
 
 If you're looking for a way to perform once-off work at some point in the future, use [delayed messaging](./messaging#delayed-messaging) instead of schedules.
 
+## Architecture
+
+```mermaid
+graph LR;
+    classDef default line-height:1.2;
+
+    A(Weekly Schedule)-->B(Service A);
+```
+
+> Schedules can be used to trigger a single service at a set cadence
+
 ## Creating schedules
 
 There are two ways to define schedules. Using `every` allows simple rate definitions to trigger the callback or `cron` can be used for more complex scenarios.

docs/secrets.mdx

@@ -8,6 +8,19 @@ Nitric Secrets simplifies the secure storage, updating, and retrieval of sensiti
 
 Alternatively, you can choose to store these values as environment variables. Learn more about it [here](/reference/env).
 
+### Architecture
+
+```mermaid
+graph LR;
+    classDef default line-height:1.2;
+    classDef edgeLabel line-height:1.2;
+
+    B(Service)-- access/put secret -->A(Secret);
+    C(Batch Service) -- access/put secret --> A;
+```
+
+Both `Services` and `Batch Services` can access and put secrets values.
+
 ## Definitions
 
 ### Secrets

docs/storage.mdx

@@ -6,6 +6,20 @@ description: 'Working with files and storage in Nitric'
 
 Nitric provides storage support for securely storing and retrieving large files in the cloud.
 
+## Architecture
+
+```mermaid
+graph LR;
+    classDef default line-height:1.2;
+    classDef edgeLabel line-height:1.2;
+
+    A(Bucket)-- on write -->B(Bucket Handler Service);
+    C(Bucket File Service) -- read/write/delete files --> A;
+    D(Image Processing Batch Service) -- read/write/delete files --> A;
+```
+
+A `Service` can both interact file files in a `Bucket` and receive notifications when files are written or deleted. A `Batch Service` can only interact with files on a bucket but cannot subscribe to file changes.
+
 ## Definitions
 
 ### Files

docs/websockets.mdx

@@ -12,6 +12,22 @@ Nitric provides support for serverless websockets. This feature allows you to co
   https://github.com/nitrictech/nitric/issues
 </Note>
 
+## Architecture
+
+```mermaid
+graph LR;
+    classDef default line-height:1.2;
+    classDef edgeLabel line-height:1.2;
+
+    A(Websocket Gateway)-- on connect -->B(Connection Handler Service);
+    A -- on disconnect --> B;
+    A -- on message --> C(Message Handler Service);
+    C -- send message --> A;
+    D(Batch Service) -- send message --> A;
+```
+
+A `Service` can both receive and send messages to a `Websocket`, `Batch Services` may only send message to a `Websocket`.
+
 ## Listening for events
 
 There are three events that must be defined to deploy a valid websocket implementation. These are `connect`, `disconnect` and `message`.

package.json

@@ -62,6 +62,8 @@
     "lucide-react": "^0.445.0",
     "mdast-util-to-string": "^4.0.0",
     "mdx-annotations": "^0.1.1",
+    "mdx-mermaid": "^2.0.3",
+    "mermaid": "^11.4.1",
     "next": "^14.2.15",
     "next-contentlayer2": "^0.5.1",
     "next-themes": "^0.3.0",

src/app/layout.tsx

@@ -3,6 +3,7 @@ import { Inter, Sora, JetBrains_Mono } from 'next/font/google'
 
 import { Providers } from '@/app/providers'
 
+import '@/styles/mermaid.css'
 import '@/styles/tailwind.css'
 import clsx from 'clsx'
 import Fathom from './Fathom'

src/components/mdx.tsx

@@ -108,4 +108,6 @@ export { Tabs, TabItem } from '@/components/tabs/Tabs'
 
 export { CodeTabs } from '@/components/code/CodeTabs'
 
+export { Mermaid } from 'mdx-mermaid/Mermaid'
+
 // see if we need to remove these

src/mdx/remark.mjs

@@ -1,4 +1,27 @@
 import { mdxAnnotations } from 'mdx-annotations'
 import remarkGfm from 'remark-gfm'
+import mdxMermaid from 'mdx-mermaid'
 
-export const remarkPlugins = [mdxAnnotations.remark, remarkGfm]
+export const remarkPlugins = [
+  mdxAnnotations.remark,
+  remarkGfm,
+  [
+    mdxMermaid,
+    {
+      output: 'svg',
+      mermaid: {
+        theme: 'base',
+        // TODO: Relocate theme config
+        themeVariables: {
+          primaryColor: '#242037',
+          lineColor: '#cad3f5',
+          secondaryColor: '#42424a',
+          tertiaryColor: '#0000ff',
+          primaryTextColor: '#cad3f5',
+          fontSize: '14px',
+          fontFamily: 'Fira Code, monospace',
+        },
+      },
+    },
+  ],
+]

src/styles/mermaid.css

@@ -0,0 +1,6 @@
+svg[id^='mermaid-svg-'] {
+  display: block;
+  /* width: 100%; */
+  margin: auto;
+  /* padding: 0; */
+}