Skip to content

Commit 40e3313

Browse files
MiloszFilimowskiAHGIJMKLKKZNPJKQRczerwiukkPiotrWodecki
authored
FCE-1596: Docs restructure (#133)
## Description There is a lot to read here so I guess this PR will take a long time to review... I welcome any of your suggestions and changes. We can treat it as a draft to work on. What's new? - Docs are restructured based on this guide: https://diataxis.fr/ - Much of the existing content just orgnized into a diffrent place - There is also a lot of new *LLM generated* content. I tried to review the changes, especially the tutorials and examples if they work and they do as of 02.07.2025. There are also some new LLM generated pages in Concepts sections. I tried to make them more verbose and more pleasing to read and I think this was achived but there might be some LLM bullshit I might've missed. - Replaced markdown-spellcheck with https://cspell.org/ because it has support for MDX. I just couldn't get the old lib to work with mdx comments, and cspell works great. --------- Co-authored-by: Tomasz Mazur <[email protected]> Co-authored-by: adrian <[email protected]> Co-authored-by: Piotr Wodecki <[email protected]>
1 parent 10c2a45 commit 40e3313

File tree

82 files changed

+5224
-4524
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

82 files changed

+5224
-4524
lines changed

‎.cspell.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"version": "0.2",
3+
"language": "en",
4+
"dictionaries": ["custom-dictionary"],
5+
"dictionaryDefinitions": [
6+
{
7+
"name": "custom-dictionary",
8+
"path": "./spelling.txt",
9+
"addWords": true
10+
}
11+
],
12+
"ignorePaths": [
13+
"node_modules/**",
14+
"packages/**",
15+
"docs/api/**",
16+
".git/**",
17+
"*.lock",
18+
"yarn.lock",
19+
"package-lock.json"
20+
],
21+
"ignoreRegExpList": ["JSXComment", "/^\\s*```[\\s\\S]*?^\\s*```/gm"],
22+
23+
"patterns": [
24+
{
25+
"name": "JSXComment",
26+
"pattern": "\\{/\\*[\\s\\S]*?\\*/\\}"
27+
}
28+
],
29+
"enableFiletypes": ["mdx"],
30+
"allowCompoundWords": true,
31+
"ignoreWords": []
32+
}

‎.github/workflows/static_check.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
- name: Install node dependencies
2323
run: yarn --immutable
2424
- name: Spellcheck
25-
run: yarn spellcheck:report
25+
run: yarn spellcheck
2626
- name: Check formatting
2727
run: yarn format:check
2828
- name: Check types

‎docs/api/_category_.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
{
22
"label": "API",
3-
"position": 10,
3+
"position": 6,
44
"link": {
55
"type": "generated-index",
6-
"description": "API documentation for Web and Mobile SDKs."
6+
"description": "API documentation for Client and Server SDKs.",
7+
"slug": "/api"
78
},
89
"customProps": {
910
"id": "generated-api"

‎docs/explanation/_category_.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"label": "Explanation",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"title": "Explanation",
7+
"description": "Big-picture explanations of higher-level Fishjam concepts. Most useful for building understanding of a particular topic.",
8+
"slug": "/explanation"
9+
},
10+
"collapsible": false
11+
}

‎docs/explanation/architecture.mdx‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
type: explanation
3+
sidebar_position: 2
4+
---
5+
6+
# Fishjam Architecture
7+
8+
_Understanding how Fishjam works under the hood_
9+
10+
This document explains the technical architecture of Fishjam and how data flows through the system.
11+
12+
## High-level Architecture
13+
14+
Streaming with Fishjam is simple: you create a room, add peers to it, and start streaming. Below is a high-level overview of how Fishjam works.
15+
16+
![Fishjam Data Flow](@site/static/img/architecture.svg)
17+
18+
## Components Overview
19+
20+
### 1. Your Backend Server
21+
22+
Your application's backend server is responsible for:
23+
24+
- Authenticating users
25+
- Creating rooms using Fishjam Server SDKs
26+
- Generating peer tokens for clients
27+
- Managing room lifecycle and permissions
28+
29+
### 2. Fishjam Media Server
30+
31+
The Fishjam Media Server is the core infrastructure component that:
32+
33+
- Routes audio and video streams between participants
34+
- Handles WebRTC negotiations and connections
35+
- Manages different room types (conference, audio-only, livestream)
36+
- Processes and transcodes media when needed
37+
- Enforces security policies and token validation
38+
39+
### 3. Client Applications
40+
41+
Client applications (React Native, React) use Fishjam Client SDKs to:
42+
43+
- Connect to rooms using peer tokens
44+
- Send and receive audio/video streams
45+
- Handle device management (cameras, microphones)
46+
- Manage connection state and reconnections
47+
48+
## Data Flow
49+
50+
### 1. Room Creation Flow
51+
52+
```mermaid
53+
sequenceDiagram
54+
participant FM as Fishjam Media Server
55+
participant BE as Your Backend
56+
participant Client as Client App
57+
58+
Client->>BE: Request to join room
59+
BE->>FM: Create room (Server SDK)
60+
FM->>BE: Return room ID
61+
BE->>FM: Create peer (Server SDK)
62+
FM->>BE: Return peer token
63+
BE->>Client: Send peer token + Fishjam URL
64+
```
65+
66+
### 2. Media Streaming Flow
67+
68+
```mermaid
69+
sequenceDiagram
70+
participant C1 as Client 1
71+
participant FM as Fishjam Media Server
72+
participant C2 as Client 2
73+
74+
C1->>FM: Connect with peer token
75+
C2->>FM: Connect with peer token
76+
C1->>FM: Send video/audio stream
77+
FM->>C2: Route stream to other peers
78+
C2->>FM: Send video/audio stream
79+
FM->>C1: Route stream to other peers
80+
```
81+
82+
## Next Steps
83+
84+
To understand different room types in detail, see [Room Types Explained](/explanation/room-types).
85+
86+
To learn about security and token management, see [Security & Token Model](/explanation/security-tokens).
87+
88+
Ready to implement? Start with our tutorials:
89+
90+
- [React Native Quick Start](/tutorials/react-native-quick-start)
91+
- [Backend Quick Start](/tutorials/backend-quick-start)

