Memorains Note - Project Documentation

Project Overview

Memorains is a comprehensive note-taking application that integrates rich text editing with canvas drawing capabilities. It supports both online and offline use, as well as multi-user and multi-device collaboration.

Core Technologies

Client (Frontend):

• Framework: React 18 with TypeScript
• Build Tool: Vite
• Rich Text Editor: Quill (with extensions for tables, cursors, image compression, markdown shortcuts)
• Canvas Drawing: Excalidraw
• Collaboration: Yjs (CRDT-based conflict-free synchronization)
• UI Library: Material-UI (MUI) v6
• Desktop App: Electron
• Routing: React Router v6

Server (Backend):

• Runtime: Node.js with TypeScript
• Framework: Express.js
• Database: MariaDB
• Real-time Communication: WebSocket (ws)
• Authentication: JSON Web Tokens (JWT)

Infrastructure:

• Containerization: Podman/Docker
• Web Server: Nginx (reverse proxy + SSL termination)
• Database: MariaDB

Architecture

The project follows a client-server architecture with real-time collaboration:

┌─────────────────┐         ┌──────────────────┐         ┌──────────────┐
│   Web Browser   │         │   Nginx (HTTPS)  │         │   MariaDB    │
│   Desktop App   │◄───────►│   Reverse Proxy  │◄───────►│   Database   │
│   Mobile App    │         └──────────────────┘         └──────────────┘
└─────────────────┘                   │
                                      │
                                      ▼
                            ┌──────────────────┐
                            │  Node.js Server  │
                            │  (Express + WS)  │
                            └──────────────────┘

Key Features:

• Three note types: Rich text editor, Infinite canvas, and Todo list editor
• Conflict-free collaboration using Yjs CRDT
• Multi-device/user real-time sync
• Online & offline support
• Cross-platform clients: Web, Desktop (Linux/Windows/macOS), Mobile (Android/iOS)

Todo List Editor Features

The TodoListEditor (client/src/editor/TodoListEditor.tsx) provides:

• Task creation and management
• Task completion tracking
• Deadline setting with visual indicators (overdue, urgent, upcoming)
• Real-time collaborative editing via Yjs
• Clear completed tasks functionality
• Edit and delete individual tasks
• Sort by completion status

---

Building and Running

Prerequisites

• Podman or Docker (for containerized deployment)
• Node.js (for development)
• SSL Certificate (for HTTPS)

Development Setup

Client Development

cd client
npm install
npm run dev

This starts a Vite dev server at http://localhost:5173 (or similar).

Server Development

cd server
npm install
npm run build      # Compile TypeScript
npm run server     # Start server (requires running database)

For full development with containers:

cd server
npm run dev        # Starts containers + TypeScript watch mode

Production Deployment

1. Build Application Package

cd script
bash build_package.sh

This creates package.tar.gz containing:

• Compiled client (client/dist)
• Server source + build (server/src, server/build)
• Database schema (server/DB)
• Docker/Podman compose files
• Nginx configuration

2. Prepare SSL Certificate

On the server:

mkdir ~/certificate
# Place your SSL certificate and key here:
# ~/certificate/cert.pem
# ~/certificate/cert.key

3. Deploy and Run

tar -zxvf package.tar.gz
cd package
podman compose up -d
# or: docker compose up -d

4. Access Application

Open in browser: https://your-host/doc/client/

---

Development Conventions

Code Style

TypeScript:

• Strict mode enabled ("strict": true)
• ES2020 target for server
• CommonJS module system for server
• ESM for client

Linting:

• ESLint configured for both client and server
• Prettier for code formatting
• Pre-commit hooks recommended

Client Structure:

client/src/
├── components/     # Reusable UI components
├── const/          # Constants and configurations
├── DB/             # Database/local storage utilities
├── editor/         # Editor components
│   ├── CommonEditor.tsx          # Base editor interface
│   ├── QuillEditor.tsx           # Rich text editor
│   ├── ExcalidrawEditor.tsx      # Canvas drawing editor
│   └── TodoListEditor.tsx        # Task management editor
├── hooks/          # Custom React hooks
├── interface/      # TypeScript interfaces/types
├── internationnalization/  # i18n support
├── pages/          # Route pages
└── utils/          # Utility functions

