chore: migrate to pnpm and add lightweight monorepo tooling

Author: Loosand

.github/pull_request_template.md

@@ -28,7 +28,7 @@
 
 ## Verification
 
-<!-- List the commands or checks you ran. For example: cd backend && go test ./..., cd frontend && pnpm check, cd frontend && pnpm build. -->
+<!-- List the commands or checks you ran. For example: pnpm check, pnpm test, pnpm build. -->
 
 - [ ] Not run; reason:
 

.github/workflows/frontend-quality.yml

@@ -1,12 +1,17 @@
-name: Frontend Quality
+name: Workspace Quality
 
 on:
   push:
     branches:
       - main
       - dev
     paths:
+      - "backend/**"
       - "frontend/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
       - "scripts/sync-version.mjs"
       - "VERSION"
       - ".github/workflows/frontend-quality.yml"
@@ -15,7 +20,12 @@ on:
       - main
       - dev
     paths:
+      - "backend/**"
       - "frontend/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "pnpm-workspace.yaml"
+      - "turbo.json"
       - "scripts/sync-version.mjs"
       - "VERSION"
       - ".github/workflows/frontend-quality.yml"
@@ -26,11 +36,8 @@ permissions:
 
 jobs:
   quality:
-    name: Biome and TypeScript
+    name: Frontend and backend checks
     runs-on: ubuntu-24.04
-    defaults:
-      run:
-        working-directory: frontend
 
     steps:
       - name: Checkout
@@ -40,17 +47,24 @@ jobs:
         uses: pnpm/action-setup@v4
         with:
           version: 10.17.0
-          run_install: false
 
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
           node-version: 24
           cache: pnpm
-          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: backend/go.mod
+          cache-dependency-path: backend/go.sum
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Run frontend checks
+      - name: Run workspace checks
         run: pnpm check
+
+      - name: Run workspace tests
+        run: pnpm test

.gitignore

@@ -93,6 +93,9 @@ web_modules/
 .cache
 .parcel-cache
 
+# Turborepo cache
+.turbo/
+
 # Next.js build output
 .next
 out

CONTRIBUTING.md

@@ -10,22 +10,22 @@ Thank you for contributing to DEEIX Chat.
 
 ## Development Setup
 
-Backend:
+Install all workspace dependencies:
 
 ```bash
-cd backend
-go test ./...
+pnpm install
 ```
 
-Frontend:
+Run the shared quality and test pipelines:
 
 ```bash
-cd frontend
-pnpm install
-pnpm lint
+pnpm check
+pnpm test
 pnpm build
 ```
 
+Use `pnpm dev`, `pnpm dev:web`, or `pnpm dev:api` for local development.
+
 Use the example configuration files for local development. Do not commit local secrets or production credentials.
 
 ## Pull Request Guidelines
@@ -107,7 +107,7 @@ Core expectations:
 - keep API access inside `shared/api` or feature-level API modules
 - do not hard-code provider-private model behavior in the frontend
 - keep authentication tokens aligned with the existing session model
-- run `pnpm lint`, and run `pnpm build` for routing, dependency, or Next.js changes
+- run `pnpm --filter @deeix/web lint`, and run `pnpm build` for routing, dependency, or Next.js changes
 
 ## Code Style
 

Dockerfile

@@ -2,7 +2,7 @@
 
 FROM node:24-bookworm-slim AS frontend-builder
 
-WORKDIR /src/frontend
+WORKDIR /src
 
 ENV PNPM_HOME=/pnpm
 ENV PATH=$PNPM_HOME:$PATH
@@ -12,17 +12,21 @@ ENV NEXT_PUBLIC_API_BASE_URL=${NEXT_PUBLIC_API_BASE_URL}
 
 COPY VERSION /src/VERSION
 COPY scripts /src/scripts
-COPY frontend/package.json frontend/pnpm-lock.yaml ./
-COPY frontend/scripts ./scripts
-COPY frontend/public/pwa ./public/pwa
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY frontend/package.json ./frontend/package.json
+COPY backend/package.json ./backend/package.json
+COPY frontend/scripts ./frontend/scripts
+COPY frontend/public/pwa ./frontend/public/pwa
 
