Relief Connect - Crisis Relief Management Platform

An open-source crisis relief management platform connecting people in need with volunteers, donors, and relief organizations.

Quick Start • Documentation • Contributing

---

📋 Table of Contents

• Overview
• Features
• Technology Stack
• Quick Start
• Testing Credentials
• Documentation
• Project Structure
• Contributing
• License

---

🎯 Overview

Relief Connect is a full-stack crisis relief management platform designed to coordinate emergency assistance during natural disasters and crises. The platform enables:

• Individuals to request help with location-based needs
• Volunteer Organizations to manage relief camps and coordinate efforts
• Donors to contribute resources to specific requests
• Administrators to oversee and manage the entire system

Built with modern technologies and best practices, Relief Connect provides a scalable, secure, and user-friendly solution for crisis management.

📖 Read Full Overview →

---

✨ Features

Core Features

• 🔐 Multi-Role Authentication - Users, Volunteer Clubs, Admins with JWT-based security
• 🆘 Help Request Management - Location-based requests with urgency levels and categories
• 🏕️ Relief Camp Management - Volunteer clubs can create and manage relief camps
• 💝 Donation System - Track donations with status workflow
• 👥 Volunteer Club System - Organizations can register and manage memberships
• 🗺️ Interactive Mapping - Leaflet maps with color-coded markers and filtering
• 👨‍💼 Admin Dashboard - Comprehensive system management and analytics
• 🌐 Multi-Language Support - English, Sinhala, and Tamil

📖 Read Full Features →

---

🛠️ Technology Stack

Frontend

• Next.js 15 - React framework with SSR/SSG
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• shadcn/ui - Accessible UI components
• Leaflet - Interactive maps

Backend

• Express.js - Web framework
• PostgreSQL - Relational database
• Sequelize - ORM for database operations
• JWT - Authentication tokens
• TypeScript - Type-safe backend

Infrastructure

• NX Monorepo - Workspace management
• Docker - Containerization
• GitHub Actions - CI/CD

📖 Read Full Tech Stack →

---

🚀 Quick Start

Prerequisites

• Node.js 18.x or higher
• PostgreSQL 14.x or higher (only if running backend locally)
• Yarn 4.x (via Corepack)

Installation

# Clone repository
git clone https://github.com/CodeSchool-LK/relief-connect.git
cd relief-connect

# Enable Corepack
corepack enable

# Install dependencies
yarn install

# Build shared library
yarn shared:build

Quick Start Options

Option 1: Frontend Only (Recommended for Quick Testing)

Use the deployed development API - no backend setup required!

1. Set up Frontend Environment (apps/web/.env.local):

# Use the deployed dev API
NEXT_PUBLIC_API_URL=https://dev-api.pasindusampath.com

# Map Configuration
NEXT_PUBLIC_MAP_TILE_URL=https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

2. Start Frontend Only:

yarn web:dev    # Frontend on port 3001

Access the application:

• Frontend: http://localhost:3001
• API: Uses https://dev-api.pasindusampath.com (no local backend needed)

Option 2: Full Local Development

Run both frontend and backend locally:

1. Set up Backend Environment (apps/api/.env):

   • Copy apps/api/env.example to apps/api/.env
   • Configure PostgreSQL credentials as shown in env.example:
     • DB_HOST=localhost
     • DB_PORT=5432
     • DB_NAME=nx_monorepo_dev
     • DB_USER=postgres
     • DB_PASSWORD=postgres (or your PostgreSQL password)
   • Set JWT secrets and other required variables

2. Set up Frontend Environment (apps/web/.env.local):

# Use local API
NEXT_PUBLIC_API_URL=http://localhost:3000

# Map Configuration
NEXT_PUBLIC_MAP_TILE_URL=https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

3. Start Development Servers:

yarn api:dev    # Terminal 1 - Backend on port 3000
yarn web:dev    # Terminal 2 - Frontend on port 3001

Access the application:

• Frontend: http://localhost:3001
• API: http://localhost:3000

📖 Read Full Quick Start Guide →

---

🧪 Testing Credentials (Development Environment)

Development URLs

• Frontend: https://dev-web.pasindusampath.com/
• Backend API: https://dev-api.pasindusampath.com/

Admin Login (Dev Environment Only)

• Username: pasindusampath
• Password: 77889900

Volunteer Club Login

• Username: test-club
• Password: 123456789

Normal Users

• No password required
• Users can log in using only their unique username

Creating New Volunteer Accounts

• You can create additional volunteer club accounts through the Admin Panel

Tip: To test the application without running a local backend, set NEXT_PUBLIC_API_URL=https://dev-api.pasindusampath.com in your apps/web/.env.local file and run only the frontend with yarn web:dev.

---

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Document	Description
Overview	Project purpose, goals, and vision
Features	Detailed feature breakdown
Technology Stack	Complete tech stack with versions
Architecture	System architecture and design patterns
Quick Start	Step-by-step setup instructions
Project Structure	Directory structure and organization
API Reference	Complete API endpoint documentation
Authentication & Authorization	Auth system and RBAC
Database Schema	Database tables and relationships
Deployment	Production deployment guide
Development	Development workflows and guidelines
Contributing	Contribution guidelines

---

🏗️ Project Structure

relief-connect/
├── apps/
│   ├── api/              # Express.js Backend
│   └── web/              # Next.js Frontend
├── libs/
│   └── shared/           # Shared code library
├── docs/                  # Documentation
├── docker-compose.yml     # Docker orchestration
└── package.json           # Root package.json

📖 Read Full Project Structure →

---

🔌 API Reference

Base URL

• Local Development: http://localhost:3000
• Dev Environment: https://dev-api.pasindusampath.com
• Production: https://api.yourdomain.com

Key Endpoints

• POST /api/auth/login - User authentication
• GET /api/help-requests - Get all help requests
• POST /api/help-requests - Create help request
• GET /api/camps - Get all relief camps
• POST /api/camps - Create camp (Volunteer Club)
• GET /api/volunteer-clubs - Get all volunteer clubs
• GET /api/admin/stats - System statistics (Admin)

📖 Read Full API Reference →

1. Build Docker images

   docker-compose build

2. Start services

   docker-compose up -d

3. View logs

   docker-compose logs -f

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit following Conventional Commits
5. Push to your branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📖 Read Full Contributing Guide →

The project includes Docker Compose files for different environments:

• docker-compose.yml - Base configuration
• docker-compose.dev.yml - Development
• docker-compose.qa.yml - QA environment
• docker-compose.staging.yml - Staging
• docker-compose.prod.yml - Production

CI/CD

This project is licensed under the MIT License - see the LICENSE file for details.

---

🆘 Support

• Issues: GitHub Issues
• Documentation: See docs/ directory
• Questions: Open a discussion on GitHub

---

🙏 Acknowledgments

• Built with ❤️ for crisis relief coordination
• Inspired by the need for efficient disaster response systems
• Thanks to all contributors and volunteers

---

🤝 Contributing

• Next.js Documentation
• Express.js Documentation
• Sequelize Documentation
• Leaflet Documentation
• TypeScript Documentation
• NX Documentation

---

Built with ❤️ to help connect people in need with those who can help

⬆ Back to Top