- 
-
| π Stars | -π΄ Forks | -π Issues | -π Open PRs | -π Close PRs | -
 |
-  |
-  |
-  |
-  |
-
-
- 
-
-
+### Backend tests
+From the project root:
+```bash
+npm run test:backend
+```
+
+The backend tests cover areas including:
+
+* User model behaviour
+* Password hashing
+* Password comparison
+* Authentication routes
+* Signup and login flows
+* Passport authentication logic
+* API integration behaviour
+
+You can also run Jasmine directly when required:
+
+```bash
+npx jasmine
+```
+
+### Test files
+
+Backend test files are located under:
+
+```text
+spec/
+```
+
+Examples include:
+
+```text
+spec/user.model.spec.cjs
+spec/auth.routes.spec.cjs
+```
+
+### Frontend tests
+
+Vitest is available through:
+
+```bash
+npm test
+```
+
+Additional frontend testing dependencies include React Testing Library and JSDOM.
+
+---
+
+## Linting and Build
+
+Run ESLint:
+
+```bash
+npm run lint
+```
+
+Create a production frontend build:
+
+```bash
+npm run build
+```
+
+Preview the production build locally:
+
+```bash
+npm run preview
+```
+
+These checks should be performed before submitting a pull request where applicable.
+
+---
+
+## Contribution Workflow
+
+The recommended contribution workflow is:
+
+```text
+Fork repository
+ β
+Clone your fork
+ β
+Create a feature branch
+ β
+Install dependencies
+ β
+Create and test changes
+ β
+Run lint/tests/build
+ β
+Commit changes
+ β
+Push branch
+ β
+Open Pull Request
+ β
+Address review feedback
+```
+
+For detailed contribution instructions, see [CONTRIBUTING.md](CONTRIBUTING.md).
---
-
+## Troubleshooting
+
+### `npm install` fails
+
+Check that you are using a supported Node.js version:
+
+```bash
+node --version
+```
+
+Then remove dependencies and reinstall if necessary:
+
+```bash
+rm -rf node_modules
+npm install
+```
+
+On Windows, you can delete the `node_modules` directory manually and run:
+
+```bash
+npm install
+```
+
+### Frontend does not start
+
+Make sure you are running the command from the repository root:
+
+```bash
+npm run dev
+```
+
+Check that port `5173` is not already being used.
+
+### Backend does not start
+
+Make sure backend dependencies are installed:
+
+```bash
+cd backend
+npm install
+```
+
+Also verify that MongoDB is running and that the required backend environment variables are configured.
+
+### MongoDB connection errors
+
+Make sure MongoDB is running and that the connection configuration in `backend/.env` is correct.
+
+The local MongoDB setup commonly uses:
+
+```text
+mongodb://127.0.0.1:27017
+```
+
+### Docker errors
+
+Make sure Docker Desktop is running.
+
+Check the available containers:
+
+```bash
+docker ps
+```
+
+Rebuild the development environment when dependencies or Docker configuration change:
+
+```bash
+docker compose --profile dev up --build
+```
+
+### Tests cannot find modules
+
+Install dependencies again:
+
+```bash
+npm install
+```
+
+If backend dependencies are missing:
+
+```bash
+cd backend
+npm install
+```
+
+---
+
+## Contribution
+
+New contributors should read [CONTRIBUTING.md](CONTRIBUTING.md) before making changes.
+
+Please ensure that changes are focused, tested where applicable, and clearly described in the pull request.
+
+Thank you for contributing to GitHub Tracker!
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 00000000..e5d3df45
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,288 @@
+# Development Guide
+
+This document provides a quick reference for contributors working on GitHub Tracker.
+
+---
+
+## Development Architecture
+
+GitHub Tracker consists of two main application layers:
+
+```text
+ GitHub Tracker
+ |
+ ββββββββββββββ΄βββββββββββββ
+ | |
+ Frontend Backend
+ React Express
+ | |
+ Vite MongoDB
+ |
+ User Interface
+```
+
+### Frontend
+
+The frontend is located in:
+
+```text
+src/
+```
+
+The application uses React and Vite.
+
+Start frontend development with:
+
+```bash
+npm run dev
+```
+
+The Vite development server runs on port `5173`.
+
+### Backend
+
+The backend is located in:
+
+```text
+backend/
+```
+
+It uses Node.js and Express and communicates with MongoDB.
+
+Install backend dependencies:
+
+```bash
+cd backend
+npm install
+```
+
+The backend Docker service uses port `5000`.
+
+---
+
+## Development Options
+
+There are two recommended ways to work on the project.
+
+### Option 1: Run services locally
+
+Run the frontend from the repository root:
+
+```bash
+npm install
+npm run dev
+```
+
+Run the backend from a separate terminal:
+
+```bash
+cd backend
+npm install
+```
+
+### Backend
+
+The backend is located in:
+
+```text
+backend/
+```
+
+It uses Node.js and Express and communicates with MongoDB.
+
+Install backend dependencies:
+
+```bash
+cd backend
+npm install
+```
+
+For development, use:
+
+```bash
+npm run dev
+```
+
+This starts the server with Nodemon, which automatically restarts the server when backend files change.
+
+For a normal start:
+
+```bash
+npm start
+```
+
+The backend Docker service uses port `5000`.
+
+
+This approach is useful when actively developing and debugging individual services.
+
+---
+
+### Option 2: Use Docker
+ **MongoDB:** MongoDB is not included in Docker Compose. Contributors must have MongoDB running separately and configure the backend to connect to it.
+
+Docker Compose can start the frontend and backend together.
+
+From the repository root:
+
+```bash
+npm run docker:dev
+```
+
+Equivalent command:
+
+```bash
+docker compose --profile dev up --build
+```
+
+Stop the services with:
+
+```bash
+docker compose --profile dev down
+```
+
+---
+
+## Ports
+
+| Component | Development Port |
+| --------- | ---------------: |
+| Frontend | 5173 |
+| Backend | 5000 |
+
+The production frontend is exposed on port `3000`.
+
+---
+
+## Testing Workflow
+
+Backend tests are located in:
+
+```text
+spec/
+```
+
+Run backend tests:
+
+```bash
+npm run test:backend
+```
+
+Run frontend tests:
+
+```bash
+npm test
+```
+
+Before submitting a pull request, also run:
+
+```bash
+npm run lint
+npm run build
+```
+
+---
+
+## Recommended Contributor Workflow
+
+```text
+Read issue
+ β
+Understand existing implementation
+ β
+Create feature branch
+ β
+Install dependencies
+ β
+Configure environment
+ β
+Run application
+ β
+Implement changes
+ β
+Run tests
+ β
+Run lint/build
+ β
+Review changes
+ β
+Commit
+ β
+Push branch
+ β
+Open Pull Request
+```
+
+---
+
+## Docker Workflow
+
+### Development
+
+```bash
+docker compose --profile dev up --build
+```
+
+### Stop development containers
+
+```bash
+docker compose --profile dev down
+```
+
+### Production
+
+```bash
+docker compose --profile prod up -d --build
+```
+
+### Stop production containers
+
+```bash
+docker compose --profile prod down
+```
+
+---
+
+## Environment Configuration
+
+Environment-specific configuration should remain outside version control.
+
+The project expects environment files for local/Docker configuration:
+
+```text
+.env
+backend/.env
+```
+
+Never commit secrets or credentials.
+
+When adding a new environment variable:
+
+1. Identify which service uses it.
+2. Add it to the appropriate local environment file.
+3. Update the documentation if contributors need to configure it.
+4. Do not commit the actual secret value.
+
+---
+
+## Before Opening a Pull Request
+
+Run the checks relevant to your changes:
+
+```bash
+npm run lint
+npm test
+npm run test:backend
+npm run build
+```
+
+Not every change requires every check, but contributors should run the checks affected by their changes.
+
+Review the final diff before pushing:
+
+```bash
+git status
+git diff
+```
+
+A clean, focused pull request makes review easier and helps maintain project quality.