-RUN corepack enable
+RUN npm install --global pnpm@10.17.0
 
 RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store \
     pnpm config set store-dir /pnpm/store \
-    && pnpm install --frozen-lockfile
+    && pnpm install --frozen-lockfile --filter @deeix/web...
+
+COPY frontend ./frontend
 
-COPY frontend ./
+WORKDIR /src/frontend
 
 # 如果你的 Next 版本支持，可以在 next.config 里开启 turbopack build filesystem cache
 RUN --mount=type=cache,id=next-cache,target=/src/frontend/.next/cache \

README.md

@@ -130,22 +130,21 @@ cp config.example.yaml config.yaml
 
 Adjust `database.postgres.dsn`, `database.redis.*`, and public URLs in `config.yaml` for your local environment.
 
-2. Start the backend:
+2. Install workspace dependencies and prepare the frontend environment:
 
 ```bash
-cd backend
-make run
+pnpm install
+cp frontend/.env.example frontend/.env.local
 ```
 
-3. Start the frontend:
+3. Start the frontend and backend together:
 
 ```bash
-cd frontend
-pnpm install
-cp .env.example .env.local
 pnpm dev
 ```
 
+Use `pnpm dev:web` or `pnpm dev:api` to start only one workspace.
+
 The frontend uses `NEXT_PUBLIC_API_BASE_URL` for API requests. For local development, confirm that `frontend/.env.local` contains:
 
 ```env
@@ -268,9 +267,8 @@ Use this mode when the frontend and backend are served from different public ori
 2. Build and publish the frontend.
 
    ```bash
-   cd frontend
    pnpm install
-   NEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm build
+   NEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm --filter @deeix/web build
    ```
 
    The static output is `frontend/out`. Serve it with Nginx, CDN, object storage, or any static web server. To let the Go backend serve the frontend, place `frontend/out` under `server.frontend_dist_dir`; the Docker image defaults to `/app/frontend/out`.

README.zh-CN.md

@@ -130,22 +130,21 @@ cp config.example.yaml config.yaml
 
 根据本机环境调整 `config.yaml` 中的 `database.postgres.dsn`、`database.redis.*` 和公开访问地址。
 
-2. 启动后端：
+2. 安装工作区依赖并准备前端环境：
 
 ```bash
-cd backend
-make run
+pnpm install
+cp frontend/.env.example frontend/.env.local
 ```
 
-3. 启动前端：
+3. 同时启动前端和后端：
 
 ```bash
-cd frontend
-pnpm install
-cp .env.example .env.local
 pnpm dev
 ```
 
+只启动单个工作区时，使用 `pnpm dev:web` 或 `pnpm dev:api`。
+
 前端请求后端使用 `NEXT_PUBLIC_API_BASE_URL`。本地开发时确认 `frontend/.env.local` 中包含：
 
 ```env
@@ -268,9 +267,8 @@ docker compose -f docker/docling/docker-compose.yml up -d --build
 2. 构建并发布前端。
 
    ```bash
-   cd frontend
    pnpm install
-   NEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm build
+   NEXT_PUBLIC_API_BASE_URL=https://api.example.com pnpm --filter @deeix/web build
    ```
 
    静态产物在 `frontend/out`，可由 Nginx、CDN、对象存储或任意静态服务托管。如需由 Go 后端托管前端，把 `frontend/out` 放到 `server.frontend_dist_dir` 指向的目录；Docker 镜像默认是 `/app/frontend/out`。

backend/docs/swagger.json

@@ -18601,4 +18601,4 @@
             "in": "header"
         }
     }
-}
+}

backend/docs/swagger.yaml

@@ -5468,7 +5468,7 @@ info:
   contact: {}
   description: DEEIX Chat 后端 API 文档
   title: DEEIX Chat API
-  version: 0.3.2
+  version: "0.3.2"
 paths:
   /admin/announcements:
     get:

backend/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@deeix/api",
+  "version": "0.3.2",
+  "private": true,
+  "scripts": {
+    "build": "make build",
+    "check": "make check-version && go vet ./...",
+    "clean": "rm -rf ../.cache/deeix-chat",
+    "dev": "make run",
+    "test": "make test"
+  }
+}