Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
155 lines (106 loc) · 6.12 KB

CONTRIBUTING.md

File metadata and controls

155 lines (106 loc) · 6.12 KB

Contributing to ReadMando 🚀

Welcome to ReadMando! We're thrilled that you'd like to contribute. This document outlines the architecture, local setup instructions, and deployment strategies to help you get up and running quickly.

🏗 System Architecture

ReadMando follows a decoupled client-server architecture:

  • Frontend: React application built with Vite and TailwindCSS (frontend/my-app).
  • Backend: Python FastAPI service (backend/).
  • Database & Storage: Supabase (PostgreSQL for data, S3-compatible storage for audio files).
  • AI Integrations: OpenAI (GPT-4o-mini) for content generation, Edge-TTS/gTTS for text-to-speech, and Jieba for Chinese word segmentation.

💻 Local Development Setup

To ensure security features (like secure cookies and CORS) work correctly, both the frontend and backend are configured to run over local HTTPS using custom .pem certificates.

Prerequisites

1. Clone the Repository

git clone https://github.com/getter111/readMando.git
cd readMando

2. Backend Setup

The backend runs on FastAPI and uses a local development script to serve over HTTPS.

cd backend

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
# On Windows (CMD):
.\.venv\Scripts\activate.bat
# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# On Mac/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the local development server (HTTPS enabled)
python run.py

The backend will be available at https://127.0.0.1:8000.

3. Frontend Setup

The frontend is a Vite + React application.

cd frontend/my-app

# Install dependencies
npm install

# Start the Vite development server (HTTPS enabled)
npm run dev

The frontend will be available at https://localhost:5173.

⚠️ Note on SSL Warnings: Because we are using local .pem certificates (localhost+1.pem and localhost+1-key.pem), your browser may warn you that the connection is not private. You can safely bypass this warning for localhost by clicking "Advanced" -> "Proceed to localhost".

4. Environment Variables

To run the application locally, you will need to configure environment variables for both the frontend and backend. We have provided .env.example files to make this easy.

Backend (backend/): Copy the example file to create your local .env:

cp .env.example .env

Open backend/.env and fill in the missing values:

  • Supabase: You will need to create a free project on Supabase and paste your Project URL and API Key.
  • Stripe: Get your test secret key (sk_test_...) from the Stripe dashboard. Create a recurring product and add its Price ID (price_...).
  • OpenAI: Provide your API key from OpenAI.
  • Emails: The MAIL_ variables are required to test email features (like password reset/verification). If testing emails, provide valid SMTP credentials.
  • Security: Generate a random SECRET_KEY for local development.

Frontend (frontend/my-app/): Copy the example file to create your local .env:

cp .env.example .env

By default, VITE_API_BASE_URL is already set to https://127.0.0.1:8000, which matches the local backend.

5. Stripe Webhooks

To test Stripe checkout and user upgrades locally, you must run the Stripe CLI to forward webhooks to your local server:

  1. Download the Stripe CLI or use the executable in the backend folder (if installed).
  2. Authenticate the CLI: stripe login
  3. Start forwarding: stripe listen --forward-to https://localhost:8000/stripe-webhook --skip-verify
  4. The CLI will output a webhook signing secret (whsec_...). Copy this and add it to your backend/.env file as STRIPE_WEBHOOK_SECRET.
  5. You can now use test cards like 4242 4242 4242 4242 to verify the checkout flow locally.

6. Supabase Database & Storage Setup

To ensure the backend functions correctly with your local Supabase project, you must configure the database tables and storage bucket:

  1. Storage Bucket (Audio):

    • In your Supabase dashboard, navigate to Storage.
    • Create a new bucket named audio.
    • Set the bucket to Public so the frontend can stream the generated TTS audio files.

  2. Vocabulary Data Import:

    • The repository includes a file named Most Common Chinese words - Sheet1.csv.
    • In Supabase, navigate to the Table Editor and create or open your vocabulary table.
    • Use the Supabase CSV import tool to upload this file. This populates your database with the core vocabulary context required for the AI to generate appropriate stories and reading materials.

🚀 Deployment

Frontend (Netlify)

The frontend is hosted on Netlify.

  • Auto-deployment: Netlify is connected to the GitHub repository. Any code merged into the main branch will automatically trigger a production build (npm run build) and deploy the new version.

Backend (Fly.io)

The backend is containerized using Docker and hosted on Fly.io.

  • Auto-deployment: The backend is deployed automatically via GitHub Actions whenever changes are pushed or merged into the main branch.
  • Manual fallback: If you need to trigger a backend deployment manually, install the Fly CLI and run the following from the backend/ directory (note: fly may be available as an alias for flyctl in some environments): 
    cd backend
flyctl deploy

🤝 How to Contribute

  1. Fork the repository and clone your fork locally.
  2. Create a new branch for your feature or bugfix (git checkout -b feature/your-feature-name).
  3. Write your code, keeping our architecture and formatting in mind.
  4. Commit your changes with clear, descriptive messages.
  5. Push to your fork and submit a Pull Request against the main branch.

If you have any questions or ideas, feel free to open an issue or reach out to the maintainers!