• Renda Zhang · Lightweight Website
  • Introduction
  • PersonalWeb Project Overview
  • Tech Stack
    • Directory Structure
    • Reference Architecture
  • Frontend
    • Architecture Overview
      • BaseLayout Component Design Notes
    • Local Development & Preview
      • GitHub Actions
      • Usage Guide
    • Website Features
      • Page Functionality
      • Page Navigation
      • Page Content
      • Page Optimization
      • Color Scheme
  • Backend
  • Nginx Server
  • Documentation
    • Git Branching & Release Workflow
    • CI/CD Workflow
    • Operations Maintenance Guide
    • Dependency Security Risk Register
    • Astro 7 Upgrade Precheck
    • Astro 6 Migration Precheck
    • Frontend Architecture Conventions
    • Frontend Directory Ownership Map
    • Chat Widget Protocol
    • Frontend Experience Platform RFC
    • Interaction Component Standards
    • Human Voice And Personal Expression
    • Content And Credibility Positioning
    • Site Intelligence And Visitor Journey
    • Portfolio Proof And Visitor Conversion
    • Chat Guide Quality Architecture
    • SEO / GEO Maintenance
    • BUG Tracking
    • Development Requirements
    • User Authentication and Password Reset Specification
    • Native to Astro + React Migration
    • Responsive Image System Maintenance
    • Error Tracking
    • Utilities Reference
    • Comprehensive Pre-Commit Guide
    • Style System Description
  • 🤝 Contribution Guide
  • 🔒 Open Source License
  • 📬 Contact

Renda Zhang · Lightweight Website

• Author: Renda Zhang
• Last Updated: August 08, 2026, 11:40 (UTC+08:00)

Introduction

点击这里查看 Github 上的中文版

This is my personal website and an evolving public engineering project. It brings a bilingual portfolio, AI Chat, technical documentation, tests, and automated delivery into one inspectable repository.

Live Site: 🌐 www.rendazhang.com

The public pages also include SEO/GEO, structured data, and an AI-summary entry point.

PersonalWeb Project Overview

I maintain PersonalWeb as both a bilingual portfolio and a working engineering project. Astro generates the main pages as static HTML, while React handles navigation, theme and language controls, forms, certification details, and Chat.

AI Chat is available as a direct page and as a floating homepage window. Both use a same-origin route to the Flask backend. Guided questions use public site and repository information, while ordinary Chat keeps its existing request path.

Vitest, Playwright browser checks, Astro builds, and GitHub Actions provide a repeatable validation and delivery path. The repository also documents the boundaries between the frontend, backend, Nginx, CSP, directory ownership, and routine operations.

Continue with:

• Reference Architecture: see how the frontend, backend, Nginx, and deployment fit together.
• AI Chat: try streaming responses, Markdown, and code rendering.
• Chat Widget Protocol: inspect the same-origin iframe loading and message boundary.
• Testing Guide: review Vitest, coverage, Playwright, and browser QA.
• CI/CD Pipeline: review the static build, deployment, and release flow.
• SEO / GEO Maintenance: see how public content stays aligned for search and AI summaries.

PersonalWeb is a maintained personal project. It does not demonstrate high-traffic scale, private customer systems, or a large commercial SaaS. The public repository leaves out secrets, visitor messages, form contents, private logs, and server details.

Another public repository, 📁 Renda Cloud LAB, focuses on cloud-native server architecture and shows a different project scope from PersonalWeb.

Tech Stack

Directory Structure

src/
├── assets/
├── constants/           # Site metadata, asset paths, and app settings
├── features/            # Feature-based modules
│   ├── chat/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── services/
│   └── auth/
│       ├── components/
│       ├── hooks/
│       └── services/
├── hooks/               # Custom hooks for business logic
├── styles/
│   ├── core/               # Core variables
│   │   ├── tokens.css      # Design tokens (colors, spacing, etc.)
│   │   └── _gradients.css  # Gradient system
│   ├── components/         # Component styles
│   ├── utilities/          # Utility classes
│   └── theme.css           # Main entry file
├── scripts/
├── utils/               # Utility helpers
├── models/              # Domain models
├── services/           # API interaction layer
└── components/
    ├── ui/
    ├── layouts/
    ├── forms/
    ├── chat/
    ├── sections/
    └── providers/

Reference Architecture

ASCII Diagram:

Web Application Architecture
============================

