FCE-1596: Docs restructure

.cspell.json

@@ -0,0 +1,32 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "dictionaries": ["custom-dictionary"],
+  "dictionaryDefinitions": [
+    {
+      "name": "custom-dictionary",
+      "path": "./spelling.txt",
+      "addWords": true
+    }
+  ],
+  "ignorePaths": [
+    "node_modules/**",
+    "packages/**",
+    "docs/api/**",
+    ".git/**",
+    "*.lock",
+    "yarn.lock",
+    "package-lock.json"
+  ],
+  "ignoreRegExpList": ["JSXComment", "/^\\s*```[\\s\\S]*?^\\s*```/gm"],
+
+  "patterns": [
+    {
+      "name": "JSXComment",
+      "pattern": "\\{/\\*[\\s\\S]*?\\*/\\}"
+    }
+  ],
+  "enableFiletypes": ["mdx"],
+  "allowCompoundWords": true,
+  "ignoreWords": []
+}

.github/workflows/static_check.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Install node dependencies
         run: yarn --immutable
       - name: Spellcheck
-        run: yarn spellcheck:report
+        run: yarn spellcheck
       - name: Check formatting
         run: yarn format:check
       - name: Check types

docs/api/_category_.json

@@ -1,9 +1,10 @@
 {
   "label": "API",
-  "position": 10,
+  "position": 6,
   "link": {
     "type": "generated-index",
-    "description": "API documentation for Web and Mobile SDKs."
+    "description": "API documentation for Client and Server SDKs.",
+    "slug": "/api"
   },
   "customProps": {
     "id": "generated-api"

docs/explanation/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Explanation",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "title": "Explanation",
+    "description": "Big-picture explanations of higher-level Fishjam concepts. Most useful for building understanding of a particular topic.",
+    "slug": "/explanation"
+  },
+  "collapsible": false
+}

docs/explanation/architecture.mdx

@@ -0,0 +1,91 @@
+---
+type: explanation
+sidebar_position: 2
+---
+
+# Fishjam Architecture
+
+_Understanding how Fishjam works under the hood_
+
+This document explains the technical architecture of Fishjam and how data flows through the system.
+
+## High-level Architecture
+
+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.
+
+![Fishjam Data Flow](@site/static/img/architecture.svg)
+
+## Components Overview
+
+### 1. Your Backend Server
+
+Your application's backend server is responsible for:
+
+- Authenticating users
+- Creating rooms using Fishjam Server SDKs
+- Generating peer tokens for clients
+- Managing room lifecycle and permissions
+
+### 2. Fishjam Media Server
+
+The Fishjam Media Server is the core infrastructure component that:
+
+- Routes audio and video streams between participants
+- Handles WebRTC negotiations and connections
+- Manages different room types (conference, audio-only, livestream)
+- Processes and transcodes media when needed
+- Enforces security policies and token validation
+
+### 3. Client Applications
+
+Client applications (React Native, React) use Fishjam Client SDKs to:
+
+- Connect to rooms using peer tokens
+- Send and receive audio/video streams
+- Handle device management (cameras, microphones)
+- Manage connection state and reconnections
+
+## Data Flow
+
+### 1. Room Creation Flow
+
+```mermaid
+sequenceDiagram
+    participant FM as Fishjam Media Server
+    participant BE as Your Backend
+    participant Client as Client App
+
+    Client->>BE: Request to join room
+    BE->>FM: Create room (Server SDK)
+    FM->>BE: Return room ID
+    BE->>FM: Create peer (Server SDK)
+    FM->>BE: Return peer token
+    BE->>Client: Send peer token + Fishjam URL
+```
+
+### 2. Media Streaming Flow
+
+```mermaid
+sequenceDiagram
+    participant C1 as Client 1
+    participant FM as Fishjam Media Server
+    participant C2 as Client 2
+
+    C1->>FM: Connect with peer token
+    C2->>FM: Connect with peer token
+    C1->>FM: Send video/audio stream
+    FM->>C2: Route stream to other peers
+    C2->>FM: Send video/audio stream
+    FM->>C1: Route stream to other peers
+```
+
+## Next Steps
+
+To understand different room types in detail, see [Room Types Explained](/explanation/room-types).
+
+To learn about security and token management, see [Security & Token Model](/explanation/security-tokens).
+
+Ready to implement? Start with our tutorials:
+
+- [React Native Quick Start](/tutorials/react-native-quick-start)
+- [Backend Quick Start](/tutorials/backend-quick-start)

