frontend/docs/README.md

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):

1. src/services/grpc_client.js creates the transport and client instances for each service.
2. src/services/api/*.js wraps unaryCall() with protobuf request construction and response mapping.
3. src/services/api/shared.js provides common mappers (mapDocument, mapAttachment, etc.) and the unaryCall wrapper that injects auth headers and handles 401 redirects.
4. 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