Skip to content

CONTRIBUTING

Jump to bottom
github-actions[bot] edited this page Aug 2, 2026 · 8 revisions

🤝 Contributing to PersonalLearningPro

We love to receive contributions from the community and are thrilled that you're interested in making this project better! 🚀✨

🌍 Community

Join our Discord server for discussions, support, and to connect with other contributors: https://discord.gg/ewHtFk9G 💬✨

🏆 Top Contributor Reward

Burger Reward

🍔 The top contributor gets a meal from the admin at McDonald's! 🍟🥤

But that's not all — the 🌟 top contributor will also earn a spot as one of the 🔥 Super 5 Core Members for PersonalLearningPro. This is your chance to shape the future of this product, have a direct say in key decisions, and be recognized as a core part of the team. 👑✨

How to become the top contributor:

  • 📝 Submit high-quality pull requests
  • 🐞 Fix bugs and resolve issues
  • ✨ Add meaningful new features
  • 🤝 Help other contributors and review PRs
  • 📖 Improve documentation and testing

🎉 Contribute, rise to the top, enjoy a burger, and join the Super 5! 🚀🍔

🚀 Getting Started

🐳 Option 1: Docker (Recommended)

The fastest way to get a development environment running — no Node.js install required.

  1. 📦 Fork and clone the repository:

    git clone https://github.com/your-username/PersonalLearningPro.git
cd PersonalLearningPro

  2. ⚙️ Set up environment variables:

    cp .env.example .env

    Edit .env with your credentials. All variables are optional — see README.md for details.

  3. 🏗️ Build and run:

    docker compose build
docker compose up

  4. 🌐 Open http://localhost:5001 in your browser.

🔄 Source files are bind-mounted, so your edits are reflected immediately via hot reload — no rebuild needed for code changes.

💻 Option 2: Manual Setup

Requires Node.js v18+ and npm.

  1. 📦 Fork and clone the repository:

    git clone https://github.com/your-username/PersonalLearningPro.git
cd PersonalLearningPro

  2. 📦 Install dependencies:

    npm install

  3. ⚙️ Set up environment variables:

    cp .env.example .env

    Edit .env with your credentials (all optional).

  4. 🚀 Start the development server:

    npm run dev

💡 Pro Tip: Want to test with a full environment immediately? Run npx tsx server/scripts/seed-pilot.ts to seed a complete "Pilot School" with an admin user, classes, and tests.

  1. 🌐 Open http://localhost:5001 in your browser. Both the frontend and API are served from the same port.

📖 For a more detailed manual setup guide, see LOCAL_SETUP.md.

⚖️ Contributor License Agreement (CLA)

We require all contributors to sign a Contributor License Agreement before their first PR can be merged. 📝 When you open a PR, the CLA Assistant bot will comment with instructions. Simply reply with:

I have read the CLA Document and I hereby sign the CLA

You only need to sign once — it applies to all future contributions. Read the full CLA here. 📜

🔄 Contribution Workflow

  1. 🌿 Create a new branch for your feature or bug fix: 
    git checkout -b feature/your-feature-name
  2. 🛠️ Make your changes.
  3. 🧪 Run TypeScript checks before committing: 
    npm run check
  4. 📝 Commit your changes with a descriptive message.
  5. 🚀 Push your changes to your fork: 
    git push origin feature/your-feature-name
  6. 🔗 Open a pull request to the main branch of the original repository.

🤖 AI Agent Contributions

If you are using an AI coding agent (like Gemini CLI, Cursor, or Aider) to contribute to this project: 🧠🤖

  1. 📖 Read AGENTS.md and CLAUDE.md: Both live in the root directory and are tracked in git. They act as a "README for agents" — environment tips, testing instructions, coding conventions, and skill routing. 📜✨
  2. 🔐 Agent state stays local: .agent/, .agents/, .claude/ and .kiro are listed in .gitignore and are not tracked. They hold per-developer assistant configuration (agent definitions, commands, hooks, rules, skills, and machine-specific settings.local.json files), so their contents differ from machine to machine and are not shared through the repository. Set yours up however your tooling expects.
  3. 📋 Shared context belongs in tracked files: anything other contributors need to see goes in AGENTS.md, CLAUDE.md, docs/, or TODOS.md — never in an ignored agent directory, where a fresh clone will not have it. 🛡️✨

🏛️ Architecture Notes

  • 📦 Modular Server — Express serves the API via domain-driven routers (analytics, billing, chat, ai, etc.) and the Vite-powered React frontend on port 5001 🖥️
  • 💾 Hybrid storage — PostgreSQL (relational), Redis/BullMQ (queues), MongoDB (legacy), and Cassandra (chat) 📊
  • 📱 Mobile app — React Native + Expo with full offline support and push notifications 📲
  • 🔥 Firebase (optional) — Used for legacy auth compatibility; the platform primarily uses local PostgreSQL auth 🔐
  • 🤖 AI Engine — Powered by Google Gemini 2.0 Flash with OpenAI fallback 🧠💡

🎨 Coding Style

This project uses ESLint and Prettier for code formatting and linting. Please run these commands before committing:

npm run lint        # Check for linting errors
npm run lint:fix    # Auto-fix linting errors
npm run format      # Format code with Prettier
npm run check       # TypeScript type checking

Follow the existing code style in the files you are editing to maintain consistency. 📏✨

🐞 Reporting Bugs

If you find a bug, please create an issue on GitHub. 🐞 Include:

  • A clear and descriptive title 📝
  • Steps to reproduce the bug 🔄
  • Any relevant error messages or screenshots 📸

✨ Suggesting Enhancements

If you have an idea for an enhancement, please create an issue on GitHub. 💡 Include:

  • A clear and descriptive title 📝
  • A description of the enhancement and the problem it solves 🚀

📚 Additional Resources

Thank you for your interest in contributing to this project! 🚀✨🎓

Clone this wiki locally