Luogu Saver Next (LGS-NG)

A web application for saving user-generated content (UGC) from www.luogu.com.cn.

简体中文 | English

Description

Luogu Saver Next (LGS-NG) is a web application designed to help users save and manage user-generated content from Luogu, a popular Chinese competitive programming platform. This tool allows users to archive articles, pastes, and other content types, ensuring that valuable information is preserved and remains easily accessible.

Features

• Content Archiving: Save articles and pastes directly from Luogu.
• Management UI: User-friendly interface for organizing saved content.
• Broad Support: Handles multiple content types efficiently.
• High Performance: Utilizes client-side rendering for a smooth user experience.
• Responsive Design: Optimized for use on desktops, tablets, and mobile devices.
• Intelligent Recommendations: Suggests related content based on user activity.

Architecture

This project is a Monorepo managed by npm workspaces:

• Root: Manages shared dev-dependencies (Prettier, TypeScript, etc.) and orchestration.
• packages/frontend: Vue 3 + Vite application (Naive UI).
• packages/backend: Koa + TypeScript API service.
• Infrastructure: External services (Database, etc.) managed via Docker Compose.

Prerequisites

Ensure you have the following installed:

• Node.js (version 22.18.0 or higher)
• Docker & Docker Compose (for infrastructure services)

Infrastructure Setup

Before building or running the application for local development, initialize the required external services. The root docker-compose.yml is a local infrastructure profile for development and single-host testing. It binds service ports to 127.0.0.1 so MariaDB, Redis, Chroma, and Meilisearch are reachable from the host only.

Note: This Compose file only manages external infrastructure. The Node.js application itself is run separately on the host. Do not use this file as a production infrastructure plan without replacing all default credentials and keeping service ports off public interfaces.

Start the local infrastructure in the background:

docker compose up -d

Build Instructions

1. Clone the Repository

git clone https://github.com/Ark-Aak/luogu-saver-next.git
cd luogu-saver-next

2. Install Dependencies

Install dependencies for the root and all workspaces in one go:

npm install

3. Build

You can build the entire project (Frontend & Backend) with a single command:

npm run build

Or build them individually using npm workspaces:

Frontend Only:

# Optional: Set environment variables inline
# VITE_API_URL=[https://api.example.com](https://api.example.com) npm run build -w @luogu-saver-next/frontend
npm run build -w @luogu-saver-next/frontend

The compiled static files will be located in packages/frontend/dist.

Backend Only:

npm run build -w @luogu-saver-next/backend

The compiled backend files will be located in packages/backend/dist.

Development

We use concurrently to run both frontend and backend in watch mode with a single command.

1. Start Infrastructure

Ensure your database and other services are running:

docker compose up -d

2. Start Development Server

In the project root, run:

npm run dev

This will:

1. Start the Frontend (Vite) in watch mode.
2. Start the Backend (ts-node-dev) in watch mode.
3. Output logs from both services in the same terminal (color-coded).

Deployment

1. Prepare Infrastructure

Provision production MariaDB, Redis, Chroma, and Meilisearch instances using a managed service or a production-specific Compose/Kubernetes configuration. Do not run the repository root docker-compose.yml as the production infrastructure plan.

Before starting the backend, ensure all of the following conditions are true:

• MariaDB, Redis, Chroma, and Meilisearch accept connections only from the backend host or from a private network.
• Public internet clients cannot connect directly to ports 3306, 6379, 8000, or 7700.
• MariaDB, Redis, and Meilisearch use non-default secrets.
• Chroma is protected by the network boundary used for backend-only infrastructure access.

2. Run the Backend Server

Navigate to the backend workspace or run directly from the root:

cd packages/backend
# Install production dependencies only
npm install --production
# Start the server
node dist/index.js

The server will start on the configured port (default is 3000).

3. Serve the Frontend

You need a web server (e.g., Nginx or Caddy) to serve the static files located in: packages/frontend/dist

4. Configuration & Proxying

If you did not set the VITE_API_URL variable during the frontend build, the application defaults to sending requests to /api on the same domain.

Crucial Step: You must configure your web server (Nginx/Caddy) to reverse proxy requests starting with /api to the running backend service (e.g., localhost:3000).

Contributing

Contributions are welcome! To contribute to Luogu Saver Next:

1. Fork the repository on GitHub.
2. Create a new branch for your feature or bug fix.
3. Commit your changes with clear, descriptive messages.
4. Push your changes to your forked repository.
5. Open a Pull Request to the main repository.

Please ensure your code adheres to the project's coding standards (Prettier) and includes appropriate tests.