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

> Learn how to contribute to the AiToEarn project. Fork the repo, set up your environment, run tests, and submit a pull request. Follow our developer guide to get started.

- Repository: [yikart/AiToEarn](https://github.com/yikart/AiToEarn)
- Tags: how-to-guide
- Published: 2026-05-12

---

**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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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:

```bash

# 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:

```bash
cd project/aitoearn-backend
pnpm install

```

Copy the configuration templates for local development:

```bash
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:

```bash

# 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`](https://github.com/yikart/AiToEarn/blob/main/apps/aitoearn-ai/src/main.ts) – Entry point for the AI agent service
- [`apps/aitoearn-server/src/main.ts`](https://github.com/yikart/AiToEarn/blob/main/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:

```bash
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`](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-web/README.md) for the project overview and [`project/aitoearn-web/src/app/layout/README.md`](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-web/src/app/layout/README.md) for layout specifics.

### Electron Desktop Setup

For desktop client contributions:

```bash
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`](https://github.com/yikart/AiToEarn/blob/main/project/aitoearn-electron/src/components/update/README.md) for auto-update logic and [`project/aitoearn-electron/server/README.md`](https://github.com/yikart/AiToEarn/blob/main/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:

```bash

# 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:

```bash
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:

```bash
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`](https://github.com/yikart/AiToEarn/blob/main/backend-build.yml) and [`web-build.yml`](https://github.com/yikart/AiToEarn/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/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`](https://github.com/yikart/AiToEarn/blob/main/tsconfig.json) files.