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
• Tech Stack
• Project Structure
• Getting Started
• Docker Deployment
• Development
• 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:

cd backend
npm install

2. Start the server:

npm start

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

🐳 Docker Deployment

Using Docker Compose (Recommended)

1. Build and start the application:

docker-compose up -d

2. View logs:

docker-compose logs -f

3. Stop the application:

docker-compose down

Using Docker directly

1. Build the image:

docker build -t oramap:latest .

2. Run the container:

docker run -d -p 3000:3000 --name oramap-app oramap:latest

3. Check health:

docker ps

💻 Development

Running in Development Mode

cd backend
npm run dev

Adding New Families

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

{
  "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:

curl "http://localhost:3000/api/search?family=Kafe"

Health Check

GET /api/health

Returns server health status.

Example Response:

{
  "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!