Yoresee Doc Frontend

Vue 3 single-page application for the Yoresee Doc collaborative document platform.

Tech Stack

Category	Technology
Framework	Vue 3 (`<script setup>` SFCs, JavaScript)
Build tool	Vite
UI library	Element Plus
State management	Pinia
Routing	Vue Router
Internationalization	vue-i18n (en-US, zh-CN)
Backend communication	ConnectRPC (gRPC-Web)
Rich text editor	TipTap (collaborative, Yjs-backed)
Markdown editors	EasyMDE, Vditor
Code editor	CodeMirror
Collaborative editing	Yjs + y-websocket
Diff rendering	diff + diff2html
Mind maps	markmap-lib / markmap-view
Spreadsheets	x-data-spreadsheet
CSS preprocessing	Less

Getting Started

Prerequisites

Node.js 20+
npm

Install & Run

npm install
npm run dev

The dev server starts on port 80 (configured for Docker). In local development without Docker, it will attempt port 80 and may need adjustment.

Environment Variables

Set in .env:

Variable	Default	Description
`VITE_API_BASE_URL`	`http://localhost:8080`	REST/gRPC base URL
`VITE_GRPC_WEB_ENDPOINT`	`/grpc`	gRPC-Web endpoint path

Production Build

npm run build    # outputs to dist/
npm run preview  # preview production build

The production Dockerfile (Dockerfile.prod) runs protoc code generation before building. See Protobuf Codegen below.

Project Structure

src/
├── main.js              # App entry: creates Vue app, registers plugins
├── App.vue              # Root component
├── assets/              # Static assets
├── components/          # Vue components
│   ├── base/            # Base/primitive components
│   ├── comment/         # Comment & inline comment
│   ├── document/        # Document-related components
│   ├── knowledge-base/  # Knowledge base components
│   ├── layout/          # Layout shell (nav, sidebar)
│   ├── list/            # List/table components
│   ├── manage/          # System management components
│   ├── shared/          # Shared/reusable components
│   └── template/        # Template components
├── composables/         # Composition API hooks
│   ├── actions/
│   ├── document/
│   ├── knowledge-base/
│   ├── layout/
│   ├── list/
│   ├── notification/
│   ├── shell/
│   ├── template/
│   ├── useMentionInput.js
│   └── usePageTitle.js
├── config/
│   └── baseUrl.js       # API_BASE_URL, GRPC_WEB_ENDPOINT, resolveWithApiBase()
├── i18n/
│   ├── index.js
│   └── locales/
│       ├── en-US.js
│       └── zh-CN.js
├── router/
│   └── index.js         # Route definitions, auth guard, page title sync
├── services/
│   ├── api.js           # Barrel re-export for all API modules
│   ├── api/             # Domain-specific API functions
│   │   ├── shared.js    # unaryCall, messages, mapper helpers
│   │   ├── document.js
│   │   ├── knowledgeBase.js
│   │   ├── template.js
│   │   ├── membership.js
│   │   ├── invitation.js
│   │   ├── setting.js
│   │   ├── notification.js
│   │   └── comment.js
│   ├── auth.js          # Auth API
│   └── grpc_client.js   # ConnectRPC transport, client instances, buildHeaders()
├── store/
│   └── user.js          # Pinia user store (token, userInfo)
├── styles/
│   ├── variables.css    # CSS variables (theming)
│   ├── column-resize.css
│   ├── list-cell.css
│   └── mention.css
├── utils/
│   ├── collabUrl.js     # Collaboration WebSocket URL builder
│   ├── documentType.js  # Document type enum helpers
│   ├── fileUrl.js       # File URL resolution
│   └── tableUtils.js    # Spreadsheet utilities
└── views/
    ├── auth/            # Login, Register
    ├── document/        # Editor, History, Settings, Attachments
    ├── error/           # 404
    ├── knowledge-base/  # Knowledge base list & detail
    ├── manage/          # System admin (users, groups, org, security, invitations)
    ├── template/        # Template list & preview
    ├── user/            # Profile, settings, notifications, invitations
    └── workspace/       # Home, MyDocuments, Search

Key Architecture Notes

Path Alias

@ maps to src/. All internal imports use this alias.

gRPC-Web API Layer

All backend communication goes through ConnectRPC (gRPC-Web):

src/services/grpc_client.js creates the transport and client instances for each service.
src/services/api/*.js wraps unaryCall() with protobuf request construction and response mapping.
src/services/api/shared.js provides common mappers (mapDocument, mapAttachment, etc.) and the unaryCall wrapper that injects auth headers and handles 401 redirects.
src/config/baseUrl.js resolves API_BASE_URL and GRPC_WEB_ENDPOINT.

All gRPC requests must include headers from buildHeaders() (Authorization bearer + accept-language). The unaryCall wrapper handles this automatically.

Authentication

Token stored in localStorage as token
User info stored as JSON in userInfo
Router guard (requiresAuth: true meta) redirects unauthenticated users to /login
On 401 (Unauthenticated) response, token is cleared and user is redirected to /login

Theming

Dark mode is the default
Toggle persists to localStorage key darkMode / theme
Theme is applied early in index.html to avoid flash of unstyled content

Protobuf Codegen

Generated protobuf code lives in src/gen/ (gitignored). It is produced from proto/yoresee_doc/v1/yoresee_doc.proto in the parent repo directory.

During production builds (Dockerfile.prod), protoc runs automatically. For local development, run the repo-level codegen script:

bash ../deploy/script/gen_proto.sh

Generated files include:

src/gen/yoresee_doc/v1/yoresee_doc_pb.js — message types
src/gen/yoresee_doc/v1/yoresee_doc_connect.js — ConnectRPC service definitions

i18n

Locales: en-US, zh-CN
Language preference stored in localStorage as language
Router sets page titles via meta.titleKey (i18n key) or meta.dynamicTitle
Keys are namespaced by feature (e.g., document.settings.title, navigation.home)

Features

Document management: Create, edit, delete, rename documents; organize in folders
Multiple document types: Markdown, rich text (TipTap), spreadsheet, slide
Real-time collaboration: Multi-user editing via Yjs CRDT over WebSocket
Version history: View and compare document versions with side-by-side diff
Knowledge bases: Organize documents into shared knowledge bases with membership controls
Templates: Create and preview document templates
Comments: Inline comments and document-level comments with @mentions
Attachments: Upload, preview, and download file attachments
Search: Full-text document search
Notifications: Comment, reply, mention, and system notifications
System management: User, user group, organization, security, and invitation management
Mind maps: Render Markdown as mind maps via markmap
Dark mode: Default dark theme with toggle