Frontend (
   Astro + React
   - Handles UI and interactions
) → CI/CD (
   GitHub Actions auto-build & deploy
) → Server (
   Ubuntu (OS)
   ↓
   Nginx (static file serving)
   ↓
   systemd service (process management)
   ↓
   Gunicorn + Gevent (WSGI server)
   ↓
   Backend: Flask App (business logic & API handling)
)

Mermaid Flow Diagram:

flowchart TD
    A[Web] --> B[Frontend: Astro + React]
    A --> C[Server]
    B -->|Handles UI and interactions| C

    subgraph Server
        direction TB
        D[Ubuntu: OS] --> E[Nginx: Static serving]
        E --> F[systemd: Process management]
        F --> G[Gunicorn + Gevent: WSGI server]
        G --> H[Backend: Flask App: Business logic & APIs]
    end

Frontend

This repository contains the frontend project: 📁 Renda Zhang WEB

Architecture Overview

BaseLayout Component Design Notes

src/layouts/BaseLayout.astro serves as the global page framework for the site, responsible for setting <head> metadata, SEO tags, and root-level slots. The navigation bar and hamburger menu now render on the server and hydrate with client:load, avoiding language flicker while preserving interactivity. The primary reasons for keeping this file as an Astro component are as follows:

• Static Content Does Not Require JavaScript: The layout structure and metadata generation are purely static content. Astro can directly output HTML without introducing the React runtime.
• Maintain Partial Hydration Benefits: Only interactive regions such as the navigation bar and hamburger menu use React, rendering static HTML first and hydrating on the client via client:load. The rest of the layout remains zero-JS, keeping bundle size minimal. Rewriting the entire layout in React would introduce additional script and hydration overhead.
• Leverage Astro Features: Astro-specific syntax such as <slot> and is:inline is extensively used in the layout. Migrating to React would require additional encapsulation or plugin support, increasing maintenance costs.

Consider rewriting BaseLayout.astro only if there are plans to fully migrate the site to React or if there is a need to share complex React state/context at the layout level. For now, maintaining the Astro version is more concise and efficient.

To satisfy Nginx CSP restrictions and allow static pages like 404/500 to reuse theme and language logic, the former inline initialization script has been moved to a blocking external script /js/base-layout-init.js. The file is generated from src/scripts/base-layout-init.ts and passes storage keys via data-theme-key, data-palette-key, and data-lang-key attributes so that theme mode, palette, and language are applied before the page renders.

Local Development & Preview

1. Install dependencies and enable pre-commit:

   npm install
   pip install pre-commit
   pre-commit install
   

2. Start local dev server:

   npm run dev
   

3. Build and preview production version:

   npm run build
   npm run preview
   

4. To connect to a custom backend API, set the PUBLIC_API_BASE_URL in the root directory's .env / .env.local file:

   PUBLIC_API_BASE_URL=https://api.example.com
   

5. Sentry integration also requires:

   SENTRY_DSN=<server dsn>
   PUBLIC_SENTRY_DSN=<browser dsn>
   SENTRY_PROJECT=<your project>
   SENTRY_AUTH_TOKEN=<auth token>
   

   When running local checks or pre-commit without Sentry, prepend:

   SKIP_SENTRY=true pre-commit run --all-files
   SKIP_SENTRY=true npm run astro -- check --incremental
   

   To temporarily skip ESLint checks and speed up commits, use:

   SKIP_ESLINT=true pre-commit run --all-files
   

6. Environment Variables Explanation

   Local configurations can be set in .env or .env.local, and read via the getEnv() function in src/utils/env.ts:

   # Public Information
   PUBLIC_SITE_BASE_URL = "https://www.rendazhang.com"
   PUBLIC_CDN_BASE="https://cdn.jsdelivr.net/gh/rendazhang/rendazhang@1.0.1/"
   PUBLIC_API_BASE_URL="/cloudchat"
   PUBLIC_SENTRY_DSN="https://e184a284f1b7342d197ee0a0151f8353@o4509770577543168.ingest.us.sentry.io/4509770780377088"
   PUBLIC_TAG_NAME="v1.0.1"
   NODE_ENV="production"
   PUBLIC_NODE_ENV="development" # Override to "development" for local debugging
   SKIP_SENTRY="true" # Skip Sentry
   SKIP_ESLINT="true" # Skip ESLint checks
   
   # Sensitive configurations (example values below)
   SENTRY_AUTH_TOKEN="sntrys_xxx"
   SENTRY_DSN="https://private-key@xxx.ingest.us.sentry.io/xxx"
   SENTRY_PROJECT="xxx"
   SENTRY_ORG="xxx"
   

