yorkie-team · hackerwins · Feb 6, 2026 · Feb 6, 2026
diff --git a/docs/advanced.mdx b/docs/advanced.mdx
@@ -1,23 +1,24 @@
 ---
-title: 'Advanced'
+title: 'Configuration'
 order: 110
 ---
 
-## Advanced
+## Configuration
 
-This section covers advanced topics for building production-ready applications with Yorkie. These guides are designed for users who are already familiar with basic Yorkie concepts and want to dive deeper into data formats, security configurations, and architectural patterns.
+This section covers configuration and integration topics for building production-ready applications with Yorkie. These guides help you design your architecture, secure your application, and configure project-level settings.
 
 ### Topics
 
 - **[Architecture Patterns](/docs/advanced/architecture-patterns)**: Explore recommended architectural patterns for integrating Yorkie with your existing systems
 - **[Security](/docs/advanced/security)**: Configure allowed origins and Auth Webhooks to secure your Yorkie applications
-- **[YSON](/docs/advanced/yson)**: Learn about Yorkie Structured Object Notation, the data format used to represent documents with specialized types for collaborative editing
+- **[Event Webhook](/docs/advanced/event-webhook)**: Receive notifications when specific events occur in your Yorkie documents
 - **[Revisions](/docs/advanced/revisions)**: Implement version control with snapshots, history browsing, and restore functionality
 - **[Resources](/docs/advanced/resources)**: Configure project-level settings for document limits, snapshots, and lifecycle behavior
+- **[Projects](/docs/advanced/projects)**: Organize multiple applications with project-based isolation, API keys, and per-project configuration
 
 ### Prerequisites
 
