PinyImage

Create meaningful mental images to remember Mandarin characters forever!

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Installation
3. Usage
4. Contact

About The Project

One of the most important parts of language learning is being able to remember massive amounts of words and phrases, and especially with a system like Mandarin where characters give few clues to their meaning, the ability to recall their sound and function becomes essential.

PinyImage leverages your brain's natural ability to recall visual information to enhance and speed up character memorization. Tying character appearance to its meaning and sound using a mental image with familiar objects and feelings will store a character more strongly in your mind, ultimately leading to a better mastery of the Chinese language!

(back to top)

Built With

• React
• Node.js
• Bootstrap
• Masonry layout
• SQLite
• tilt.js
• Cohere AI API

(back to top)

Getting Started

Installation

1. Clone the repo

   git clone https://github.com/evan-thoms/pinyImage.git
   cd pinyImage

2. Backend Setup

   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Environment Configuration

   # Copy the example environment file
   cp env.example .env
   # Edit .env and add your API keys
   # Choose either COHERE_API_KEY or OPENAI_API_KEY

4. Frontend Setup

   cd ../frontend
   npm install

(back to top)

Usage

Local Development

1. Start the backend server

   cd backend
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   python main.py

2. Start the React frontend (in a new terminal)

   cd frontend
   npm start

3. Open your browser and navigate to http://localhost:3000

4. Input a Mandarin character and review the AI-generated mnemonic

5. Save desired responses to create study cards

6. Use the search functionality to filter through your saved cards

Deployment

Option 1: Render (Recommended - Free)

1. Fork this repository
2. Connect your fork to Render
3. Create a new Web Service
4. Add environment variables in Render dashboard:
   • COHERE_API_KEY or OPENAI_API_KEY
   • FLASK_ENV=production
5. Deploy automatically

Option 2: Heroku

1. Install Heroku CLI
2. Create a new Heroku app
3. Add environment variables:

   heroku config:set COHERE_API_KEY=your_key_here
   heroku config:set FLASK_ENV=production

4. Deploy:

   git push heroku main

Testing

Run the API tests:

cd backend
python test_api.py

(back to top)

Contributing

Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Evan Thoms - evanthoms@outlook.com

Project Link: https://github.com/evan-thoms/pinyImage

(back to top)