After running npm run build, the dist/_astro directory will contain fingerprinted files with hash suffixes, allowing browsers to cache them long-term.

Access via http://localhost:4321.

Verify builds using npm run preview.

GitHub Actions

Pushing to master triggers GitHub Actions Auto-Deployment:

1. Check out the code with actions/checkout@v5.
2. Set up Node.js 24 with actions/setup-node@v6 and enable npm caching.
3. Run npm ci so dependency installation is based on package-lock.json.
4. Before building, run npm run sync, npm run lint, npm run typecheck, npm run check, and npm run test:coverage.
5. Run npm run build to generate the dist/ static files; production builds remove source maps.
6. Use appleboy/scp-action to upload the contents of dist/ to the server directory, such as /var/www/html.
7. Publish the release branch, recreate the version tag, create the GitHub Release, and try to purge the jsDelivr version cache.
8. After deployment, Nginx serves the static site; no frontend service restart is required.

Local commits do not automatically run the full Astro check. To validate manually, run: npm run check

Configure server IP, SSH user, and private key in Repository Secrets. Details: 📄 GitHub Actions Setup

Usage Guide

Access all modules post-deployment:

• 🌐 Homepage
• 🌐 AI Chat
• 🌐 Certifications
• 🌐 Tech Docs
• 🌐 Login
• 🌐 Register

Website Features

For details on the core functionality system of the website, please refer to the following documentation link: 📄 Core Functionality System. This document provides a detailed description of the website's core functional modules, including feature design and technical implementation. It serves as an essential reference for development and maintenance.

• Theme Switching (Light / Dark)
• Language Switching (Chinese / English)
• Online Chat with AI
• Floating AI Chat Window
• Back to Top Button
• Technical Documentation Rendering Page (docs/)
• Login and Registration Form
• Logged-in User Account Information Page (Accessible from the Hamburger Menu after Login)
• Contact Form
• Content Platform Links
• Certificate Display
• Resume Download

Page Functionality

The core responsibilities of each page are as follows (all generated by .astro files):

• index.astro: Homepage, also the introduction page for Zhang Renda, showcasing Zhang Renda's information, education, skills, blog, and work experience.
• certifications.astro: Certifications list page.
• deepseek_chat.astro: AI chat interface.
• docs.astro: Technical documentation page.
• profile.astro: User account information page.
• login.astro: Login page.
• register.astro: Registration page.
• 404.astro, 500.astro: Error pages.

Page Navigation

1. Return to Homepage All pages have "Home" button in navigation

2. Navigation Menu Redirection

   • The navigation bar and hamburger menu output static markup on the server side and are hydrated on the client side using client:load, ensuring interactivity while avoiding hydration errors.
   • By clicking the "Hamburger Menu" button in the navigation bar, users can choose to navigate to the following pages:
     • Homepage
     • AI Chat Page
     • Certifications Page
     • Technical Documentation Page
     • User Account Information Page (visible after login)

3. Login Page Access Profile icon in nav redirects to login

flowchart TD
    A[Home] -->|Hamburger| B[AI Chat]
    A -->|Hamburger| C[Certifications]
    A -->|Hamburger| D[Tech Docs]
    A -->|Hamburger| F[Account Profile]
    A -->|Profile Icon| E[Login]
    B -->|Home Button| A
    C -->|Home Button| A
    D -->|Home Button| A
    E -->|Home Button| A
    F -->|Home Button| A

    style A fill:#9f9,stroke:#333
    style B fill:#f9f,stroke:#333
    style C fill:#ff9,stroke:#333
    style D fill:#99f,stroke:#333
    style E fill:#f99,stroke:#333
    style F fill:#9ff,stroke:#333

Page Content

• index.astro: A multi-section homepage containing modules such as "Hero", "About Me", "Education", "Blog", "Skills & Abilities", "Experience", and "Contact Me", with a default floating ChatWidget badge.
• certifications.astro: Grid-based certification cards with Credly verification
• deepseek_chat.astro: A conversational interface consisting of a chat history area and an input box, supporting streaming output and real-time rendering of AI-generated Markdown content. It provides a one-click copy feature for the original content and automatically retains the chat history upon page refresh, and loads both github-code-highlight.css and github-markdown-light.css for consistent GitHub-style code highlighting. The chat UI has been refactored into reusable components such as ChatMessageList and ChatInput for better maintainability.
• docs.astro: Technical documentation page that loads both github-code-highlight.css and github-markdown-light.css together with highlight.js for GitHub-style Markdown layout and code highlighting.
• profile.astro: Account information page, displaying the information of the currently logged-in user.
• login.astro: Login form page.
• register.astro: Register form page.
• 404.astro/500.astro: Custom error pages designed to handle Page Not Found (404) and Internal Server Error (500) scenarios. These pages provide clear error messages, user-friendly guidance, and a link to return to the homepage, enhancing the overall user experience.