docs/glossary.md → docs/explanation/glossary.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+type: reference
 ---
 
 # Glossary
@@ -32,4 +32,4 @@ The URL to your Fishjam instance. It is used by your backend server to add peers
 
 ### Room Manager
 
-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).
+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

@@ -0,0 +1,87 @@
+---
+type: explanation
+sidebar_position: 1
+---
+
+# What is Room Manager?
+
+_Understanding what Room Manager is and why it exists_
+
+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.
+
+## What can Room Manager do?
+
+Room Manager is an HTTP server that comes with Fishjam's Sandbox environment.
+It provides basic room creation and peer management functionality without requiring you to set up your own backend infrastructure.
+
+### Key Characteristics
+
+- **Batteries-included**: No extra setup required to start using room manager.
+- **Development-focused**: Designed for initial development and testing
+- **No authentication**: Simplified access for quick prototyping
+- **Sandbox-only**: Only available in the Sandbox environment
+
+## The Problem Room Manager Solves
+
+When starting with videoconferencing or livestreaming development, you typically need:
+
+1. A **Backend server** to create rooms
+2. An **Authentication system** to manage users
+3. **Token management** for secure peer access
+4. **API endpoints** for your frontend to call
+
+This creates a problem: to test your frontend, you need a backend, but during prototyping you want to focus on frontend development first.
+Room Manager mitigates this issue and allows you to start frontend development ASAP.
+
+## Relationship to Server SDKs
+
+Room Manager is essentially a simplified application built using the Fishjam Server SDKs:
+
+```typescript
+import {
+  FishjamClient,
+  RoomConfigRoomTypeEnum,
+} from "@fishjam-cloud/js-server-sdk";
+import express from "express";
+const fishjamUrl = "";
+const managementToken = "";
+const app = express();
+
+// ---cut---
+// What Room Manager does internally (simplified)
+const fishjamClient = new FishjamClient({ fishjamUrl, managementToken });
+
+app.get(
+  "/room-manager",
+  async (req: express.Request, res: express.Response) => {
+    const { roomName, peerName, roomType } = req.query;
+
+    // Create or get room
+    const room = await fishjamClient.createRoom({
+      roomType: roomType as RoomConfigRoomTypeEnum,
+    });
+
+    // Create or get peer
+    const { peer, peerToken } = await fishjamClient.createPeer(room.id);
+
+    res.json({ peerToken, url: fishjamUrl });
+  },
+);
+```
+
+This shows you exactly what your production backend needs to do, just with proper authentication and error handling.
+
+## See also
+
+To understand how to use Room Manager for development:
+
+- [How to use Room Manager for testing](/how-to/features/room-manager-testing)
+
+To learn about building your own backend:
+
+- [Backend Quick Start Tutorial](/tutorials/backend-quick-start)
+- [How to set up your server](/how-to/backend/server-setup)
+
+To understand the security model:
+
+- [Security & Token Model](/explanation/security-tokens)

docs/explanation/room-types.mdx

