🔧 Garagena — Auto Repair Service Hub

A mobile application connecting vehicle owners with local garages and automotive marketplaces in Morocco.

Built with React Native (Expo) + Node.js/Express + PostgreSQL/PostGIS following a strict Feature-Based Redux-Saga architecture.

---

📋 Table of Contents

1. Tech Stack
2. Project Structure
3. Getting Started
4. Architecture Rules
5. API Reference
6. Database Schema
7. Environment Variables
8. Troubleshooting

---

Tech Stack

Layer	Technology
Mobile App	React Native 0.73 + Expo SDK 50
State Management	Redux 5 + Redux-Saga
Styling	React Native StyleSheet
API Client	Axios
Backend	Node.js + Express
Database	PostgreSQL 17 + PostGIS 3.5
Auth	JWT (jsonwebtoken + bcrypt)
Infrastructure	Docker + Docker Compose

---

Project Structure

mecanic_hub3/
├── docker-compose.yml        # Database service (PostgreSQL + PostGIS)
├── init.sql                  # Full DB schema + seed data (auto-run by Docker)
│
├── backend/
│   ├── .env                  # ⚠️ NOT committed — see Environment Variables below
│   ├── server.js             # Express app entry point
│   ├── package.json
│   ├── config/
│   │   └── database.js       # PostgreSQL connection pool
│   ├── middleware/
│   │   └── auth.js           # JWT verification middleware
│   └── routes/
│       ├── auth.js           # POST /auth/login, /auth/register
│       ├── garages.js        # GET /garages/search, /garages/:id
│       ├── marketplace.js    # GET/POST /marketplace/posts
│       ├── profile.js        # GET /profile/client, /profile/garage
│       └── dashboard.js      # GET /dashboard/client, /dashboard/garage
│
└── src/
    ├── features/             # Feature modules (see Architecture Rules)
    │   ├── Auth/
    │   ├── GarageDiscovery/
    │   ├── Marketplace/
    │   └── Profile/
    │       ├── ClientProfile/
    │       └── GarageProfile/
    ├── components/           # Reusable UI components
    │   ├── AppButton.js
    │   ├── AppCard.js
    │   ├── AppInput.js
    │   ├── GarageCard.js
    │   └── CustomTabNavigator.js
    ├── navigation/
    │   └── AppNavigator.js   # Root navigator (Auth vs Main flow)
    ├── services/
    │   └── api.js            # Axios instance — update API_URL for your machine
    └── store/
        ├── index.js
        ├── rootReducer.js
        └── rootSaga.js

---

Getting Started

Prerequisites

• Node.js v18+
• Docker Desktop (running)
• Android Studio (for emulator) or Expo Go app on a physical device

---

Step 1 — Start the Database

# From project root
docker-compose up -d

# Verify it's healthy
docker ps
# Expected: mecanic_hub_db   Up (healthy)

# Verify seed data
docker exec -it mecanic_hub_db psql -U postgres -d garagena -c "SELECT name, city FROM garages;"

The database schema and seed data from init.sql run automatically on the first start.

---

Step 2 — Configure & Start the Backend

cd backend
npm install

Create backend/.env (or verify it exists):

PORT=3000
NODE_ENV=development

DB_HOST=localhost
DB_PORT=5432
DB_NAME=garagena
DB_USER=postgres
DB_PASSWORD=0000

JWT_SECRET=change_this_in_production
JWT_EXPIRES_IN=7d

node server.js
# Expected:
# ✅ Database connected successfully
# 🚀 Server running on port 3000

Test the backend:

# Should return garages in Rabat
curl "http://localhost:3000/api/garages/search?city=Rabat"

---

Step 3 — Configure & Start the Frontend

Find your machine's local IP:

# Windows PowerShell
ipconfig
# Look for "IPv4 Address" under your active network adapter

Update the API URL in src/services/api.js:

const API_URL = 'http://YOUR_LOCAL_IP:3000/api';
// Example: 'http://192.168.1.50:3000/api'
// ⚠️ Use 10.0.2.2 instead of localhost for Android Emulator

# From project root
npm install
npx expo start --lan

• Press a → Android Emulator
• Scan QR code with Expo Go → Physical device (must be on same WiFi)

---

Step 4 — Login with Seed Data

Role	Email	Password
Client	youssef@gmail.com	secret
Client	fatima@gmail.com	secret
Garage owner	garage1@gmail.com	secret
Admin	admin@garagena.ma	secret

---

Architecture Rules

Every feature must follow this exact structure. No exceptions.

