# type-for-learning

**Repository Path**: luyanfei/type-for-learning

## Basic Information

- **Project Name**: type-for-learning
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-23
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Type-for-Learning

A Chinese typing and vocabulary learning platform with centralized OAuth 2.0 authentication.

## Features

- **Chinese Typing Practice**: Continuous, sentence, vocabulary, and fill-blank modes
- **Vocabulary Management**: Create word lists with pronunciation and definitions
- **Article System**: Create, tag, and practice with custom articles
- **Progress Tracking**: Practice statistics and performance metrics
- **OAuth 2.0 Authentication**: Integrated with auth.fei78.me SSO

## Authentication

This application uses OAuth 2.0 for authentication, integrated with the standalone auth-service.

### Login Flow

1. User clicks "登录" (Login)
2. Redirects to `auth.fei78.me/oauth/authorize`
3. If user has active session: Auto-authorize (SSO)
4. If not logged in: Show login form, then authorize
5. Redirect back with authorization code
6. Exchange code for access token
7. Create local user session

### Environment Setup

Create `.env.local` with the following:

```bash
# Database
MONGODB_URI=mongodb://localhost:27017/type-for-learning

# NextAuth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key

# OAuth 2.0 (auth-service integration)
NEXT_PUBLIC_AUTH_SERVICE_URL=http://localhost:3001
NEXT_PUBLIC_OAUTH_AUTHORIZATION_ENDPOINT=http://localhost:3001/oauth/authorize
NEXT_PUBLIC_OAUTH_TOKEN_ENDPOINT=http://localhost:3001/api/auth/token
NEXT_PUBLIC_OAUTH_USERINFO_ENDPOINT=http://localhost:3001/api/auth/userinfo
NEXT_PUBLIC_OAUTH_REDIRECT_URI=http://localhost:3000/api/auth/callback
NEXT_PUBLIC_OAUTH_CLIENT_ID=type-for-learning-client
NEXT_PUBLIC_OAUTH_CLIENT_SECRET=your-client-secret
```

## Getting Started

### Prerequisites

- Node.js 18+
- MongoDB 7+
- auth-service running on port 3001

### Install Dependencies

```bash
npm install
```

### Run Development Server

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000)

## Project Structure

```
type-for-learning/
├── app/
│   ├── (dashboard)/        # Authenticated pages
│   │   ├── portal/         # Homepage with article grid
│   │   ├── practice/       # Current practice list
│   │   ├── analytics/      # Practice statistics
│   │   ├── articles/       # Article management
│   │   ├── settings/       # User settings
│   │   └── typing-game/    # Typing practice
│   ├── api/
│   │   ├── auth/           # OAuth callback endpoint
│   │   ├── articles/       # Article CRUD
│   │   ├── vocabulary/     # Vocabulary management
│   │   └── users/          # User profile
│   └── page.tsx            # Homepage
├── components/
│   ├── ui/                 # Shared UI components
│   ├── home/               # Homepage components
│   ├── practice/           # Practice-related components
│   └── vocabulary/         # Vocabulary components
├── lib/
│   ├── auth/               # OAuth configuration
│   ├── services/           # Business logic layer
│   ├── mongodb/            # Database models
│   └── utils/              # Utility functions
└── types/                  # TypeScript definitions
```

## Available Scripts

```bash
npm run dev          # Start development server
npm run build        # Build for production
npm start            # Start production server
npm run lint         # Run ESLint
npm test             # Run tests
npm run test:e2e     # Run E2E tests
```

## Tech Stack

- **Framework**: Next.js 16+ (App Router)
- **Language**: TypeScript 5.x (strict mode)
- **Database**: MongoDB with Mongoose 9.x
- **Authentication**: OAuth 2.0 (auth.fei78.me)
- **UI**: Ant Design 6.1.1, Tailwind CSS v4
- **State**: React hooks, localStorage for practice state

## Kubernetes Deployment

See [Kubernetes Deployment Guide](#kubernetes-deployment) below for production deployment.

### Architecture

```
Internet
    |
    v
Gateway API
    |
    +---> Next.js App (HPA: 2-5 pods)
    |        - OAuth 2.0 client
    |        - Local user database
    |
    +---> auth-service (separate deployment)
    |        - OAuth 2.0 authorization server
    |        - User authentication
    |
    +---> MongoDB StatefulSet (3 nodes, replica set)
```

## Kubernetes Deployment

This application can be deployed to a self-hosted Kubernetes cluster.

### Prerequisites

- Kubernetes Cluster (v1.24+) with kubectl configured
- Gateway API CRDs installed (v1.0.0+)
- Container Registry access
- Domain name with DNS configured
- MongoDB 7+ replica set

### Quick Start

#### 1. Build and Push Container Image

```bash
docker build -t your-registry/type-for-learning:latest .
docker push your-registry/type-for-learning:latest
```

#### 2. Create Kubernetes Secrets

```bash
# Create MongoDB credentials
kubectl create secret generic mongodb-credentials \
  --from-literal=username=mongoadmin \
  --from-literal=password=your-strong-password

# Create application secret
kubectl create secret generic type-for-learning-secret \
  --from-literal=mongodb-uri="mongodb://mongoadmin:password@mongodb-0.mongodb-headless:27017,type-for-learning-1.mongodb-headless:27017,type-for-learning-2.mongodb-headless:27017/type-for-learning?replicaSet=rs0&authSource=admin" \
  --from-literal=nextauth-secret="your-nextauth-secret" \
  --from-literal=oauth-client-id="your-client-id" \
  --from-literal=oauth-client-secret="your-client-secret"
```

#### 3. Deploy

```bash
# Deploy MongoDB
kubectl apply -f k8s/mongodb/

# Deploy Next.js app
kubectl apply -f k8s/nextjs-app/

# Deploy Gateway API resources
kubectl apply -f k8s/gateway/
```

### Monitoring

```bash
# View logs
kubectl logs -l app=type-for-learning -f

# Check pod status
kubectl get pods

# Get Gateway IP
kubectl get gateway type-for-learning-gateway -o jsonpath='{.status.addresses[0].value}'
```

## Documentation

- [CLAUDE.md](CLAUDE.md) - Development guidelines
- [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md) - Migration notes

## License

MIT