Page Optimization

Adaptive Layout: Optimizes the display effect of the page on different devices, reduces unnecessary resource loading and layout calculations, and thereby improves performance. Ensures that the page displays well on various screen sizes (e.g., desktop, tablet, mobile), enhancing user experience.

Lazy Loading: All images have lazy loading enabled with a loading animation. For high-definition images, LQIP (Low-Quality Image Placeholder) lazy loading optimization is applied (e.g., the Hero section on the homepage).

Color Scheme

The core colors of the project are designed using OKLCH design tokens and provide sRGB fallback through color-mix to ensure perceptual consistency across light and dark modes.

For detailed information, refer to the documentation: 📄 Color Scheme.

Backend

For detailed steps and configurations on backend deployment, please refer to the following project: 📁 Python Cloud Chat. This project provides a complete backend implementation and deployment guide, helping you quickly set up and run backend services.

Nginx Server

The frontend project is automatically built via GitHub Actions and pushed to the /var/www/html directory on the server, where Nginx serves the static resources.

For detailed Nginx configurations and operational instructions, please check the following repository: 📁 Nginx Conf. This repository includes commonly used Nginx configuration files and examples, making it easy for you to get started.

To fully leverage the hashed assets under /_astro, add a long-term cache rule in Nginx:

location /_astro/ {
    access_log off;
    add_header Cache-Control "public, max-age=31536000, immutable";
}

If you need a more robust server solution, you can refer to my cloud-native project: 📁 Renda Cloud LAB. This project provides a complete cloud-native architecture design, suitable for large-scale and high-availability scenarios.

Documentation

Git Branching & Release Workflow

The project follows a master/develop dual-branch model with conventions for feature, hotfix, and experiment branches. Details: 📄 Git Workflow.

CI/CD Workflow

deploy.yml defines the deployment process triggered when code is pushed or merged into master, including tag management and environment variable mappings. See: 📄 CI / CD Pipeline.

Operations Maintenance Guide

Frontend validation, deploy-run inspection, deploy-log noise classification, dependency audits, backend/Nginx docs-only sync rules, production read-only checks, and local roadmap maintenance commands are documented in: 📄 Operations Maintenance Guide.

Dependency Security Risk Register

Current dependency audit / Dependabot residual risk, the reason npm audit fix --force is disallowed, Astro 7 upgrade boundaries, and security patch escalation thresholds are documented in: 📄 Dependency Security Risk Register.

Astro 7 Upgrade Precheck

The Astro 7 Go/No-Go decision, target package set, Vite 8/Rolldown risks, Sentry source-map checks, CSP gate, Chat Widget smoke scope, and rollback plan are documented in: 📄 Astro 7 Upgrade Precheck.

Astro 6 Migration Precheck

The current baseline, target package set, Node/Vite/Sentry compatibility risks, validation checklist, and rollback plan for the Astro 6 upgrade are documented in: 📄 Astro 6 Migration Precheck.

Frontend Architecture Conventions

Current conventions for Astro pages, BaseLayout, React Islands, hydration, service boundaries, utilities, style tokens, CSP, and iframe constraints are documented in: 📄 Frontend Architecture Conventions.

Frontend Directory Ownership Map

Directory ownership for src/components, src/services, src/utils, src/styles, src/content, src/stores, and src/controllers is documented in: 📄 Frontend Directory Ownership Map.

Chat Widget Protocol

The same-origin iframe postMessage ready protocol between the floating Chat Widget and /deepseek_chat/, including origin/source checks, loading lifecycle, and refactor constraints, is documented in: 📄 Chat Widget Protocol.

Frontend Experience Platform RFC

Phase 8 planning for browser smoke coverage, hydration safety, theme mode vs palette/accent separation, palette slice order, and interaction standards is documented in: 📄 Frontend Experience Platform RFC.

Interaction Component Standards

Modal, popover/menu, toast/status, loading, disabled/empty/error state, keyboard behavior, focus management, and browser smoke gates are documented in: 📄 Interaction Component Standards.

Human Voice And Personal Expression

Phase 15 rules for bilingual voice, first-person writing, technical terminology, CTAs, evidence boundaries, visual expression, and owner input are documented in: 📄 Human Voice And Personal Expression.

