diff --git a/README.md b/README.md
index c155dfdd..2f95f90e 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,17 @@ Bring projects, wikis, and teams together with AI
+## Table of Contents
+
+- [Use Cases](#use-cases)
+- [Features](#features)
+- [AppFlowy Web Roadmap](#appflowy-web-roadmap)
+- [Installation](#installation)
+- [Development](#development)
+- [Deployment](#deployment)
+- [Documentation](#documentation)
+- [License](#license)
+
## Use cases
- Build and maintain a knowledge base for your team
- Create and publish documentation for your customers and audience
@@ -36,15 +47,6 @@ Bring projects, wikis, and teams together with AI
- Invite members to your workspace for seamless collaboration
- Create multiple public and private spaces to better organize your content
-## AppFlowy Web roadmap
->Features listed below are available in AppFlowy desktop and mobile applications (Download).
-
-Q1 2025:
-- Templates
-- Favorite pages
-- Import and export markdown files
-- More document features incl. simple table and column layout
-- AI Chat and AI Writer
## Installation
### Cloud: we host AppFlowy for you
@@ -62,32 +64,19 @@ Join our Discord server to get help!
## Development
-### Pre-requisite
-AppFlowy Cloud must be running and accessible by AppFlowy Web. If you alredy have AppFlowy Cloud running, you can skip this step.
-For local development, please follow the steps below:
-1. Install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
-2. Clone the AppFlowy Cloud repository.
-3. Copy deploy.env to .env, then run `docker-compose up -d`.
-4. The AppFlowy Cloud API should be running on localhost:80, and allow CORS from localhost:3000 by default.
-5. Setup at least one sign in method: SMTP for magic link, or using an OAuth provider. Refer to AppFlowy Cloud repository for more details.
-
-### Running AppFlowy Web Locally
-1. Copy .development.env to .env. The default value assumes that AppFlowy Cloud is deployed on localhost. If not, please update the value of the API endpoints.
-2. Make sure `npm` has been installed on your dev environment, then run the following:
-```
-corepack enable
-pnpm install
-
-pnpm run dev
-```
-
-Open your browser to visit localhost:3000
+Check out the [development guide](./doc/DEVELOPMENT_GUIDE.md) for more details
## Deployment
Once AppFlowy Cloud has been setup, you can follow the [deployment guide](https://appflowy.com/docs/self-host-appflowy-run-appflowy-web)
to deploy AppFlowy Web.
+## Documentation
+
+- **[Deployment Guide](doc/DEPLOYMENT.md)** - Detailed environment configuration, architecture diagrams, and troubleshooting
+- **[AppFlowy Cloud Repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud)** - Backend setup and configuration
+- **[Official Documentation](https://appflowy.com/docs)** - Complete AppFlowy documentation
+
## License
Distributed under the AGPLv3 License. See [`LICENSE.md`](https://github.com/AppFlowy-IO/AppFlowy-Web/blob/main/LICENSE) for
more information.
diff --git a/.development.env b/deploy.env
similarity index 100%
rename from .development.env
rename to deploy.env
diff --git a/dev.env b/dev.env
new file mode 100644
index 00000000..dcde6f63
--- /dev/null
+++ b/dev.env
@@ -0,0 +1,4 @@
+AF_BASE_URL=http://localhost:8000
+AF_GOTRUE_URL=http://localhost:9999
+AF_WS_URL=ws://localhost:8000/ws/v1
+AF_WS_V2_URL=ws://localhost:8000/ws/v2
\ No newline at end of file
diff --git a/doc/DEVELOPMENT_GUIDE.md b/doc/DEVELOPMENT_GUIDE.md
new file mode 100644
index 00000000..076855d3
--- /dev/null
+++ b/doc/DEVELOPMENT_GUIDE.md
@@ -0,0 +1,91 @@
+## 🎯 Overview
+
+AppFlowy Web requires AppFlowy Cloud as its backend. You can set up this pair in two ways:
+
+- **🛠️ Development Mode** (`dev.env`) - For local development and testing
+- **🚀 Production Mode** (`deploy.env`) - For production deployments with Docker
+
+## 📋 Prerequisites
+
+Before you begin, ensure you have:
+
+- **Node.js** ≥18.0.0
+- **pnpm** ≥10.9.0
+- **Docker & Docker Compose** (required for both modes)
+
+## 🛠️ Development Mode Setup
+
+**Best for:** Local development, testing, and debugging individual services.
+
+### Step-by-Step Setup
+
+#### 1. Set Up AppFlowy Cloud (Development)
+
+```bash
+# Clone AppFlowy Cloud repository
+git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git
+cd AppFlowy-Cloud
+
+# Use development configuration
+cp dev.env .env
+
+# Start development server
+./script/run_local_server.sh
+```
+
+#### 2. Set Up AppFlowy Web (Development)
+
+```bash
+# In a new terminal, navigate to your AppFlowy Web directory
+cd /path/to/appflowy-web
+
+# Use matching development configuration
+cp dev.env .env
+
+# Install dependencies and start
+corepack enable
+pnpm install
+pnpm run dev
+```
+
+
+## 🚀 Production Mode Setup
+
+**Best for:** Production deployments, staging environments, and containerized setups.
+
+
+#### 1. Set Up AppFlowy Cloud (Production)
+
+```bash
+# Clone AppFlowy Cloud repository
+git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git
+cd AppFlowy-Cloud
+
+# Use production configuration
+cp deploy.env .env
+
+# Start with Docker Compose
+docker compose up -d
+```
+
+#### 2. Set Up AppFlowy Web (Production)
+
+```bash
+# In a new terminal, navigate to your AppFlowy Web directory
+cd /path/to/appflowy-web
+
+# Use matching production configuration
+cp deploy.env .env
+
+# Install dependencies and start
+corepack enable
+pnpm install
+pnpm run dev
+```
+
+## 🔗 Additional Resources
+
+- **[AppFlowy Cloud Repository](https://github.com/AppFlowy-IO/AppFlowy-Cloud)** - Backend setup and configuration
+- **[AppFlowy Web README](../README.md)** - Frontend development guide
+- **[AppFlowy Documentation](https://appflowy.com/docs)** - Official product documentation
+- **[AppFlowy GitHub Discussions](https://github.com/AppFlowy-IO/AppFlowy/discussions)** - Community support