‎docs/glossary.md‎ renamed to ‎docs/explanation/glossary.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 8
2+
type: reference
33
---
44

55
# Glossary
@@ -32,4 +32,4 @@ The URL to your Fishjam instance. It is used by your backend server to add peers
3232

3333
### Room Manager
3434

35-
Our test app is available **only** in the Sandbox environment. It allows you to test Fishjam without needing to add room creation functionality to your backend. You can find more details [here](/room-manager).
35+
Our test app is available **only** in the Sandbox environment. It allows you to test Fishjam without needing to add room creation functionality to your backend. You can find more details [here](/how-to/features/room-manager-testing).

‎docs/explanation/room-manager-concept.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
type: explanation
3+
sidebar_position: 1
4+
---
5+
6+
# What is Room Manager?
7+
8+
_Understanding what Room Manager is and why it exists_
9+
10+
Room Manager is a development tool that simplifies getting started with Fishjam by providing a simple backend for testing, eliminating the need to build your own server initially.
11+
12+
## What can Room Manager do?
13+
14+
Room Manager is an HTTP server that comes with Fishjam's Sandbox environment.
15+
It provides basic room creation and peer management functionality without requiring you to set up your own backend infrastructure.
16+
17+
### Key Characteristics
18+
19+
- **Batteries-included**: No extra setup required to start using room manager.
20+
- **Development-focused**: Designed for initial development and testing
21+
- **No authentication**: Simplified access for quick prototyping
22+
- **Sandbox-only**: Only available in the Sandbox environment
23+
24+
## The Problem Room Manager Solves
25+
26+
When starting with videoconferencing or livestreaming development, you typically need:
27+
28+
1. A **Backend server** to create rooms
29+
2. An **Authentication system** to manage users
30+
3. **Token management** for secure peer access
31+
4. **API endpoints** for your frontend to call
32+
33+
This creates a problem: to test your frontend, you need a backend, but during prototyping you want to focus on frontend development first.
34+
Room Manager mitigates this issue and allows you to start frontend development ASAP.
35+
36+
## Relationship to Server SDKs
37+
38+
Room Manager is essentially a simplified application built using the Fishjam Server SDKs:
39+
40+
```typescript
41+
import {
42+
FishjamClient,
43+
RoomConfigRoomTypeEnum,
44+
} from "@fishjam-cloud/js-server-sdk";
45+
import express from "express";
46+
const fishjamUrl = "";
47+
const managementToken = "";
48+
const app = express();
49+
50+
// ---cut---
51+
// What Room Manager does internally (simplified)
52+
const fishjamClient = new FishjamClient({ fishjamUrl, managementToken });
53+
54+
app.get(
55+
"/room-manager",
56+
async (req: express.Request, res: express.Response) => {
57+
const { roomName, peerName, roomType } = req.query;
58+
59+
// Create or get room
60+
const room = await fishjamClient.createRoom({
61+
roomType: roomType as RoomConfigRoomTypeEnum,
62+
});
63+
64+
// Create or get peer
65+
const { peer, peerToken } = await fishjamClient.createPeer(room.id);
66+
67+
res.json({ peerToken, url: fishjamUrl });
68+
},
69+
);
70+
```
71+
72+
This shows you exactly what your production backend needs to do, just with proper authentication and error handling.
73+
74+
## See also
75+
76+
To understand how to use Room Manager for development:
77+
78+
- [How to use Room Manager for testing](/how-to/features/room-manager-testing)
79+
80+
To learn about building your own backend:
81+
82+
- [Backend Quick Start Tutorial](/tutorials/backend-quick-start)
83+
- [How to set up your server](/how-to/backend/server-setup)
84+
85+
To understand the security model:
86+
87+
- [Security & Token Model](/explanation/security-tokens)