src/features/[FeatureName]/
├── actionTypes/index.js    # String constants (e.g. FETCH_GARAGES_REQUEST)
├── actions/index.js        # Action creator functions
├── initialState/index.js   # Default Redux state shape
├── reducer/index.js        # Pure reducer function
├── sagas/index.js          # All API calls (side effects)
├── selectors/index.js      # Reselect memoized selectors
├── useCases/
│   ├── service.js          # Business logic (custom React hook)
│   └── main.js             # UI component (renders only)
└── index.js                # Public exports

Golden Rules

Rule	Detail
✅ API calls	Only in sagas/index.js via call(api.get, ...)
✅ Business logic	Only in useCases/service.js
✅ UI / JSX	Only in useCases/main.js
✅ State reads	Only via selectors/ using useSelector
✅ State writes	Only via actions/ dispatched through Redux
❌ Never	Direct axios calls inside components
❌ Never	useState for server data
❌ Never	Business logic inside main.js

Adding a New Feature — Checklist

• Create folder src/features/NewFeature/
• Define actionTypes/index.js
• Create actions/index.js
• Define initialState/index.js
• Create reducer/index.js
• Create sagas/index.js (add to store/rootSaga.js)
• Create selectors/index.js
• Create useCases/service.js
• Create useCases/main.js
• Export from index.js
• Add reducer to store/rootReducer.js
• Add to navigation in AppNavigator.js if needed

---

API Reference

Authentication

Method	Endpoint	Auth	Description
POST	/api/auth/register	No	Register new user
POST	/api/auth/login	No	Login, returns JWT
GET	/api/auth/me	Yes	Get current user

Register body:

{ "email": "user@example.com", "password": "Test1234!", "name": "John", "role": "client" }

---

Garages

Method	Endpoint	Auth	Description
GET	/api/garages/search	No	Search garages
GET	/api/garages/:id	No	Get garage detail
POST	/api/garages/:id/interaction	Yes	Track a click

Search query params:

Param	Type	Example	Description
city	string	Rabat	Filter by city
category	string	SERVICE	SERVICE, RETAIL, BOTH
lat + lng	float	34.01,-6.83	GPS center point
radius	int	10	Radius in km (default: 50)
sortBy	string	rating	rating or distance
minRating	float	4.0	Minimum rating filter

---

Marketplace

Method	Endpoint	Auth	Description
GET	/api/marketplace/posts	No	List items
POST	/api/marketplace/posts	Yes	Create listing
GET	/api/marketplace/posts/:id	No	Item detail
PUT	/api/marketplace/posts/:id	Yes	Update listing
DELETE	/api/marketplace/posts/:id	Yes	Delete listing

---

Profile

Method	Endpoint	Auth	Description
GET	/api/profile/client	Yes	Client profile
PUT	/api/profile/client	Yes	Update client profile
GET	/api/profile/client/vehicles	Yes	List vehicles
POST	/api/profile/client/vehicles	Yes	Add vehicle
GET	/api/profile/client/favorites	Yes	Favorite garages
POST	/api/profile/client/favorites/:id	Yes	Add favorite
GET	/api/profile/garage	Yes	Garage profile
PUT	/api/profile/garage	Yes	Update garage profile

---

Database Schema

See init.sql for the complete schema. Summary:

users
 └── garages         (one user → one garage for garage role)
 └── vehicles        (one user → many vehicles)
 └── favorites       (user ↔ garage junction)
 └── notifications   (one user → many notifications)
 └── messages        (user → user)

garages
 └── appointments    (client user + garage + vehicle)
 └── posts           (reviews: user + garage + rating)
 └── marketplace_items
 └── interactions    (analytics: whatsapp_click, call_click, etc.)
 └── garage_certifications

Garages use PostGIS GEOMETRY(Point, 4326) for GPS-based radius search.

---

Environment Variables

backend/.env — required, never commit

PORT=3000
NODE_ENV=development

DB_HOST=localhost
DB_PORT=5432
DB_NAME=garagena
DB_USER=postgres
DB_PASSWORD=0000

JWT_SECRET=change_this_in_production
JWT_EXPIRES_IN=7d

src/services/api.js — update per machine

const API_URL = 'http://<YOUR_LOCAL_IP>:3000/api';

For Android Emulator: use 10.0.2.2 instead of localhost

---

Troubleshooting

Problem	Solution
Error: connect ECONNREFUSED ::1:5432	Docker DB not running: docker-compose up -d
Network Error on device	Update API_URL in api.js with your PC's IP. Ensure same WiFi.
Port 5432 already in use	Stop local Postgres: net stop postgresql-x64-17
Port 3000 already in use	netstat -ano | findstr :3000 then kill the PID
Blank screen on login	Check Metro console for JS errors. Run npx expo start --clear
GPS not working on emulator	Set a manual location in Android Emulator's "..." → Location tab
Cannot read property 'latitude' of null	City search does not require GPS — this is handled automatically
DB schema out of date	Drop and recreate: docker-compose down -v && docker-compose up -d