diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 0000000..eda01b4
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,168 @@
+# PackWeave design document
+
+Binary: packweave, pkwv \
+Target platform: Linux, Windows, MacOS
+
+## 1. Overview & Goals
+
+packweave is a high performance minecraft modpack project support tool. It use the modrinth and curseforge as the mod registry, and the toml defination language to describe mod file. Provider a better and convienent way to develop and debug the modpack.
+
+**Key Requirements Met:**
+
+- Represent mod `.jar` files as small, human-readable TOML metadata files
+- Support mods hosted on Modrinth and CurseForge (URL + hash + update metadata)
+- Support local/custom mods not published to any registry
+- Download the Minecraft core jar and mod loader automatically
+- Sync modpack project changes to a real game client directory incrementally
+- Detect and sync extra files created by mods back into the project
+- Import a modpack from CurseForge or Modrinth pack format
+- Export the project to CurseForge and Modrinth pack formats
+- Allow a modpack project to declare another modpack as a dependency
+- Support named mod groups (e.g. `magic`, `tech`) for selective inclusion
+- Detect and resolve mod conflicts when merging multiple modpack dependencies
+- GUI of the cli
+
+## 2. Workspace Architecture
+
+```
+PackWeave/
+├─Cargo.toml
+├─docs/
+├─crates/
+│   ├─packweave-core/           # manifest, sync, resolver, conflict detection
+│   ├─ packweave-pack/          # modrinth/curseforge import-export (optional split)
+│   ├─packweave-network/        # HTTP downloads, hash verification
+│   ├─packweave-cli/            # main cli tool
+│   └─packweave-gui/            # gui tool
+```
+
+## 3. mod description file (packwiz format)
+
+the packwiz format of mod is 
+
+```toml
+name = "Just Enough Items"
+filename = "jei-1.21.1-neoforge.jar"
+side = "both"          # "client" | "server" | "both"
+pin = false            # if true, skip auto-updates
+
+[download]
+
+# optional
+url = "https://..."
+hash-format = "sha512"
+hash = "<hash>"
+
+# nessesary
+mode = ""              # "" or "url" = normal, "metadata:curseforge" = no URL stored, "local" = use local mod file, "git" = custom mod in git repo
+
+[update.modrinth]
+mod-id = "u6dRKJwZ"
+version = "YAcQ6elZ"
+
+# OR
+
+[update.curseforge]
+project-id = 238222
+file-id = 123456
+
+# OR
+
+[update.gitrepo]
+git-url = "https://..."
+branch = ...
+loader = forge | neogforge | fabric | ...
+
+[option]                # optional
+optional = true
+default = true
+description = "Adds item tooltips"
+```
+
+the project define
+```toml
+name = "My Modpack"
+author = "someone"
+version = "1.0.0"
+description = "..."
+pack-format = "packwiz:1.1.0"
+
+[versions]
+minecraft = "1.21.1"
+neoforge = "21.1.0"   # or fabric / quilt / forge
+
+[export]
+# optional, per-format export settings
+# export
+project-id = 123456    # your CurseForge project ID, embedded in the exported zip manifest
+
+[options]
+# optional, merged into viper config
+# example
+acceptable-game-versions = ["1.21", "1.21.1"]   # allow mods from these MC versions
+no-internal-hashes = false                        # whether to skip hashing index files
+```
+
+## 4. Resource download pipline
+
+There are three type of resource need to download.
+
+### 4.1 game client
+
+The mojang provider all the version of minecraft client.\
+https://piston-meta.mojang.com/mc/game/version_manifest_v2.json\
+use this json file to search all the version, and the detail message. It have the directly link of the client.jar, the assest and libraries.
+
+- step 1: download the version manifest
+- step 2: download the client jar
+- step 3: download the libraries incremental
+- step 4: download the assets index json
+- step 5: download the assets
+
+### 4.2 mod loader
+
+#### neoforge/forge
+
+since the neoforge/forge have there own installer(They even don't need the original client.jar).
+- step 1: download the installer
+- step 2: run the installer
+- step 3: download the assest
+- step 4: download the libraries.
+
+#### fabric/quilt
+
+the fabric or quilt don't need the installer.
+- step 1: get available loader versions (https://meta.fabricmc.net/v2/versions/loader)
+- step 2: fetch the version profile
+- step 3: build the version JSON
+- step 4: download the libraries.
+
+
+### 4.3 mod
+
+#### modrinth
+
+every mod on modrinth have their own download link. Just use client to download.
+
+#### curseforge
+
+Downloading from curseforge is more complex.
+- step1: try the api\
+    GET /v1/mods/{projectId}/files/{fileId} with an embedded API key, use downloadUrl if present.
+- step2: construct CDN URL directly\
+    When downloadUrl is null, launchers construct the CurseForge CDN URL 
+- step3: if still fail, prompt user to download manually
+
+## 5. import and export behaviour
+
+## 6. GUI design
+
+## 7. Configuration Structure
+
+## 8. Networking, Proxy & Mirror
+
+## 9. Security & Reliability
+
+## 10. Dependency Matrix
+
+## 11. Testing & CI Strategy