‎docs/explanation/room-types.mdx‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
type: explanation
3+
sidebar_position: 3
4+
---
5+
6+
# Room Types Explained
7+
8+
_Understanding different types of rooms and when to use them_
9+
10+
Fishjam provides three distinct room types, each optimized for different use cases and scenarios.
11+
Understanding these room types helps you choose the right approach for your application.
12+
13+
## Conference Rooms (Default)
14+
15+
### What are Conference Rooms?
16+
17+
Conference rooms are the default room type designed for multi-participant video conferencing scenarios. They support all Fishjam features and provide the most flexibility.
18+
19+
### Key Characteristics
20+
21+
- **Multi-participant**: Support for many participants simultaneously
22+
- **Bidirectional media**: All participants can send and receive video/audio
23+
- **Multiple sources**: Participants can share their camera, screen, microphone and more all at once
24+
- **Flexible track management**: Participants can add/remove tracks dynamically
25+
26+
### Best Use Cases
27+
28+
- **Video conferencing applications**
29+
- **Interactive webinars** with participant engagement
30+
31+
### Cost Considerations
32+
33+
Conference rooms are priced based on total connection time of all peers.
34+
35+
## Audio-only Rooms
36+
37+
### What are Audio-only Rooms?
38+
39+
Audio-only rooms are optimized specifically for voice communication, removing video capabilities to improve performance and reduce costs.
40+
41+
### Key Characteristics
42+
43+
- **Voice-only communication**: No video tracks allowed
44+
- **Cheap pricing**: Audio only rooms cost much less than other room types
45+
- **Optimized network usage**: Works well in degraded network conditions
46+
47+
### Best Use Cases
48+
49+
- **Audio chat applications**
50+
- **Podcast recording** with multiple participants
51+
- **Large-scale audio events** (town halls, announcements)
52+
53+
### Cost Benefits
54+
55+
Audio-only rooms come at a **75% discount** compared to conference rooms:
56+
57+
- 2 peers for 30 minutes = 60 minutes total time in conference room
58+
- Same scenario in audio-only room = 15 minutes equivalent cost
59+
60+
### Video Behavior in Audio-only Rooms
61+
62+
If you attempt to add video to an audio-only room:
63+
64+
- Video tracks are ignored (not transmitted)
65+
- SDKs log warnings to help with debugging
66+
- Only audio from screen sharing is transmitted
67+
- No errors thrown, graceful degradation
68+
69+
## Livestream Rooms
70+
71+
### What are Livestream Rooms?
72+
73+
Livestream rooms are designed for one-to-many livestreaming scenarios where a single streamer streams to multiple viewers.
74+
75+
### Key Characteristics
76+
77+
- **One sender**: Only one streamer can send media
78+
- **Many receivers**: Unlimited viewers can watch
79+
- **Optimized for scale**: Efficient distribution architecture
80+
81+
### Livestreaming Limitations
82+
83+
- **Single video track**: Only one video stream allowed
84+
- **Single audio track**: Only one audio stream allowed
85+
- **Additional tracks ignored**: Extra tracks are not forwarded to viewers
86+
87+
### Viewer Experience
88+
89+
- **Configurable access**: Livestreams can either be public, where anyone with the stream's ID can join, or private, where every viewer needs a token
90+
- **Standard compatibility**: Any [WHEP](https://blog.swmansion.com/building-interactive-streaming-apps-webrtc-whip-whep-explained-d38f4825ec90)-compatible player works
91+
92+
### Best Use Cases
93+
94+
- **Live events**
95+
- **Streaming platforms** and content distribution
96+
- **Corporate livestreams** and announcements
97+
- **Sports and entertainment** streaming
98+
99+
### Cost Benefits
100+
101+
Livestream rooms are **20% cheaper** than conference rooms for equivalent usage.
102+
103+
## Choosing the Right Room Type
104+
105+
### Decision Matrix
106+
107+
| Use Case | Room Type | Why |
108+
| ---------------------- | ---------- | ------------------------------------------- |
109+
| Classic video meetings | Conference | Multiple video sources |
110+
| Voice-only meetings | Audio-only | Cheapest and most performant option |
111+
| Live Podcasts | Audio-only | Cheapest and most performant option |
112+
| Sport streaming | Livestream | Highly scalable and cheaper than conference |
113+
| Interactive workshop | Conference | Multiple video sources |
114+
115+
## Next Steps
116+
117+
To understand how to implement each room type:
118+
119+
- [How to create audio-only calls](/how-to/features/audio-only-calls)
120+
- [How to implement livestreaming](/how-to/features/livestreaming)
121+
122+
To learn about the underlying architecture:
123+
124+
- [Fishjam Architecture](/explanation/architecture)
125+
- [Security & Token Model](/explanation/security-tokens)
126+
127+
Ready to start building? Check our tutorials:
128+
129+
- [React Native Quick Start](/tutorials/react-native-quick-start)
130+
- [Backend Quick Start](/tutorials/backend-quick-start)

0 commit comments

Comments
 (0)