@@ -0,0 +1,130 @@
+---
+type: explanation
+sidebar_position: 3
+---
+
+# Room Types Explained
+
+_Understanding different types of rooms and when to use them_
+
+Fishjam provides three distinct room types, each optimized for different use cases and scenarios.
+Understanding these room types helps you choose the right approach for your application.
+
+## Conference Rooms (Default)
+
+### What are Conference Rooms?
+
+Conference rooms are the default room type designed for multi-participant video conferencing scenarios. They support all Fishjam features and provide the most flexibility.
+
+### Key Characteristics
+
+- **Multi-participant**: Support for many participants simultaneously
+- **Bidirectional media**: All participants can send and receive video/audio
+- **Multiple sources**: Participants can share their camera, screen, microphone and more all at once
+- **Flexible track management**: Participants can add/remove tracks dynamically
+
+### Best Use Cases
+
+- **Video conferencing applications**
+- **Interactive webinars** with participant engagement
+
+### Cost Considerations
+
+Conference rooms are priced based on total connection time of all peers.
+
+## Audio-only Rooms
+
+### What are Audio-only Rooms?
+
+Audio-only rooms are optimized specifically for voice communication, removing video capabilities to improve performance and reduce costs.
+
+### Key Characteristics
+
+- **Voice-only communication**: No video tracks allowed
+- **Cheap pricing**: Audio only rooms cost much less than other room types
+- **Optimized network usage**: Works well in degraded network conditions
+
+### Best Use Cases
+
+- **Audio chat applications**
+- **Podcast recording** with multiple participants
+- **Large-scale audio events** (town halls, announcements)
+
+### Cost Benefits
+
+Audio-only rooms come at a **75% discount** compared to conference rooms:
+
+- 2 peers for 30 minutes = 60 minutes total time in conference room
+- Same scenario in audio-only room = 15 minutes equivalent cost
+
+### Video Behavior in Audio-only Rooms
+
+If you attempt to add video to an audio-only room:
+
+- Video tracks are ignored (not transmitted)
+- SDKs log warnings to help with debugging
+- Only audio from screen sharing is transmitted
+- No errors thrown, graceful degradation
+
+## Livestream Rooms
+
+### What are Livestream Rooms?
+
+Livestream rooms are designed for one-to-many livestreaming scenarios where a single streamer streams to multiple viewers.
+
+### Key Characteristics
+
+- **One sender**: Only one streamer can send media
+- **Many receivers**: Unlimited viewers can watch
+- **Optimized for scale**: Efficient distribution architecture
+
+### Livestreaming Limitations
+
+- **Single video track**: Only one video stream allowed
+- **Single audio track**: Only one audio stream allowed
+- **Additional tracks ignored**: Extra tracks are not forwarded to viewers
+
+### Viewer Experience
+
+- **Configurable access**: Livestreams can either be public, where anyone with the stream's ID can join, or private, where every viewer needs a token
+- **Standard compatibility**: Any [WHEP](https://blog.swmansion.com/building-interactive-streaming-apps-webrtc-whip-whep-explained-d38f4825ec90)-compatible player works
+
+### Best Use Cases
+
+- **Live events**
+- **Streaming platforms** and content distribution
+- **Corporate livestreams** and announcements
+- **Sports and entertainment** streaming
+
+### Cost Benefits
+
+Livestream rooms are **20% cheaper** than conference rooms for equivalent usage.
+
+## Choosing the Right Room Type
+
+### Decision Matrix
+
+| Use Case               | Room Type  | Why                                         |
+| ---------------------- | ---------- | ------------------------------------------- |
+| Classic video meetings | Conference | Multiple video sources                      |
+| Voice-only meetings    | Audio-only | Cheapest and most performant option         |
+| Live Podcasts          | Audio-only | Cheapest and most performant option         |
+| Sport streaming        | Livestream | Highly scalable and cheaper than conference |
+| Interactive workshop   | Conference | Multiple video sources                      |
+
+## Next Steps
+
+To understand how to implement each room type:
+
+- [How to create audio-only calls](/how-to/features/audio-only-calls)
+- [How to implement livestreaming](/how-to/features/livestreaming)
+
+To learn about the underlying architecture:
+
+- [Fishjam Architecture](/explanation/architecture)
+- [Security & Token Model](/explanation/security-tokens)
+
+Ready to start building? Check our tutorials:
+
+- [React Native Quick Start](/tutorials/react-native-quick-start)
+- [Backend Quick Start](/tutorials/backend-quick-start)