Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: correct mermaid support in ADRs [skip ci] #552

Merged
merged 1 commit into from
Jun 16, 2023
Merged

docs: correct mermaid support in ADRs [skip ci] #552

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
21 changes: 14 additions & 7 deletions docs/decisions/20221005-using-tapir-library-as-a-dsl-for-openapi-specification.md
View file
Open in desktop
Expand Up @@ -80,7 +80,8 @@ The server side is interpreted using a ZIO-HTTP interpreter to be aligned with t
Client side stubs are generated using OpenAPI tools and OpenAPI specification file. (must be a part of CI)

For server-side code the flow is following:
```mermaid

<pre class="mermaid">
graph TD
ED(Endpoint Definition) --> |Generate| OAS(OpenAPI Specification)
ED --> |Generate| AAUI(AsyncAPI Specification)
Expand All @@ -91,7 +92,7 @@ graph TD
OAS --> |Input| OAT(OpenAPI Tools)
OAT --> |Generate| SS(Server Stub)
OAT --> |Generate| CS(Client Stub)
```
</pre>

### Positive Consequences <!-- optional -->

Expand All @@ -108,7 +109,7 @@ graph TD
- There is a risk that Tapir might have some hidden surprises and constraints

### Option 1 & 2: Feature Implementation Workflow
```mermaid
<pre class="mermaid">
graph TD
U[Start Feature] --> |Edit OAS| A
A[OAS File] --> |Input| E
Expand All @@ -123,9 +124,10 @@ graph TD
S --> |Compilation Error| I(Investigate)
I --> |Try again| U
S --> |Success| T(Complete Feature)
```
</pre>

### Option 3: Feature Implementation Workflow
```mermaid
<pre class="mermaid">
graph TD
U[Start Feature] --> |Edit Endpoint Specification| ED(Endpoint Definition)
U --> |Edit Input/Output Types| DM(Domain Model)
Expand All @@ -149,8 +151,8 @@ graph TD
S --> |Compilation Error| I(Investigate)
I --> |Try again| U
S --> |Success| T(Complete Feature)
```
</pre>

## Pros and Cons of the Options <!-- optional -->

### Option 1: use OpenAPI tools and mustache templates for Akka server
Expand Down Expand Up @@ -205,3 +207,8 @@ Then all the endpoints are translated to Tapir, it will be possible to switch th
- [OpenAPI Tools](https://github.com/OpenAPITools/openapi-generator)
- [Goals of Tapir library](https://tapir.softwaremill.com/en/latest/goals.html)
- [Tapir](https://tapir.softwaremill.com/en/latest/index.html)

<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.2.1/mermaid.min.js"/>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
10 changes: 7 additions & 3 deletions docs/decisions/20230509-message-routing-for-multi-tenant.md
View file
Open in desktop
Expand Up @@ -13,7 +13,7 @@ All the API endpoints are same from outside
Multi-tenancy, message routing can be used to ensure that messages are delivered only to the intended recipient or tenants, and not to unauthorized tenants.

Backend services: Prism Agent use PostgreSQL. Authentication and authorization
```mermaid
<pre class="mermaid">
sequenceDiagram
autonumber
actor H as Holder(DidComm)
Expand Down Expand Up @@ -48,5 +48,9 @@ Backend services: Prism Agent use PostgreSQL. Authentication and authorization
A-->>DB:lookup to Agent DID identify tenantId
A-->>A:decrypt message
deactivate H

```
</pre>

<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.2.1/mermaid.min.js"/>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
18 changes: 18 additions & 0 deletions docs/decisions/README.md
View file
Open in desktop
Expand Up @@ -28,6 +28,24 @@ To create a new ADR interactively, run:
log4brains adr new
```

## Mermaid support

Log4brains does not support [Github Mermaid Diagrams](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) diagrams by default.

To successfully render Mermaid diagrams on the server side, add the following code to your ADR:
```
<pre class="mermaid">
... your mermaid code here ...
</pre>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.2.1/mermaid.min.js"/>
<script>
mermaid.initialize({ startOnLoad: true });
</script>
```

> Unfortunately, this diagram won't be automatically rendered in your preview mode.
> So, you could debug using github mermaid diagrams, but then integrate the code above in your ADR.

## More information

- [RFC-0016](https://input-output.atlassian.net/wiki/spaces/ATB/pages/3580559403/RFC+0016+-+Use+Architectural+Design+Records)
Expand Down