Project Overview

Source Files

This page is generated from the following source files:

• README.md
• package.json
• src/app/page.tsx
• src/app/layout.tsx
• src/app/not-found.tsx
• src/types/index.ts
• .spec-workflow/user-templates/README.md
• next-env.d.ts
• next.config.js
• postcss.config.js

This project is a gamified writing learning platform designed for sixth-grade students, built with Next.js 14 and following a backend-less architecture. The platform helps students master writing skills through seven progressive tool levels, real-time essay editing, and AI-powered grading with a Bring Your Own Key (BYOK) approach. All user data persists locally via localStorage and Zustand state management, eliminating the need for server-side infrastructure while maintaining full functionality across modern browsers.

Project Introduction and Core Features

The platform, named "六年级作文成长手册" (Sixth Grade Writing Growth Handbook), implements a comprehensive gamification system to engage students in writing practice. The core value proposition centers on making writing practice enjoyable through structured progression, immediate feedback, and achievement systems.

Gamification Mechanics

The platform features seven distinct writing tool levels that students unlock progressively. Each tool includes comprehension tests, practice exercises, and mastery tracking. The daily challenge system generates randomized writing tasks based on unlocked tools, with streak tracking to encourage consistent practice habits.

Key gamification elements include:

• Progressive Tool Unlocking: Tools require prerequisites such as completing prior tools, achieving minimum mastery levels, or maintaining writing streaks (src/types/index.ts:27-40)
• Daily Challenges: Randomized tasks selected from available tools with streak counters (src/app/page.tsx:31-44)
• Achievement System: Unlocks based on milestones like first challenge completion or 7-day streaks (src/app/page.tsx:64-69)
• Mastery Tracking: Each tool tracks practice count, test passed status, and mastery level (0-100) (src/types/index.ts:60-72)

AI-Powered Feedback

The platform supports AI essay grading through a BYOK (Bring Your Own Key) model. Users configure their own API credentials in settings, with support for OpenAI-compatible endpoints including DeepSeek and Moonshot. This approach eliminates backend API key management while providing personalized feedback capabilities (README.md:9-11).

Target Audience and Educational Goals

The application targets Chinese elementary school students (specifically sixth grade) preparing for writing assessments. The metadata configuration reflects this focus with keywords including "作文" (composition), "六年级" (sixth grade), "写作" (writing), and "游戏化学习" (gamified learning) (src/app/layout.tsx:8-12).

Technical Architecture and Stack

The project employs a modern frontend-only architecture leveraging Next.js 14's App Router pattern. The technology selection prioritizes developer experience, performance, and deployment simplicity.

Technology Stack Overview

(package.json:12-42)

Frontend Architecture

The application follows Next.js App Router conventions with a clear separation of concerns:

src/
├── app/           # Next.js App Router pages
├── components/    # Reusable UI components
├── data/          # Static configuration and tool definitions
├── lib/           # Utility functions and Zustand stores
├── types/         # TypeScript type definitions
└── styles/        # Global styles and Tailwind configuration

(README.md:75-85)

Build Configuration

The Next.js configuration optimizes for Vercel deployment with React strict mode enabled and SWC minification. Image optimization is disabled (unoptimized: true) to simplify deployment. A custom webpack rule handles .mjs files in node_modules to prevent JavaScript syntax errors during Vercel builds (next.config.js:1-20).

javascript
1// Key configuration from next.config.js
2const nextConfig = {
3  reactStrictMode: true,
4  swcMinify: true,
5  images: {
6    unoptimized: true
7  },
8  webpack: (config) => {
9    config.module.rules.push({
10      test: /\.mjs$/,
11      include: /node_modules/,
12      type: 'javascript/auto',
13    });
14    return config;
15  }
16}

System Design and Data Model

The data model centers on student progress tracking with comprehensive type definitions for writing tools, essays, challenges, and achievements. The TypeScript types enforce data integrity across the application while supporting complex nested structures.

Core Type Definitions

The type system defines several interconnected interfaces:

WritingTool Interface: Represents each writing technique with guidance content, exercises, and unlock conditions. Tools can contain subTools for hierarchical organization and comprehension tests for knowledge verification (src/types/index.ts:10-57).

LevelProgress Interface: Tracks individual tool mastery including completion status, test passed flag, practice count, and mastery level percentage. This enables fine-grained progress tracking beyond simple completion states (src/types/index.ts:60-72).

Essay and EssayVersion Interfaces: Support versioned essay editing with tree-structured history (via parentId), multiple content types (text, image, audio), and action items for improvement tracking. The transcribedText field enables OCR/audio transcription workflows (src/types/index.ts:129-169).

Data Persistence Strategy

The backend-less design stores all data in browser localStorage through Zustand's persistence middleware. This approach provides:

• Zero infrastructure costs
• Complete data privacy (data never leaves the user's device)
• Offline capability for core features
• Simple deployment without database management

(README.md:87-92)

AI Configuration Model

The AIConfig interface supports flexible API configuration:

• apiKey: User-provided API key (stored locally, never transmitted to app servers)
• baseURL: Custom endpoint for OpenAI-compatible services
• model: Selected model identifier
• models: Available model list for UI selection

(src/types/index.ts:114-119)

System Architecture Diagram

The following diagram illustrates the core modules and their relationships within the platform:

正在加载图表渲染器...

Architecture Explanation:

1. UI Layer: The Next.js App Router provides the page structure with RootLayout wrapping all pages. HomePage contains the main application logic including challenge generation and achievement tracking (src/app/layout.tsx:14-30).

2. State Management: Zustand manages application state with automatic localStorage persistence. This enables offline functionality and data retention across sessions without backend infrastructure.

3. Data Layer: TypeScript types enforce data contracts while static data files define writing tool content. The separation allows content updates without code changes.

4. External Services: AI APIs are called directly from the client using user-provided credentials, maintaining the backend-less architecture.

Daily Challenge Data Flow

The following sequence diagram shows the data flow when generating and completing a daily challenge:

正在加载图表渲染器...

Data Flow Explanation:

1. Initialization: On application load, the HomePage component retrieves persisted progress from the Zustand store, which automatically syncs with localStorage (src/app/page.tsx:21-27).

2. Challenge Generation: The generateDailyChallenge function filters available tools based on testPassed status, randomly selects a tool and exercise, then constructs a challenge object with streak continuation (src/app/page.tsx:31-44).

3. Completion Handling: When a user completes a challenge, handleChallengeComplete updates the challenge state, increments the streak counter, and checks for achievement unlocks based on streak milestones (src/app/page.tsx:47-69).

4. Persistence: All state changes automatically propagate to localStorage through Zustand's persistence middleware, ensuring data survives browser sessions.

Project Structure and Organization

The codebase follows a clear organizational pattern separating concerns across distinct directories:

writing-companion/
├── src/
│   ├── app/
│   │   ├── layout.tsx      # Root layout with providers
│   │   ├── page.tsx        # Main application page
│   │   ├── not-found.tsx   # 404 error page
│   │   └── globals.css     # Global styles
│   ├── components/
│   │   └── ui/             # Radix UI based components
│   ├── data/
│   │   └── tools.ts        # Writing tool definitions
│   ├── lib/                # Utilities and stores
│   ├── types/
│   │   └── index.ts        # All TypeScript interfaces
│   └── styles/             # Additional styling
├── package.json            # Dependencies and scripts
├── next.config.js          # Next.js configuration
├── postcss.config.js       # PostCSS/Tailwind config
└── next-env.d.ts           # Next.js TypeScript references

Component Architecture

The UI layer uses Radix UI primitives wrapped in custom components with Tailwind CSS styling. The not-found.tsx demonstrates the pattern: importing Card and Button components from @/components/ui/ and applying Morandi color palette classes (src/app/not-found.tsx:5-32).

Styling Approach

The application uses a custom Morandi color palette (morandi-gray, morandi-beige, morandi-blue) applied through Tailwind utility classes. PostCSS processes Tailwind directives with autoprefixer for browser compatibility (postcss.config.js:1-6).

Deployment and Compatibility

The project is optimized for Vercel deployment with zero-configuration setup. The deployment workflow leverages Next.js's built-in optimizations and Vercel's automatic detection.

Deployment Process

1. Push code to GitHub repository
2. Import project in Vercel dashboard
3. Vercel auto-detects Next.js and configures build settings
4. Deploy triggers automatically on push

(README.md:65-74)

Browser Compatibility

The application supports modern evergreen browsers with specific minimum versions:

(README.md:104-109)

These requirements ensure support for ES6 modules, CSS Grid, and modern JavaScript APIs required by React 18 and Next.js 14.

Development Workflow

Standard npm scripts provide development, build, and lint commands:

bash
1# Development with hot reload
2npm run dev
3
4# Production build
5npm run build
6
7# Start production server
8npm start
9
10# Lint code
11npm run lint

(package.json:6-11)

Report Reading Roadmap

The following diagram illustrates the recommended reading order for this technical analysis report:

正在加载图表渲染器...

Reading Recommendations:

1. Start Here: This overview provides foundational understanding of the project's purpose, technology choices, and high-level architecture.

2. Core Understanding: Features Analysis details the gamification mechanics and user-facing functionality. Architecture Deep Dive explores module boundaries and dependencies.

3. Implementation Details: Data Flow & State examines Zustand store patterns and localStorage persistence. API Integration covers the BYOK AI grading system. Data Model Details provides comprehensive type documentation.

Quantitative Project Metrics

The project demonstrates a well-structured educational technology application balancing feature richness with architectural simplicity through its backend-less design, comprehensive type system, and modern frontend tooling.