Content And Credibility Positioning

Phase 10 planning for personal-brand content, credibility proof, PersonalWeb project evidence, certifications, work/education narrative, and SEO/GEO alignment is documented in: 📄 Content And Credibility Positioning.

Site Intelligence And Visitor Journey

Phase 11 visitor journey, privacy-safe anonymous events, first-party telemetry boundaries, and Chat Guide public-content scope are documented in: 📄 Site Intelligence And Visitor Journey.

Portfolio Proof And Visitor Conversion

Phase 14 planning for portfolio proof, visitor proof paths, the PersonalWeb case-study surface, homepage proof flow, Chat Guide entry points, and browser/mobile conversion QA is documented in: 📄 Portfolio Proof And Visitor Conversion.

Chat Guide Quality Architecture

Phase 12 documents the Chat Guide public knowledge boundary, answer-quality architecture, backend-owned public knowledge package, and delivery sequence: 📄 Chat Guide Quality Architecture.

SEO / GEO Maintenance

Canonical host, sitemap, llms.txt, /docs/ SSR content, and soft-404 validation rules are documented in: 📄 SEO / GEO Maintenance.

BUG Tracking

For BUGs encountered during frontend development and their solutions, please refer to the following document: 📄 Frontend BUG Tracking Database. This document provides detailed records of BUG descriptions, reproduction steps, solutions, and developer notes, helping you quickly identify and resolve issues.

Development Requirements

For project feature requirements, priorities, and development plans, please refer to the following document: 📄 Project Requirements List. This document lists all requirements for the current version, along with detailed descriptions and development statuses, making it easy for you to track project progress and plan development tasks.

User Authentication and Password Reset Specification

For details on page routing, API contracts, password policies, and security considerations related to user authentication and password reset, please refer to: 📄 Authentication Specification.

Native to Astro + React Migration

The front-end currently adopts an architecture based on Astro + React, following a layered design philosophy. It utilizes GitHub Actions for automated builds and deploys the build artifacts to a specified directory on the server's Nginx.

For detailed steps on upgrading from native frontend, please refer to the following documentation: 📄 Upgrade Plan. This document provides a comprehensive plan and implementation steps for gradually migrating from the old native frontend to a new frontend architecture based on Astro and React.

For detailed steps on setting up the development environment, please refer to the following documentation: 📄 Environment Preparation. This document provides a comprehensive guide on configuring the development environment and initializing an Astro project, ensuring you can smoothly proceed with subsequent development tasks.

Responsive Image System Maintenance

The website uses an automated pipeline to generate responsive images with built-in LQIP placeholders. For maintenance and extension instructions, see 📄 Responsive Image System Maintenance

Error Tracking

Sentry collects runtime and network errors. See 📄 Error Tracking Integration for configuration.

Utilities Reference

src/utils/env.ts, src/utils/langUtils.ts, src/utils/storage.ts, and src/utils/logger.ts provide unified access to environment variables, language parsing, multi-backend storage solutions, and an extensible logging interface.

Docs: 📄 Utilities Reference.

Comprehensive Pre-Commit Guide

For a detailed explanation of the pre-commit hooks, refer to the Comprehensive Pre-Commit Guide.

Style System Description

Introduce the project's CSS architecture, the OKLCH-based design token system, and the build process. Demonstrate how postcss-import inlines the core and utility styles referenced by theme.css during the compilation phase to reduce runtime requests. For details, see: 📄 Style Guide.

🤝 Contribution Guide

• Fork and clone this repository.
• Enter the virtual environment:

  # If the virtual environment is not yet installed, run: python -m venv venv
  source venv/bin/activate
  

• Install dependencies and enable pre-commit:

  pip install pre-commit
  pre-commit install
  

• Before each commit, the hooks will automatically run and perform the following tasks:
  • Automatically fix basic formatting issues (trailing whitespace, end-of-file newlines, etc.)
  • Update the documentation table of contents and the last updated timestamp
  • Synchronize the README file to the assets directory
  • Validate static resource naming conventions
  • Automatically generate module index.ts files
  • Perform code formatting and static checks

✅ All commits must pass the pre-commit checks; CI will block PRs that do not meet the standards.

🔒 Open Source License

Released under MIT License - free for use and modification. Retain original license notices when redistributing.

📬 Contact

• Contact: Renda Zhang
• 📧 Email: 952402967@qq.com

⏰ Maintainer: @RendaZhang — If this project helps you, please give it a ⭐️!