Skip to content

Commit fdfbb74

Browse files
TRohit20Shurtu-gal
TRohit20
and
Shurtu-gal
authored
docs: add onboarding documentation for studio (#1209)
Co-authored-by: Rohit <vadlamudi.rohit5@gmail.com> Co-authored-by: Ashish Padhy <ashishpadhy1729@gmail.com>
1 parent 8b9c982 commit fdfbb74

File tree

8 files changed

+599
-0
lines changed

8 files changed

+599
-0
lines changed

‎doc/onboarding/_section.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Studio
3+
weight: 20
4+
---

‎doc/onboarding/architecture.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
title: 'Architecture'
3+
weight: 50
4+
---
5+
6+
AsyncAPI Studio is built as a monorepo using Turbo, with a modular architecture that separates concerns into distinct services and components. The application follows a layered architecture pattern:
7+
8+
```mermaid
9+
graph TD
10+
classDef layer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
11+
classDef component fill:#fff,stroke:#01579b,stroke-width:1px
12+
13+
UI[User Interface Layer]:::layer
14+
SL[Services Layer]:::layer
15+
CL[Core Libraries Layer]:::layer
16+
ED[External Dependencies]:::layer
17+
18+
UI --> SL
19+
SL --> CL
20+
CL --> ED
21+
```
22+
23+
### Layer Breakdown
24+
25+
```mermaid
26+
graph TD
27+
classDef layer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
28+
classDef component fill:#fff,stroke:#01579b,stroke-width:1px
29+
30+
subgraph UI[User Interface Layer]
31+
direction LR
32+
UI_C[UI Components]:::component
33+
Nav[Navigation]:::component
34+
Ed[Editor]:::component
35+
Vis[Visualization]:::component
36+
end
37+
38+
subgraph SL[Services Layer]
39+
direction LR
40+
ES[Editor Service]:::component
41+
PS[Parser Service]:::component
42+
NS[Navigation Service]:::component
43+
SM[State Management]:::component
44+
end
45+
46+
subgraph CL[Core Libraries Layer]
47+
direction LR
48+
AP[AsyncAPI Parser]:::component
49+
AR[AsyncAPI React]:::component
50+
ME[Monaco Editor]:::component
51+
RF[React Flow]:::component
52+
end
53+
```
54+
55+
## Key Components
56+
57+
AsyncAPI Studio consists of several key components that work together to provide a seamless experience:
58+
59+
### User Interface Components
60+
61+
The UI layer consists of React components organized into logical groups:
62+
63+
1. **Core Components**: Base UI components like buttons, inputs, panels, and modals
64+
2. **Navigation Components**: Sidebar, tabs, and navigation controls
65+
3. **Editor Components**: Monaco editor integration and editor-related UI
66+
4. **Visualization Components**: React Flow integration for API visualization
67+
5. **Preview Components**: Documentation preview using AsyncAPI React component
68+
69+
### Services Layer
70+
71+
The services layer provides the core functionality of the application:
72+
73+
#### Editor Service
74+
75+
The Editor Service handles all aspects of editing AsyncAPI documents:
76+
77+
- Manages Monaco Editor configuration and integration
78+
- Provides syntax highlighting and code completion
79+
- Handles file loading and saving
80+
- Manages document format conversion (YAML/JSON)
81+
82+
#### Parser Service
83+
84+
The Parser Service is responsible for processing and validating AsyncAPI documents:
85+
86+
- Integrates with the AsyncAPI Parser library
87+
- Validates documents against the AsyncAPI schema
88+
- Processes validation results and error reporting
89+
- Handles schema resolution and references
90+
91+
#### Navigation Service
92+
93+
The Navigation Service manages navigation within the application:
94+
95+
- Controls switching between different views (Editor, Preview, Visualize)
96+
- Manages the sidebar navigation
97+
- Handles URL routing and state persistence
98+
- Coordinates interactions between different views
99+
100+
### State Management
101+
102+
AsyncAPI Studio uses Zustand for state management, with several stores:
103+
104+
1. **Editor Store**: Manages the editor state, content, and configuration
105+
2. **Parser Store**: Stores validation results and parsed document information
106+
3. **UI Store**: Manages UI state like sidebar visibility and active panels
107+
4. **Settings Store**: Handles user preferences and application settings
108+
109+
## Technology Stack
110+
111+
AsyncAPI Studio is built using modern web technologies:
112+
113+
### Frontend Technologies
114+
115+
- **React**: For building the user interface
116+
- **Next.js**: For server-side rendering and routing
117+
- **TailwindCSS**: For styling and design system
118+
- **Monaco Editor**: For the code editing experience
119+
- **React Flow**: For interactive API visualizations
120+
- **Zustand**: For state management
121+
122+
### AsyncAPI Technologies
123+
124+
- **AsyncAPI Parser**: For validating and processing AsyncAPI documents
125+
- **AsyncAPI Converter**: For converting between different AsyncAPI versions
126+
- **AsyncAPI React**: For rendering documentation previews
127+
- **AsyncAPI Generator**: For code generation from specifications
128+
129+
### Build and Development Tools
130+
131+
- **Turbo**: For monorepo management and efficient builds
132+
- **pnpm**: For package management
133+
- **TypeScript**: For type-safe code
134+
- **ESLint/Prettier**: For code quality and formatting
135+
- **Jest/React Testing Library**: For testing
136+
137+
## Data Flow
138+
139+
The following diagram illustrates how data flows through the application:
140+
141+
```mermaid
142+
sequenceDiagram
143+
participant User
144+
participant UI as User Interface
145+
participant ES as Editor Service
146+
participant PS as Parser Service
147+
participant NS as Navigation Service
148+
participant API as External APIs
149+
150+
User->>UI: Edit document
151+
UI->>ES: Update document content
152+
ES->>PS: Request validation
153+
PS->>PS: Validate document
154+
PS->>UI: Return validation results
155+
156+
User->>UI: Request preview
157+
UI->>NS: Navigate to preview
158+
NS->>PS: Get parsed document
159+
PS->>UI: Return parsed document
160+
UI->>UI: Render preview
161+
162+
User->>UI: Generate code
163+
UI->>API: Send document for generation
164+
API->>UI: Return generated code
165+
UI->>User: Download code
166+
```
167+
168+
## Deployment
169+
170+
AsyncAPI Studio supports multiple deployment models:
171+
172+
### Hosted Version
173+
The hosted version at [studio.asyncapi.com](https://studio.asyncapi.com) is deployed as a static site on cloud infrastructure:
174+
```mermaid
175+
graph LR
176+
classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px
177+
classDef service fill:#fff,stroke:#01579b,stroke-width:1px
178+
179+
U[User]:::user
180+
CDN[CDN]:::service
181+
SW[Static Website]:::service
182+
AS[API Services]:::service
183+
CG[Code Generation]:::service
184+
DS[Document Storage]:::service
185+
186+
U --> CDN
187+
CDN --> SW
188+
U --> AS
189+
AS --> CG
190+
AS --> DS
191+
192+
style U fill:#e1f5fe,stroke:#01579b,stroke-width:2px
193+
style CDN fill:#fff,stroke:#01579b,stroke-width:1px
194+
style SW fill:#fff,stroke:#01579b,stroke-width:1px
195+
style AS fill:#fff,stroke:#01579b,stroke-width:1px
196+
style CG fill:#fff,stroke:#01579b,stroke-width:1px
197+
style DS fill:#fff,stroke:#01579b,stroke-width:1px
198+
```
199+
200+
### Local Deployment
201+
202+
When deployed locally, AsyncAPI Studio runs as a standalone application:
203+
204+
```mermaid
205+
graph LR
206+
classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px
207+
classDef service fill:#fff,stroke:#01579b,stroke-width:1px
208+
209+
U[User]:::user
210+
B[Browser]:::service
211+
N[Next.js Server]:::service
212+
FS[File System]:::service
213+
214+
U --> B
215+
B --> N
216+
N --> FS
217+
```
218+
219+
### Docker Deployment
220+
221+
The Docker deployment packages the application in a lightweight container:
222+
223+
```mermaid
224+
graph LR
225+
classDef user fill:#e1f5fe,stroke:#01579b,stroke-width:2px
226+
classDef service fill:#fff,stroke:#01579b,stroke-width:1px
227+
228+
U[User]:::user
229+
B[Browser]:::service
230+
N[Nginx Server]:::service
231+
SF[Static Files]:::service
232+
233+
U --> B
234+
B --> N
235+
N --> SF
236+
```
237+
238+
## Design Decisions
239+
240+
Several key design decisions that shape AsyncAPI Studio's architecture:
241+
242+
1. **Monorepo Structure**: Allows sharing code between applications while maintaining separation
243+
2. **Service-Based Architecture**: Separates concerns into distinct services
244+
3. **Local-First Processing**: Performs validation and parsing client-side for better performance
245+
4. **Extensible Plugin System**: Enables future extensions through plugins
246+
5. **Responsive Design**: Works on various devices and screen sizes

‎doc/onboarding/images/editor-panel.png‎

659 KB
Loading

‎doc/onboarding/images/navigation-panel.png‎

684 KB
Loading

‎doc/onboarding/images/preview-panel.png‎

677 KB
Loading

‎doc/onboarding/index.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: 'Introduction'
3+
weight: 20
4+
---
5+
6+
AsyncAPI Studio is a web-based tool designed specifically for working with AsyncAPI specifications. It provides an integrated environment for developing, validating, converting, and visualizing AsyncAPI documents, making it easier to create and manage your asynchronous API definitions.
7+
8+
## Key Features
9+
10+
AsyncAPI Studio offers a rich set of features to streamline your AsyncAPI development workflow:
11+
12+
* **Advanced Editor**: Build and edit AsyncAPI documents with syntax highlighting, code completion, and error detection
13+
* **Validation**: Instantly validate your AsyncAPI documents against schema rules
14+
* **Version Conversion**: Convert specifications between different AsyncAPI versions
15+
* **Documentation Preview**: Render beautiful documentation using the AsyncAPI React component
16+
* **Visual Flow Diagrams**: Visualize message flows between systems for better understanding
17+
* **Code Generation**: Generate code from your AsyncAPI specifications using various templates
18+
* **Collaboration**: Share your AsyncAPI documents with others through URLs or file exports
19+
20+
## Why Use AsyncAPI Studio?
21+
22+
AsyncAPI Studio simplifies the process of working with AsyncAPI specifications by providing all the tools you need in one place:
23+
24+
* **User-Friendly Interface**: Designed for both beginners and experienced AsyncAPI users
25+
* **Immediate Feedback**: Get instant validation as you type to catch errors early
26+
* **Visualization**: See your API structure visually to better understand message flows
27+
* **No Installation Required**: Use the online version at [studio.asyncapi.com](https://studio.asyncapi.com) or deploy locally
28+
29+
## Studio Architecture
30+
31+
AsyncAPI Studio is built with modern web technologies:
32+
33+
```mermaid
34+
graph TD;
35+
A[User Interface] --> B[Editor Service]
36+
A --> C[Parser Service]
37+
A --> D[Navigation Service]
38+
B --> E[Monaco Editor]
39+
C --> F[AsyncAPI Parser]
40+
D --> G[Code Generation]
41+
D --> H[HTML Preview]
42+
D --> I[Block Visualizer]
43+
```
44+
45+
The application integrates several key components:
46+
* **Monaco Editor**: Powers the advanced code editing capabilities
47+
* **AsyncAPI Parser**: Validates and processes specifications
48+
* **React Flow**: Creates interactive visualizations of your API components
49+
* **AsyncAPI React**: Renders beautiful documentation previews
50+
51+
Whether you're just getting started with AsyncAPI or you're an experienced user, AsyncAPI Studio provides the tools you need to create high-quality AsyncAPI specifications efficiently.

0 commit comments

Comments
 (0)