Build and Run an AI-Powered WeChat Learning Mini App

What You Will Build

AI Knowledge Base Smart Learning Mini App is an intelligent study application for the WeChat ecosystem. A learner can enter a topic or upload private documents, then use AI-assisted workflows to generate questions, receive immediate explanations, and review a report covering mastery, weak areas, and suggested next steps.

The project combines large language models, web search, and retrieval-augmented generation. Tavily supplies current web context, while Chroma supports retrieval from uploaded PDF, Word, Markdown, and TXT files.

Key Features

• Topic-based quiz generation: Generate learning questions from a topic supplied by the user.
• Web search enhancement: Use Tavily to add up-to-date context.
• Private knowledge-base learning: Upload PDF, Word, Markdown, or TXT documents and retrieve relevant content with RAG.
• Immediate feedback: Check answers and return explanations after each response.
• Learning reports: Analyze mastery, identify weak areas, and provide study suggestions.
• Question illustrations: Generate supporting images and store them in Tencent Cloud COS.
• WeChat user support: Provide login, learning history, and report review.
• Container deployment: Deploy the backend through Docker to WeChat Cloud Run or another compatible platform.

Understand the Architecture

The mini app frontend uses Taro 4, React 18, TypeScript, and Sass. The backend runs on Python 3.11 with FastAPI, Pydantic v2, and Uvicorn. LangChain and LangGraph coordinate AI operations, with DeepSeek and Alibaba Bailian included in the model and retrieval stack.

MySQL provides application data storage, Tencent Cloud COS stores generated illustrations, and Chroma acts as the vector store. Authentication uses WeChat jscode2session and JWT. Backend tests use pytest and pytest-asyncio.

Repository Layout

.
├── backend/        # FastAPI backend
├── frontend/       # Taro-based WeChat mini app frontend
├── docs/           # project docs kept locally
├── openspec/       # specification files kept locally
└── prototypes/     # prototype files kept locally

Prerequisites

Before starting, install Python 3.11, Node.js with npm, and WeChat DevTools. You will also need the service credentials and configuration values expected by backend/.env.example. Docker is required only when you are ready to build or deploy the backend container.

Keep real API keys, database credentials, JWT secrets, and cloud storage credentials out of version control. Production secrets should be injected through the deployment platform.

Step 1: Configure the Backend

Open a terminal, enter the backend directory, and create an isolated Python environment. The README provides the following PowerShell-oriented setup:

cd backend
python -m venv venv
venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env

Open the new .env file and supply the configuration required by your selected models, Tavily integration, database, authentication, vector retrieval, and Tencent Cloud storage. Use backend/.env.example as the authoritative list of expected variables.

Start the FastAPI Service

python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The --reload option is useful during local development because Uvicorn restarts when backend code changes. Binding to 0.0.0.0 makes the development service available through the machine's network interfaces.

Verify the Backend

After startup, open the interactive API documentation at http://localhost:8000/docs. You can also check service health at http://localhost:8000/api/v1/health.

Verify the health endpoint before troubleshooting the frontend. If it is unavailable, confirm that the virtual environment is active, dependencies installed successfully, the .env file exists, and port 8000 is not already occupied.

Step 2: Build the WeChat Mini App Frontend

Keep the backend running, open a second terminal, and install the frontend dependencies:

cd frontend
npm install
npm run dev:weapp

The development command compiles the Taro application for WeChat. When compilation is complete, launch WeChat DevTools and open the generated frontend/dist directory.

Keep the compiler terminal open while developing so frontend changes can be rebuilt. The FastAPI server should remain active in its own terminal so the mini app can access backend functionality.

Step 3: Try the Learning Workflow

Once the frontend and backend are running, the project supports two primary learning paths.

Generate a Quiz from a Topic

1. Log in through the WeChat user flow.
2. Enter a subject you want to study.
3. Generate AI-assisted questions based on that topic.
4. Submit answers and review the returned answers and explanations.
5. Complete the study session and inspect the AI report for mastery analysis, weak points, and recommendations.

Learn from Private Documents

1. Choose a supported PDF, Word, Markdown, or TXT document.
2. Upload it to the application's knowledge-base workflow.
3. Allow the system to retrieve relevant document context through its RAG pipeline.
4. Answer the generated questions and review the explanations.
5. Use the resulting report to decide which parts of the material need further study.

Topic-based learning can use Tavily to add recent web context. Document-based learning instead grounds retrieval in uploaded private materials. The exact available behavior depends on the services and credentials configured in the backend environment.

Step 4: Run the Test Suite

Run the backend tests from the backend directory:

cd backend
pytest

The project uses pytest and pytest-asyncio. Run the suite after backend changes and before deployment to catch regressions in synchronous and asynchronous behavior.

Advanced Tips

Use the API Documentation During Development

FastAPI's documentation page is useful for inspecting the routes exposed by the running version of the project. Use it as the source of truth instead of assuming request fields or endpoint paths that are not documented in the README.

Separate Development and Production Secrets

Use the local .env file for development only. In production, configure secrets through WeChat Cloud Run or the selected container platform. Do not commit populated environment files to the repository.

Choose the Appropriate Knowledge Source

Use topic generation with Tavily when freshness matters. Use the document workflow when questions should be grounded in private or organization-specific material. Supported uploads are PDF, Word, Markdown, and TXT files.

Validate Services in Layers

1. Confirm that the health endpoint responds.
2. Inspect the FastAPI documentation.
3. Run pytest.
4. Compile the Taro frontend.
5. Open frontend/dist in WeChat DevTools.
6. Test login, quiz generation, feedback, history, and report review with the configured external services.

This order makes it easier to distinguish backend configuration problems from frontend compilation or WeChat tooling issues.

Prepare for Container Deployment

The repository includes backend/Dockerfile and backend/.dockerignore. These files allow the backend to be packaged as a Docker container for WeChat Cloud Run or another compatible platform.

Before deployment, run the tests, verify that required production environment variables are available through the platform, and avoid placing secrets in the image. Confirm that external dependencies such as MySQL, Tencent Cloud COS, model providers, Tavily, and WeChat authentication are reachable from the deployment environment.

Conclusion

This project provides a complete foundation for AI-assisted learning in WeChat: a Taro and React mini app, a FastAPI backend, topic and document-based quiz generation, immediate explanations, study reports, user history, and container-ready deployment. Start by validating the backend, compile the frontend in WeChat DevTools, and then configure the external services needed for your chosen learning workflow.