website/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OmniVerse (灵境万象) is an enterprise website for a health technology company specializing in AI-powered health solutions including smart wearables, care robots, and health data platforms. This is a comprehensive React application with advanced content management, internationalization, and a microservices architecture.

Commands

Development

npm run dev        # Start development server on port 5174 (http://localhost:5174)
npm run build      # Build for production
npm run build:check # TypeScript check + build
npm run preview    # Preview production build locally
npm run lint       # Run ESLint
npm run deploy     # Build and deploy to GitHub Pages

News Crawler Service

cd news-crawler-service
npm start          # Start news crawler API server on port 3001
npm run dev        # Development mode with nodemon
npm run crawler    # Run crawler manually
npm test           # Run tests

Docker Deployment

docker-compose up -d    # Start containerized services

Architecture

Technology Stack

• Frontend: React 18 + TypeScript + Vite
• Routing: React Router v7 with file-based routing
• Styling: TailwindCSS with custom design system
• Animation: Framer Motion
• Internationalization: i18next + react-i18next (zh/en/de)
• State Management: React Context (Theme, Auth, Search, Favorites)
• Content: Markdown-based with dynamic loading
• Backend Services: Node.js microservices (news crawler)

Application Architecture

Frontend Structure

src/
├── components/
│   ├── sections/           # Page layout sections
│   ├── charts/            # Data visualization components
│   └── (other components) # Modals, navigation, etc.
├── pages/                 # Route components
│   └── company/          # Company information pages
├── contexts/              # React Context providers
├── data/                  # Static data and mock data
├── content/               # Markdown content files
│   ├── articles/         # Technical articles
│   ├── blog/             # Company blog posts
│   └── docs/             # Documentation
├── locales/              # i18n translation files
├── services/             # API service layers
├── types/                # TypeScript definitions
└── utils/                # Utility functions

Company Pages Structure

The application includes a comprehensive company section with 8 dedicated pages:

• About Page (/about): Company overview and mission
• Team Page (/team): Team member profiles
• History Page (/history): Company timeline and milestones
• Careers Page (/careers): Job opportunities and company culture
• News Page (/news): Company news and announcements
• Investors Page (/investors): Investor relations and information
• CSR Page (/csr): Corporate social responsibility initiatives
• Contact Page (/contact): Contact information and forms

Key Architectural Patterns

• Context-based State Management: Theme, Auth, Search, and Favorites contexts
• File-based Content Management: Markdown files with dynamic imports
• Microservices: Separate news crawler service with its own database
• Component-based Charts: Custom SVG charts without external dependencies
• Responsive Design System: TailwindCSS with custom color tokens and animations

Content Management System

Markdown Content Structure

• Articles (src/content/articles/): Technical articles with chart integration
• Blog Posts (src/content/blog/): Company blog content
• Documentation (src/content/docs/): API and user documentation
• Dynamic Loading: Content loaded via contentLoader.ts and markdownLoader.ts

Chart Integration System

Charts are embedded in markdown using placeholder syntax:

{{CHART:chart-type}}

Available chart types: health-monitoring, market-trend, case-study-comparison, system-architecture, simple-bar-chart

Content Loader Architecture

• Dynamic Import Loading: Uses Vite's import.meta.glob for efficient markdown loading
• Front Matter Parsing: Custom YAML parser for article metadata
• Caching System: In-memory caching for loaded content
• Search Functionality: Full-text search across title, content, and tags
• Related Content: Algorithm-based content recommendations

Service Architecture

News Crawler Service (news-crawler-service/)

• Technology: Node.js + Express + SQLite + RSS parsing
• Features: RSS aggregation, content categorization, scheduled crawling
• API: RESTful endpoints for news data
• Database: SQLite with news articles and metadata
• Authentication: API key-based authentication for all endpoints
• Caching: In-memory caching with configurable TTL
• Logging: Winston-based logging system

News Integration Architecture

• Service Separation: News crawler runs as independent microservice on port 3001
• API Endpoints: /api/news, /api/news/hot, /api/stats, /api/categories
• News Sources: Monitors major Chinese tech/healthcare RSS feeds (动脉网, 36氪, 亿欧网, 雷锋网, 机器之心)
• Categories: healthcare-policy, medical-robotics, smart-elderly-care, industry-trends, tech-innovation, investment
• Frontend Service: src/services/newsService.ts handles API communication
• Fallback System: Mock data fallback when news service is unavailable

Theming System

Theme Configuration

• Modes: light, dark, auto (system preference)
• Implementation: CSS classes + Tailwind dark mode
• Storage: localStorage persistence
• Context: ThemeContext with useTheme hook

Custom Color System

/* Tech-inspired colors */
--tech-blue: #0ff (cyan)
--tech-green: #0f0 (green)
--dark-bg: #0a0a0a
/* Semantic color tokens for light/dark modes */

Internationalization

Language Support

• Chinese (zh): Primary language, fallback
• English (en): Secondary language
• German (de): Additional language
• Implementation: i18next with JSON translation files
• Default: Chinese (zh) with fallback

Development Guidelines

Component Patterns

• All components are TypeScript functional components
• Use Framer Motion for animations
• Follow the existing glass morphism design patterns
• Implement responsive design with Tailwind breakpoints
• Use context hooks for global state (theme, auth, etc.)

Content Guidelines

• Markdown files support chart placeholders: {{CHART:type}}
• Charts are rendered via ChartRenderer component
• Content is loaded dynamically via utility functions
• Support for syntax highlighting in code blocks

API Integration

• News API: /api/news endpoints from crawler service
• Mock data fallbacks when services unavailable
• Error handling with user-friendly messages

Deployment

Production Build

• Vite build system optimized for GitHub Pages
• Base URL configured for /website/ path
• Static asset optimization and tree shaking

Container Deployment

• Docker Compose setup for web service
• Health checks and restart policies configured
• Port mapping: 5173 (web), 3001 (news API)

Important Development Notes

Vite Configuration

• Development server runs on port 5174 (not 5173)
• GitHub Pages deployment with /website/ base path
• Host configured as 0.0.0.0 for container compatibility

Custom Build Scripts

• build:check: Runs TypeScript checking before build
• deploy: Automated GitHub Pages deployment via gh-pages

Context Dependencies

When adding new features that use global state:

1. Check existing contexts: ThemeContext, AuthContext, SearchContext, FavoritesContext
2. Use the established patterns for context providers and hooks
3. Ensure proper TypeScript typing for context values

Development Workflow

Testing Strategy

• Frontend Testing: No test framework currently configured (consider adding Vitest/Jest)
• News Service Testing: Jest framework for news crawler service
• Build Verification: build:check script ensures TypeScript compilation before build
• Linting: ESLint configuration for code quality

Build Process

• Development: Vite dev server with HMR on port 5174
• Production: Optimized build with tree shaking and code splitting
• Deployment: GitHub Pages deployment via gh-pages package
• Containerization: Docker support with health checks

Environment Configuration

• Development: Local development with hot reload
• Production: Optimized for GitHub Pages deployment
• Base Path: /website/ configured for repository deployment
• Host Binding: 0.0.0.0 for container compatibility