How to Contribute to the AiToEarn Project: A Complete Developer's Guide

To contribute to AiToEarn, fork the repository, set up your local environment for one of the three workspaces (Backend, Web, or Electron), verify your changes with the test suite, and submit a pull request following the guidelines in CONTRIBUTING.md.

The AiToEarn project is a comprehensive mono-repository managed by yikart/AiToEarn that powers an AI-driven earning platform through three distinct codebases. Whether you are fixing a bug in the NestJS backend, refining the Next.js web interface, or improving the Electron desktop client, understanding the repository structure and contribution workflow is essential for getting your code merged efficiently.

Understanding the AiToEarn Repository Structure

The AiToEarn mono-repo is organized into three primary workspaces, each with distinct technology stacks and responsibilities:

• Backend (project/aitoearn-backend): Built with Nx, pnpm, NestJS, MongoDB, Redis, and RabbitMQ. This workspace contains the AI agent service (aitoearn-ai) and the public API server (aitoearn-server).
• Web Front-end (project/aitoearn-web): Built with Next.js 14 (App Router) and pnpm, featuring Playwright for end-to-end testing.
• Electron Desktop (project/aitoearn-electron): Built with Electron, Vite, and **TypeScript` for the native desktop client.

Before writing code, review the AGENTS.md file at the repository root, which defines the project's communication protocols and overall architectural layout.

Setting Up Your Development Environment

Fork and Clone the Repository

Start by forking the repository on GitHub, then clone your fork locally:

# Clone your fork

git clone https://github.com/<your-username>/AiToEarn.git
cd AiToEarn

Backend Workspace Setup

Navigate to the backend directory and install dependencies:

cd project/aitoearn-backend
pnpm install

Copy the configuration templates for local development:

cp apps/aitoearn-ai/config/config.js apps/aitoearn-ai/config/local.config.js
cp apps/aitoearn-server/config/config.js apps/aitoearn-server/config/local.config.js

Start the development servers using Nx:

# Terminal 1: AI agent service (runs on port 3001 by default)

pnpm nx serve aitoearn-ai

# Terminal 2: Public API server (runs on port 3000 by default)

pnpm nx serve aitoearn-server

Key files to understand when contributing to the backend include:

• apps/aitoearn-ai/src/main.ts – Entry point for the AI agent service
• apps/aitoearn-server/src/main.ts – Entry point for the public API server
• apps/aitoearn-server/src/core/user/* – User-related controllers and services
• libs/* – Reusable libraries (e.g., libs/redis, libs/mongodb)

Web Front-end Setup

For UI contributions, set up the Next.js application:

cd project/aitoearn-web
pnpm install
pnpm run dev  # Starts dev server at http://localhost:3000

Important documentation files in the web workspace include project/aitoearn-web/README.md for the project overview and project/aitoearn-web/src/app/layout/README.md for layout specifics.

Electron Desktop Setup

For desktop client contributions:

cd project/aitoearn-electron
npm install
npm run rebuild  # Rebuild native modules like better-sqlite3

npm run dev      # Launch the Electron application

Reference project/aitoearn-electron/src/components/update/README.md for auto-update logic and project/aitoearn-electron/server/README.md for the desktop client's server-side architecture.

Running the Test Suite

All contributions must pass the existing test suites before submission.

Backend Testing

From the repository root, execute the NestJS tests:

# Run core agent tests

pnpm run test:agent

# Faster subset for rapid feedback during development

pnpm run test:agent:quick

Web End-to-End Testing

Run Playwright tests to verify UI behavior:

npx playwright test tests/e2e/home/simple-test.spec.ts --headed --project=chromium

Submitting Your Contribution

Create a Feature Branch

Follow standard Git workflow by creating a descriptive branch:

git checkout -b feature/<short-description>

# Make your changes

git add .
git commit -m "feat: <concise description>"
git push origin feature/<short-description>

Open a Pull Request

1. Navigate to the upstream yikart/AiToEarn repository and click New Pull Request.
2. Select your feature branch as the source and main as the target.
3. Link related issues using keywords like fixes #123.
4. Complete the checklist in the PR template, ensuring code style compliance, test coverage, and documentation updates.

The CI pipelines defined in .github/workflows/ (including backend-build.yml and web-build.yml) will automatically run linting, type-checking, and tests on your PR.

Common Contribution Patterns

Adding a New API Endpoint

When contributing to the backend, you might add endpoints in the user module:

// src/core/user/user.controller.ts
import { Controller, Get, Param } from '@nestjs/common';
import { UserService } from './user.service';

@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get('profile/:id')
  async getProfile(@Param('id') id: string) {
    return this.userService.getProfile(id);
  }
}

After implementation, run pnpm nx test aitoearn-server to ensure adequate test coverage.

Updating React Components

For web contributions, modify components following the existing patterns:

// src/components/PublishDialog/PublishDialog.tsx
import { useState } from 'react';

export default function PublishDialog() {
  const [isOpen, setOpen] = useState(false);
  // Component logic here
}

Implementing Electron IPC Handlers

For desktop features, add IPC handlers in the main process:

// src/main/electron.ts
import { ipcMain } from 'electron';

ipcMain.handle('get-user-info', async (event, userId) => {
  // Fetch from backend or local database
  return await fetchUserInfo(userId);
});

Remember to rebuild native modules with npm run rebuild after modifying Electron dependencies.

Summary

• Fork and clone the yikart/AiToEarn repository to your local machine.
• Choose your workspace: Backend (NestJS/Nx), Web (Next.js), or Desktop (Electron).
• Configure locally by copying template config files and installing dependencies with pnpm or npm.
• Write tests for new features and run the full suite using pnpm run test:agent and Playwright.
• Submit PRs against the main branch with clear descriptions and linked issues.
• Follow CI checks defined in .github/workflows/ to ensure code quality before merging.

Frequently Asked Questions

What are the system requirements for contributing to AiToEarn?

You need Node.js (version specified in the root package.json), pnpm for the backend and web workspaces, and npm for the Electron workspace. The backend additionally requires MongoDB, Redis, and RabbitMQ running locally or via Docker using the provided docker-compose.yml file.

How do I choose which workspace to contribute to?

Select based on your expertise and the issue at hand. Choose Backend (project/aitoearn-backend) for API changes, AI agent logic in apps/aitoearn-ai/src/core/agent/agent.service.ts, or database improvements. Choose Web (project/aitoearn-web) for React components, UI refinements, or e2e tests. Choose Electron (project/aitoearn-electron) for desktop-specific features or native module integrations.

What should I do if the CI checks fail on my pull request?

Review the specific error logs in the GitHub Actions tab under .github/workflows/. Common failures include linting errors, TypeScript type mismatches, or failing unit tests. Fix the issues locally, commit the changes to your feature branch, and push again—the checks will re-run automatically.

Is there a specific coding style or convention I must follow?

Yes, the project enforces consistent code style through the CI pipelines. Run linting commands locally before submitting (typically available via Nx targets or npm scripts in each workspace). Refer to existing files like apps/aitoearn-server/src/core/user/user.controller.ts for architectural patterns and maintain TypeScript strict mode compliance as configured in the workspace tsconfig.json files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}