Docs/add contributing guide

CONTRIBUTING.md

@@ -1,116 +1,192 @@
 # Contributing to DevCard
 
-<p align="center">
-  <a href="https://discord.gg/QueQN83wn">
-    <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white&style=flat-square" alt="Discord Server" />
-  </a>
-</p>
+Thank you for your interest in contributing to **DevCard**! DevCard is an open-source developer profile exchange platform that aggregates your developer profiles into a single shareable QR code.
 
-**Join the community** — ask questions, get help, discuss ideas, and meet other contributors on our [Discord server](https://discord.gg/QueQN83wn).
+By contributing, you help make networking easier and more accessible for developers around the world. Please take a moment to review this guide before getting started.
 
-## Development Setup
+---
 
-### Prerequisites
+## Table of Contents
+1. [Project Overview](#project-overview)
+2. [Prerequisites](#prerequisites)
+3. [Local Setup](#local-setup)
+4. [Branch Naming Conventions](#branch-naming-conventions)
+5. [Pull Request Process & Checklist](#pull-request-process--checklist)
+6. [Issue Labels Guide](#issue-labels-guide)
+7. [Coding Standards](#coding-standards)
 
-- **Node.js** >= 20
-- **npm** >= 10 (bundled with Node.js)
-- **Docker** & Docker Compose
-- **React Native** dev environment — follow the [official setup guide](https://reactnative.dev/docs/environment-setup)
+---
 
-### Getting Started
+## Project Overview
 
-```bash
-# 1. Fork and clone the repo
-git clone https://github.com/Dev-Card/DevCard.git
-cd devcard
-
-# 2. Install dependencies
-npm install                              # root (orchestrator)
-npm --prefix packages/shared install     # shared types/utils
-npm --prefix apps/backend install        # backend API
-npm --prefix apps/web install            # web app
-npm --prefix apps/mobile install         # mobile app (if working on mobile)
-
-# 3. Start PostgreSQL + Redis
-docker compose up -d
+DevCard is structured as a monorepo containing the web frontend, mobile frontend, backend API, and a shared packages library.
 
-# 4. Configure environment
-cp .env.example .env
-# Edit .env with your OAuth credentials
+```text
+devcard/
+├── apps/
+│   ├── backend/          # Fastify API (TypeScript, Prisma ORM, Vitest)
+│   ├── mobile/           # React Native mobile app (Bare Workflow, Jest)
+│   └── web/              # React + Vite web app (TypeScript, ESLint)
+├── packages/
+│   └── shared/           # Shared types, platform registry, and utility functions
+├── docker/               # Docker files and configurations
+├── docker-compose.yml    # Runs PostgreSQL and Redis services
+└── package.json          # Root orchestrator (npm scripts to run workspace tasks)
+```
 
-# 5. Run database migrations and seed
-npm run db:migrate
-npm run db:seed
+---
 
-# 6. Start development
-npm run dev:backend    # Backend API on :3000
-npm run dev:mobile     # React Native app
-```
+## Prerequisites
+
+To run DevCard locally, you will need the following installed:
+
+*   **Node.js**: `v20.x` or `v22.x` (Long Term Support recommended)
+*   **npm**: `v10.x` or higher (usually bundled with Node.js)
+*   **Docker & Docker Compose**: Used to run PostgreSQL 16 and Redis 7 databases locally.
+*   **React Native / Mobile Environment**:
+    *   **React Native CLI** (Bare workflow environment setup) — follow the [official React Native setup guide](https://reactnative.dev/docs/environment-setup) for your OS (Android Studio / Xcode).
+    *   **Expo CLI** (if doing secondary Expo testing or building). Note that the primary mobile app in `apps/mobile` is a bare React Native project.
+*   **Backend Runtime & Tools**:
+    *   **PostgreSQL**: (Provided via Docker)
+    *   **Redis**: (Provided via Docker)
+
+---
 
-### Running Tests
+## Local Setup
+
+Follow these step-by-step instructions to get the project running on your local machine:
+
+### 1. Clone the Repository
+Fork the repository on GitHub, then clone your fork:
+```bash
+git clone https://github.com/YOUR-USERNAME/DevCard.git
+cd DevCard
+```
 
-This project uses `npm` to run tests across different parts of the codebase.
+### 2. Install Dependencies
+Install all package dependencies from the root directory. This will install dependencies for all monorepo workspaces:
+```bash
+npm install
+```
 
-#### Run all tests
-To execute backend tests:
+### 3. Start Database and Cache Services
+Run Docker Compose to start PostgreSQL and Redis in the background:
 ```bash
-npm run test
+docker compose up -d
 ```
 
-#### apps/backend
-The backend uses Vitest:
+### 4. Configure Environment Variables
+Copy the template `.env.example` in the root (or `apps/backend`) to `.env` inside `apps/backend/`:
 ```bash
-npm --prefix apps/backend run test
-npm --prefix apps/backend run test:watch
+cp .env.example apps/backend/.env
 ```
-#### apps/mobile
-The mobile app uses Jest:
+Open `apps/backend/.env` and generate the required secure secrets:
+*   **JWT_SECRET**: Generate using:
+    ```bash
+    node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
+    ```
+*   **ENCRYPTION_KEY**: Generate using:
+    ```bash
+    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+    ```
+Paste these values into `apps/backend/.env`.
+
+### 5. Run Database Migrations and Seed
+Initialize your PostgreSQL database schemas and seed it with dummy developer profiles:
 ```bash
-npm --prefix apps/mobile run test
+# Run migrations
+npm run db:migrate
+
+# Seed sample database data
+npm run db:seed
 ```
-#### apps/web
-Currently, the web app does not define a test script.
 
-#### packages/shared
-The shared package does not include test scripts. It only provides linting and type checking.
+### 6. Run the Applications
+
+You can run individual parts of the project from the root directory using the following orchestrator scripts:
+
+*   **Run Backend API**:
+    ```bash
+    npm run dev:backend
+    ```
+    This starts the Fastify server (usually listening on `http://localhost:3000`).
+*   **Run Web App**:
+    ```bash
+    npm run dev:web
+    ```
+    This starts the Vite-powered React web dashboard.
+*   **Run Mobile App**:
+    Make sure your Android Emulator or iOS Simulator is running, then execute:
+    ```bash
+    npm run dev:mobile
+    ```
+    And in another terminal window to launch on Android:
+    ```bash
+    npm run android
+    ```
 
+---
 
-## Project Structure
+## Branch Naming Conventions
 
-```
-devcard/
-├── apps/backend/     # Fastify API (TypeScript)
-├── apps/mobile/      # React Native mobile app
-├── apps/web/         # SvelteKit web backup
-└── packages/shared/  # Shared types, utils, platform registry
-```
+We enforce prefix-based branch naming to keep the repository history organized. When creating a branch, use one of the following prefix structures:
 
-## Coding Standards
+*   `feat/` — For new features or additions (e.g., `feat/add-github-oauth`)
+*   `fix/` — For bug fixes and patches (e.g., `fix/event-organizer-id`)
+*   `docs/` — For updates to documentation or guides (e.g., `docs/contributing-guide`)
+*   `chore/` — For build processes, dependency updates, or tool configurations (e.g., `chore/upgrade-prisma`)
 
-- **TypeScript** for all new code
-- **ESLint + Prettier** for formatting (run `npm run lint` before committing)
-- **Conventional Commits** for commit messages (`feat:`, `fix:`, `docs:`, `chore:`)
-- Write tests for new features and bug fixes
+Use hyphens to separate words (kebab-case) and keep names concise.
 
-## Pull Request Process
+---
 
-1. Create a feature branch from `main`: `git checkout -b feat/your-feature`
-2. Make your changes with clear, descriptive commits
-3. Ensure all tests pass: `npm run test`
-4. Ensure linting passes: `npm run lint`
-5. Open a PR against `main` with a clear description of the change
-6. Wait for review — maintainers will respond within 48 hours
+## Pull Request Process & Checklist
+
+When you are ready to submit your changes, follow this process:
+
+### 1. PR Checklist
+Before opening a Pull Request, please ensure you satisfy the following checklist:
+- [ ] Code compiles and builds without errors.
+- [ ] Linting passes: Run `npm run lint` from the root.
+- [ ] Tests pass: Run `npm run test` (Vitest backend tests) and ensure zero failures.
+- [ ] Your branch name matches our [Branch Naming Conventions](#branch-naming-conventions).
+- [ ] Your commits use clear descriptions and follow [Conventional Commits](https://www.conventionalcommits.org/) format (e.g., `feat(auth): add GitHub login flow`).
+- [ ] You have updated/added tests for any new features or bug fixes.
+- [ ] Documentation has been updated if applicable.
+
+### 2. Submitting the PR
+1. Push your branch to your GitHub fork:
+   ```bash
+   git push origin branch-name
+   ```
+2. Navigate to the main [DevCard Repository](https://github.com/Dev-Card/DevCard) and click **New Pull Request**.
+3. Choose your fork and branch, write a clear title and description outlining:
+    *   What problem does this PR solve?
+    *   How was it resolved?
+    *   Any testing steps or verification done.
+4. Submit the PR and wait for a review from the maintainers. Reviews are usually conducted within 24–48 hours.
+
+---
 
-## Reporting Issues
+## Issue Labels Guide
 
-- Use GitHub Issues for bug reports and feature requests
-- Include reproduction steps for bugs
-- Search existing issues before creating a new one
+We use specific labels to categorize and track issues. Here is a guide to what they mean:
 
-## Code of Conduct
+*   `good-first-issue` — Welcoming issues for newcomers or first-time contributors. Usually has clear instructions.
+*   `bug` — A reproducible issue or error in the codebase.
+*   `enhancement` — A request for new features, optimizations, or enhancements.
+*   `documentation` — Work related to writing or updating READMEs, guides, or code docstrings.
+*   `help wanted` — Extra attention or specific expertise is requested to solve the issue.
+*   `gssoc24` / `hacktoberfest` — Labels indicating participation in open-source programs like GirlScript Summer of Code or Hacktoberfest.
+
+---
+
+## Coding Standards
 
-Be kind, inclusive, and constructive. We follow the [Contributor Covenant](https://www.contributor-covenant.org/).
+*   **TypeScript**: Use static typing wherever possible. Avoid using `any` and define proper interfaces/types.
+*   **Formatting**: We use ESLint and Prettier for code style consistency. Run `npm run lint` or format files directly in your IDE before committing.
+*   **Migrations**: Do not modify existing Prisma migrations. Create new migrations via `prisma migrate dev` if you modify `schema.prisma`.
 
 ---
 
-Thank you for helping make DevCard better! 🎉
+Thank you for contributing to DevCard! 🚀