-Before exploring these advanced topics, ensure you have:
+Before exploring these topics, ensure you have:
 1. Completed the [Getting Started guide](/docs/getting-started)
 2. Built at least one application using Yorkie SDKs
 3. Understood basic concepts like [Client](/docs/js-sdk#client), [Document](/docs/js-sdk#document), and [Channel](/docs/js-sdk#channel)

diff --git a/docs/advanced/architecture-patterns.mdx b/docs/advanced/architecture-patterns.mdx
@@ -22,7 +22,7 @@ If you're new to Yorkie, we recommend:
 In this pattern, your existing database serves as the Source of Truth, while your server manages the document lifecycle through Yorkie's Admin API. This approach provides centralized control over document creation and deletion, making it suitable for applications that require strict server-side governance.
 
 **Key Characteristics:**
-- Server creates and deletes documents via [Admin API](/docs/admin-api#documents-management)
+- Server creates and deletes documents via [Admin API](/docs/tools/admin-api#documents-management)
 - Clients edit documents directly through Yorkie SDK during collaboration
 - Explicit "Save" action persists content to your database
 - Server maintains full control over document lifecycle
@@ -49,7 +49,7 @@ sequenceDiagram
 ```
 
 1. Client requests document creation from your server
-2. Server creates a new document through [Yorkie Admin API](/docs/admin-api#post-yorkiev1adminservicecreatedocument)
+2. Server creates a new document through [Yorkie Admin API](/docs/tools/admin-api#post-yorkiev1adminservicecreatedocument)
 3. Server stores document metadata in your database
 4. Server returns document key to client
 5. Client [attaches](/docs/js-sdk#attaching-the-document) to the document using the provided key
@@ -139,7 +139,7 @@ This pattern also uses your external database as the Source of Truth, but delega
 **Key Characteristics:**
 - Server only provides document keys and initial content
 - Clients create and manage documents independently
-- Automatic document cleanup via `RemoveOnDetach` project setting (configure via [CLI](/docs/cli#updating-the-project) or Dashboard)
+- Automatic document cleanup via `RemoveOnDetach` project setting (configure via [CLI](/docs/tools/cli#updating-the-project) or Dashboard)
 - Explicit "Save" action persists content to your database
 
 **Document Creation Flow:**
@@ -306,7 +306,7 @@ sequenceDiagram
     S-->>C: Deletion confirmed
 ```
 
-1. Client or server removes document via [Yorkie Admin API](/docs/admin-api#post-yorkiev1adminserviceremovedocument)
+1. Client or server removes document via [Yorkie Admin API](/docs/tools/admin-api#post-yorkiev1adminserviceremovedocument)
 2. Server removes document metadata from your database
 3. Document content is automatically removed from Yorkie
 
@@ -345,7 +345,7 @@ Explore real-world examples implementing these patterns:
 
 For more information about Yorkie's API and features:
 - [JS SDK Documentation](/docs/js-sdk) - Client and Document API reference
-- [Admin API](/docs/admin-api) - Admin API for server-side management
+- [Admin API](/docs/tools/admin-api) - Admin API for server-side management
 - [Security Configuration](/docs/advanced/security) - Auth Webhook and access control
-- [CLI](/docs/cli) - Command-line tools for project management
+- [CLI](/docs/tools/cli) - Command-line tools for project management
 - [Glossary](/docs/glossary) - Key terminology and concepts
diff --git a/docs/advanced/event-webhook.mdx b/docs/advanced/event-webhook.mdx
@@ -151,5 +151,5 @@ app.listen(3000, () => {
 ### Related Documentation
 
 - [Auth Webhook](/docs/advanced/security#auth-webhook) - For authorization and access control
-- [CLI Reference](/docs/cli) - Complete CLI command reference
+- [CLI Reference](/docs/tools/cli) - Complete CLI command reference
 - [Architecture Patterns](/docs/advanced/architecture-patterns) - Document lifecycle patterns
diff --git a/docs/advanced/projects.mdx b/docs/advanced/projects.mdx
@@ -0,0 +1,167 @@
+---
+title: 'Projects'
+order: 119
+---
+
+## Projects
+
+A **Project** in Yorkie is a logical grouping that isolates documents, channels, and clients. Projects enable multi-tenancy, allowing you to run multiple independent applications or environments within a single Yorkie installation.
+
+### Overview
+
+Every Yorkie installation starts with a `default` project that is created automatically. When a [Client](/docs/js-sdk#client) connects without specifying an API key, it is placed in the default project. For production applications, you should create dedicated projects to isolate data and configure settings independently.
+
+```mermaid
+graph TB
+    subgraph Server["Yorkie Server"]
+        subgraph P1["Project: my-app-prod"]
+            D1["Documents"]
+            C1["Channels"]
+            CL1["Clients"]
+        end
+        subgraph P2["Project: my-app-staging"]
+            D2["Documents"]
+            C2["Channels"]
+            CL2["Clients"]
+        end
+        subgraph P3["Project: another-app"]
+            D3["Documents"]
+            C3["Channels"]
+            CL3["Clients"]
+        end
+    end
+```
+
+### Project Isolation
+
+Each project provides complete isolation:
+
+- **Documents** in one project are invisible to clients in another project. A document key like `doc-1` can exist independently in multiple projects.
+- **Channels** are scoped to their project. Broadcast messages and presence updates only reach clients within the same project.
+- **Clients** belong to exactly one project, determined by the API key they use to connect.
+- **Configuration** (auth webhooks, event webhooks, resource limits, housekeeping thresholds) is set per project.
+
+### API Keys
+
+Each project has two keys:
+
+| Key | Purpose | Usage |
+|-----|---------|-------|
+| **Public Key** | Identifies the project for client connections | Used as `apiKey` when creating a [Client](/docs/js-sdk#client) |
+| **Secret Key** | Authenticates server-side applications | Used in the `authorization` header for [Admin API](/docs/tools/admin-api) requests |
+
+```javascript
+// Connect a client to a specific project using its public key
+const client = new yorkie.Client({
+  rpcAddr: '{{API_ADDR}}',
+  apiKey: 'your-project-public-key',
+});
+```
+
+> Keep your **Secret Key** confidential. It grants full access to manage documents within the project via the [Admin API](/docs/tools/admin-api). Never expose it in client-side code.
+
+### Managing Projects
+
+Projects are managed through the [CLI](/docs/tools/cli#project) or the [Dashboard]({{DASHBOARD_PATH}}).
+
+#### Creating a Project
+
+```bash
+$ yorkie project create my-app-prod
+```
+
+This returns the project details including both keys:
+
+```json
+{
+  "name": "my-app-prod",
+  "public_key": "...",
+  "secret_key": "...",
+  "created_at": "..."
+}
+```
+
+#### Listing Projects
+
+```bash
+$ yorkie project ls
+```
+
+#### Updating a Project
+
+Configure project settings such as auth webhooks, event webhooks, and resource limits:
+
+```bash
+# Set an auth webhook URL
+$ yorkie project update my-app-prod --auth-webhook-url https://my-server.com/auth
+
+# Configure event webhooks
+$ yorkie project update my-app-prod \
+  --event-webhook-url https://my-server.com/events \
+  --event-webhook-events-add DocumentRootChanged
+
+# Set resource limits
+$ yorkie project update my-app-prod \
+  --max-attachments-per-document 50 \
+  --max-subscribers-per-document 100
+
+# Configure housekeeping
+$ yorkie project update my-app-prod \
+  --client-deactivate-threshold 24h
+```
+
+For the full set of update options, see [Updating the Project](/docs/tools/cli#updating-the-project).
+
+### Per-Project Configuration
+
+Each project can be independently configured with the following settings:
+
+| Setting | Description | Reference |
+|---------|-------------|-----------|
+| **Auth Webhook** | External authentication endpoint for validating client requests | [Security: Auth Webhook](/docs/advanced/security#auth-webhook) |
+| **Event Webhook** | Notification endpoint for document events | [Event Webhook](/docs/advanced/event-webhook) |
+| **Allowed Origins** | CORS restrictions for client connections | [Security: Allowed Origins](/docs/advanced/security#allowed-origins) |
+| **Max Attachments** | Maximum clients that can attach to a single document | [Document Limits](/docs/js-sdk#document-limits) |
+| **Max Subscribers** | Maximum clients that can subscribe to a single document | [Document Limits](/docs/js-sdk#document-limits) |
+| **Client Deactivate Threshold** | Time after which inactive clients are automatically deactivated by [Housekeeping](/docs/glossary) | [CLI](/docs/tools/cli#updating-the-project) |
+
+### Common Patterns
+
+#### Separate Environments
+
+Create distinct projects for development, staging, and production:
+
+```bash
+$ yorkie project create my-app-dev
+$ yorkie project create my-app-staging
+$ yorkie project create my-app-prod
+```
+
+Use environment variables in your application to select the appropriate API key:
+
+```javascript
+const client = new yorkie.Client({
+  rpcAddr: process.env.YORKIE_RPC_ADDR,
+  apiKey: process.env.YORKIE_API_KEY,
+});
+```
+
+#### Multiple Applications
+
+If you host multiple collaborative applications on a single Yorkie server, create a project for each:
+
+```bash
+$ yorkie project create docs-app
+$ yorkie project create whiteboard-app
+$ yorkie project create chat-app
+```
+
+Each application's documents, channels, and client data remain fully isolated.
+
+### Further Reading
+
+- [CLI: Project Management](/docs/tools/cli#project) -- Full CLI reference for project commands
+- [Admin API](/docs/tools/admin-api) -- Server-side document management using the project's secret key
+- [Security](/docs/advanced/security) -- Configuring auth webhooks and allowed origins
+- [Resources](/docs/advanced/resources) -- Configuring project-level resource limits
+- [Glossary](/docs/glossary) -- Definitions of all key terms
diff --git a/docs/advanced/resources.mdx b/docs/advanced/resources.mdx
@@ -13,7 +13,7 @@ Resource settings can be configured through:
 
 - **CLI**: Using `yorkie project update` command
 - **Dashboard**: Through the project settings page
-- **Admin API**: Using the [UpdateProject](/docs/admin-api#post-yorkiev1adminserviceupdateproject) endpoint
+- **Admin API**: Using the [UpdateProject](/docs/tools/admin-api#post-yorkiev1adminserviceupdateproject) endpoint
 
 ### Document Limits
 
@@ -188,7 +188,7 @@ yorkie project update my-project \
 
 ### Related Documentation
 
-- [CLI Reference](/docs/cli) - Complete CLI command reference
-- [Admin API](/docs/admin-api) - API for project management
+- [CLI Reference](/docs/tools/cli) - Complete CLI command reference
+- [Admin API](/docs/tools/admin-api) - API for project management
 - [Architecture Patterns](/docs/advanced/architecture-patterns) - Document lifecycle patterns
 - [JS SDK - Document Events](/docs/js-sdk#documentsubscribesnapshot) - Handling snapshot events
diff --git a/docs/advanced/revisions.mdx b/docs/advanced/revisions.mdx
@@ -13,7 +13,7 @@ Revisions are immutable snapshots of a document's state stored on the server. Ea
 
 - **Label**: A user-friendly identifier (e.g., "v1.0", "Draft", "Final")
 - **Description**: Optional detailed explanation of what changed
-- **Snapshot**: The complete document state in [YSON](/docs/advanced/yson) format
+- **Snapshot**: The complete document state in [YSON](/docs/internals/yson) format
 - **Timestamp**: When the revision was created
 - **Server Sequence**: The document's server sequence number at creation time
 
@@ -29,7 +29,7 @@ Revisions are immutable snapshots of a document's state stored on the server. Ea
 
 This guide assumes familiarity with:
 1. [Client](/docs/js-sdk#client) and [Document](/docs/js-sdk#document) basics
-2. [YSON format](/docs/advanced/yson) for understanding snapshots
+2. [YSON format](/docs/internals/yson) for understanding snapshots
 
 ### How Revisions Work
 
@@ -298,7 +298,7 @@ When enabled:
 - Labels follow the format: `snapshot-{serverSeq}`
 - Descriptions: `Auto created revision of snapshot #{serverSeq}`
 
-Configure via the Dashboard or [Admin API](/docs/admin-api#post-yorkiev1adminserviceupdateproject). See [Resources](/docs/advanced/resources#autorevisionenabled) for details.
+Configure via the Dashboard or [Admin API](/docs/tools/admin-api#post-yorkiev1adminserviceupdateproject). See [Resources](/docs/advanced/resources#autorevisionenabled) for details.
 
 ### Best Practices
 
@@ -341,6 +341,6 @@ Revision operations require appropriate document permissions:
 ### Related Documentation
 
 - [JS SDK - Document Revisions](/docs/js-sdk#document-revisions) - Complete API reference
-- [YSON](/docs/advanced/yson) - Understanding snapshot format
+- [YSON](/docs/internals/yson) - Understanding snapshot format
 - [Resources](/docs/advanced/resources) - Project configuration including auto-revisions
 - [CodePair](https://github.com/yorkie-team/codepair) - Reference implementation
diff --git a/docs/advanced/security.mdx b/docs/advanced/security.mdx
@@ -55,7 +55,7 @@ You can set up the Auth Webhook via the [Dashboard]({{DASHBOARD_PATH}}):
 
 <Image alt="setting auth-webhook" src="/assets/images/docs/auth-webhook-dashboard.png" width={1300} height={840} style={{ maxWidth: '1000px' }} />
 
-Alternatively, configure the webhook using the Yorkie CLI. See [Updating the Project](/docs/cli#updating-the-project) for details.
+Alternatively, configure the webhook using the Yorkie CLI. See [Updating the Project](/docs/tools/cli#updating-the-project) for details.
 
 ##### 2. Client Configuration