Server Structure:

server/src/
├── build/          # Compiled JavaScript output
├── DB/             # Database schema and migrations
├── src/            # TypeScript source files
└── post-test/      # Test utilities

Testing

Client:

• No formal test framework currently configured
• Desktop testing: npm run desktop:test (placeholder)

Server:

• No test framework currently configured
• npm run test returns error placeholder

Build Process

Client Build:

1. TypeScript compilation
2. Vite bundling
3. Excalidraw assets copy (fonts)
4. Version management (sw-version.js)

Server Build:

1. TypeScript compilation to build/ directory
2. Output is executable Node.js code

Package Build:

1. Build client assets
2. Copy server source + compiled code
3. Include database schema
4. Include infrastructure configs (docker-compose, nginx)
5. Create tarball

Environment Variables

Server:

• NODE_ENV=production (in docker-compose)
• IS_DEV=true (for development mode)

Database (docker-compose):

• MYSQL_ROOT_PASSWORD=123456
• MYSQL_DATABASE=document
• MYSQL_USER=doc
• MYSQL_PASSWORD=123456

Networking

Docker Network:

• Bridge network: reno_note_app_network
• Services communicate via container names:
  • reno_note_mariadb
  • reno_note_nodejs
  • reno_note_nginx

Ports:

• 80: HTTP (nginx)
• 443: HTTPS (nginx with SSL)
• 8000: Node.js server (internal)
• Dynamic WebSocket ports: Range 8000-8999 (proxied via nginx)

WebSocket Proxy:

• Nginx routes /doc/websocket/port_XXXX/* to Node.js on port XXXX
• Supports long-lived connections (1800s timeout)

---

Key Dependencies

Client

• @excalidraw/excalidraw: Canvas drawing
• quill: Rich text editor
• yjs: CRDT for collaboration
• y-quill: Quill binding for Yjs
• @mui/material: UI components
• react-router-dom: Routing
• electron: Desktop app framework

Server

• express: Web framework
• ws: WebSocket server
• mariadb: Database driver
• jsonwebtoken: Authentication
• yjs: CRDT support

---

Third-Party Licenses

See third-party-license/ directory for detailed license information.

Main libraries:

• quill - Rich text editor
• excalidraw - Canvas drawing
• material-ui - UI components (used in all editors)
• yjs - CRDT for collaboration (used in all editors)

---

Notes for Future Development

1. Database Initialization: The README mentions database initialization is no longer needed (commented out). Verify if migrations are handled automatically.

2. Electron Desktop App: Client has Electron configuration (forge.config.cjs, electron/ directory) for desktop builds. Use npm run desktop:package or desktop:make for platform-specific builds.

3. Mobile Support: While mentioned in features, mobile implementation details are not visible in the current structure. May require separate mobile app or PWA setup.

4. Testing: Both client and server lack formal test suites. Consider adding Jest/Vitest for client and Jest/Mocha for server.

5. Security: Current setup uses hardcoded credentials in docker-compose. For production, use environment variables or secrets management.

6. SSL: Certificate must be manually placed in ~/certificate/ on the server. Consider automated certificate management (Let's Encrypt).

7. Offline Support: Yjs provides offline capabilities, but implementation details should be verified for data persistence.

8. Multi-platform Builds: Desktop app supports Linux/Windows/macOS via Electron Forge. Use desktop:make:win for Windows cross-compilation.

---

Quick Reference Commands

# Development
cd client && npm run dev
cd server && npm run build && npm run server

# Production Build
cd script && bash build_package.sh

# Deployment
tar -zxvf package.tar.gz && cd package && podman compose up -d

# Desktop App
cd client && npm run desktop:dev
cd client && npm run desktop:package
cd client && npm run desktop:make

# Server Management
cd server && npm run build
cd server && npm run dev  # with containers

---

Project Metadata

• Version: Client v0.8.65, Server v1.0.0
• License: MIT
• Repository: https://github.com/redTreeOnWall/memorains
• Demo: https://note.lirunlong.com/doc/client/