oramap/README.md

# 🗺️ Ora Map - Family Location Mapping Application

A full-stack web application for mapping and searching family locations in Yemen using interactive maps.

## 📋 Table of Contents
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Getting Started](#getting-started)
- [Docker Deployment](#docker-deployment)
- [Development](#development)
- [API Endpoints](#api-endpoints)

## ✨ Features

- 🔍 **Family Search**: Search for families by name with autocomplete suggestions
- 🗺️ **Interactive Map**: Leaflet-based map with multiple tile layer options
- 📍 **Location Markers**: View family locations with city information
- 🎨 **Modern UI**: Clean and responsive design
- 🐳 **Docker Ready**: Containerized for easy deployment
- 💚 **Health Checks**: Built-in health monitoring

## 🛠️ Tech Stack

**Backend:**
- Node.js
- Express.js
- JSON data storage

**Frontend:**
- HTML5/CSS3
- JavaScript (ES6+)
- Leaflet.js (interactive maps)
- Fuse.js (fuzzy search)

**DevOps:**
- Docker
- Docker Compose

## 📁 Project Structure

```
oramap/
├── backend/
│   ├── server.js           # Express server
│   ├── package.json        # Backend dependencies
│   └── data/
│       └── families.json   # Family location data
├── public/
│   ├── index.html          # Frontend HTML
│   ├── script.js           # Frontend JavaScript
│   └── style.css           # Styles
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.yml      # Docker Compose configuration
└── .dockerignore          # Docker ignore rules
```

## 🚀 Getting Started

### Prerequisites
- Node.js (v18 or higher)
- Docker & Docker Compose (optional, for containerized deployment)

### Local Development

1. **Install backend dependencies:**
```bash
cd backend
npm install
```

2. **Start the server:**
```bash
npm start
```

3. **Open your browser:**
Navigate to `http://localhost:3000`

## 🐳 Docker Deployment

### Using Docker Compose (Recommended)

1. **Build and start the application:**
```bash
docker-compose up -d
```

2. **View logs:**
```bash
docker-compose logs -f
```

3. **Stop the application:**
```bash
docker-compose down
```

### Using Docker directly

1. **Build the image:**
```bash
docker build -t oramap:latest .
```

2. **Run the container:**
```bash
docker run -d -p 3000:3000 --name oramap-app oramap:latest
```

3. **Check health:**
```bash
docker ps
```

## 💻 Development

### Running in Development Mode

```bash
cd backend
npm run dev
```

### Adding New Families

Edit `backend/data/families.json` and add entries in the following format:

```json
{
  "family": "Family Name (Hebrew)",
  "city": "City Name (Hebrew)",
  "lat": 15.3545,
  "lng": 44.2064
}
```

## 📡 API Endpoints

### Search Families
```
GET /api/search?family={familyName}
```
Returns matching family records with location data.

**Example:**
```bash
curl "http://localhost:3000/api/search?family=Kafe"
```

### Health Check
```
GET /api/health
```
Returns server health status.

**Example Response:**
```json
{
  "status": "ok",
  "timestamp": "2026-03-24T10:30:00.000Z"
}
```

## 🗺️ Available Family Names

- Kafe (קאפח)
- Shiheb (שחב-שבח)
- Uzeyri (עזירי-עוזרי)
- Salumi (סלומי-שלומי)
- Afgin (עפג'ין)
- Eraki (עראקי)

## 📝 License

ISC

## 🤝 Contributing

Contributions, issues, and feature requests are welcome!