NGOS-Backend Documentation

Last Updated: August 12, 2025

Introduction

Welcome to the official documentation for the NGOS-Backend system. This document provides a comprehensive overview of the system's architecture, database schema, API endpoints, and other critical components.

The NGOS-Backend is a robust and scalable platform built with Strapi v5, designed to serve as the backbone for an application that connects and supports non-governmental organizations (NGOs).

The system has evolved significantly over time, with a strong focus on data management, real-time communication, user engagement, and seamless integration with various third-party services. This documentation aims to provide developers with the knowledge needed to understand, maintain, and extend the system effectively.

System Architecture

The NGOS-Backend is built on a modern, decoupled architecture using Strapi as its core. This "headless" approach separates the backend content management and API layer from the frontend presentation layer, offering flexibility to build various client applications (web, mobile, etc.).

Core Components

  • Strapi v5 Core (Headless CMS): At its heart, the system uses Strapi to manage content. Strapi provides an intuitive admin panel for content creators and a powerful, auto-generated API for developers. It handles the complexities of content modeling, user authentication, and role-based access control (RBAC) out of the box.
  • Database (MySQL): MySQL serves as the primary data store. Strapi's data layer, powered by an ORM called knex.js, abstracts the database interactions, allowing developers to work with JavaScript objects and methods instead of writing raw SQL queries. This makes the data access layer clean and maintainable.
  • Real-time Layer (WebSockets): For instant, two-way communication, the system uses WebSockets. This is implemented for features like real-time chat and notifications, allowing the server to push updates to connected clients without them needing to poll for new data. This creates a more dynamic and engaging user experience.
  • Deployment & CI/CD: The application is containerized using Docker, which packages the application and its dependencies into a single, portable container. Docker Compose is used to define and run the multi-container application (the Strapi app, the MySQL database, Redis, etc.). The entire process, from code commit to deployment on a VPS, is automated using GitHub Actions, ensuring a consistent and reliable deployment pipeline.

Database Schema

The database schema is meticulously designed to support the complex relationships within the NGO ecosystem. It consists of interconnected "collection types" (similar to tables in a traditional database).

Schema Relationships

Understanding the relationships between different data models is key to working with the backend. Here is a summary of the most important relations:

  • User & Organization:
    • A User can be associated with one OrgProfile (One-to-One). This links a user account to the NGO they manage.
    • An OrgProfile has one owner (a User).
  • Content & Organization:
    • An OrgProfile can have many Posts, News articles, Events, and Webinars (One-to-Many).
    • Each Post, News, Event, and Webinar belongs to exactly one OrgProfile. This establishes clear ownership of content.
  • Geographic & Content Relations:
    • A City can have many OrgProfiles, Posts, Services, etc. (One-to-Many).
    • Content and profiles can be associated with a City to enable location-based filtering and searching.
  • Resources & Bookings:
    • A ResourceCenter can contain multiple Resources (One-to-Many).
    • A Resource can be booked multiple times, creating many Bookings (One-to-Many).
    • Each Booking is made by one User and is for one Resource.
  • Categorization:
    • A Category can be applied to many Webinars and other content types (One-to-Many). This allows for thematic organization.
    • Services are also linked to categories to help users find relevant services.
  • User Interaction:
    • A Post can have many Comments and many Post-Likes (One-to-Many).
    • A User can write many Comments and "like" many posts.

API Endpoints

The system exposes a comprehensive RESTful API. Below are details for some of the key endpoints. Standard CRUD operations (GET, POST, PUT, DELETE) are available for most, governed by user roles and permissions.

/api/org-profiles

Manages the core NGO profiles. This is a central endpoint for retrieving information about organizations.

  • GET /api/org-profiles: Fetches a list of all approved organization profiles.
  • GET /api/org-profiles/:id: Fetches a single organization profile by its ID.

// GET /api/org-profiles/1?populate=*
{
  "data": {
    "id": 1,
    "attributes": {
      "name": "Global Relief Foundation",
      "website": "https://globalrelief.org",
      "organization_status": "Approved",
      "createdAt": "2024-08-12T10:00:00.000Z",
      "city": {
        "data": {
          "id": 5,
          "attributes": { "name": "Geneva" }
        }
      },
      "focus_area": { /* ... */ }
    }
  }
}

/api/news & /api/webinars

Endpoints for fetching content published by NGOs.

  • GET /api/news: Fetches a paginated list of news articles.
  • GET /api/webinars: Fetches a paginated list of webinars. Supports filtering by category.

// GET /api/news?sort=createdAt:desc&pagination[limit]=5
{
  "data": [
    {
      "id": 101,
      "attributes": {
        "title": "New Initiative to Provide Clean Water",
        "slug": "new-initiative-clean-water",
        "createdAt": "2024-08-11T14:30:00.000Z",
        "org_profile": {
          "data": { "id": 1, "attributes": { "name": "Global Relief Foundation" } }
        }
      }
    }
    // ... more news articles
  ],
  "meta": { "pagination": { /* ... */ } }
}

/api/cities & /api/categories

Used for fetching taxonomies to populate UI filters and dropdowns.

  • GET /api/cities: Returns a list of all cities where NGOs operate.
  • GET /api/categories: Returns a list of all content and service categories.

// GET /api/cities
{
  "data": [
    { "id": 1, "attributes": { "name": "Tripoli", /* ... */ } },
    { "id": 2, "attributes": { "name": "Bengahzi", /* ... */ } }
  ]
}

/api/services

Provides a list of services offered by the NGOs.

  • GET /api/services: Fetches a list of available services, often filterable by city or category.

// GET /api/services?filters[city][name][$eq]=Tripoli
{
  "data": [
    {
      "id": 25,
      "attributes": {
        "name": "Legal Aid for Refugees",
        "description": "Providing free legal consultation...",
        "org_profile": {
          "data": { "id": 3, "attributes": { "name": "Cross-Border Legal" } }
        }
      }
    }
  ]
}

Third-Party Integrations

The NGOS-Backend integrates with several third-party services to enhance its functionality and provide a seamless user experience.

Key Integrations

  • OneSignal: For sending push notifications to mobile and web clients to keep users engaged.
  • AWS S3: For storing file uploads (like images and documents) and for automated database backups, ensuring data safety and scalability.
  • Google reCAPTCHA: To protect against spam and abuse in public-facing forms like the NGO registration.
  • Marsol and EasySMS: For sending SMS notifications and one-time passwords (OTPs) for phone number verification.
  • AI Translation Services: The system is configured for AI-powered translation to support multiple languages, making the platform accessible to a global audience.

Deployment

The application is designed for a streamlined deployment process using Docker and Docker Compose. The GitHub repository is also equipped with a GitHub Actions workflow to automate this process for a production environment.

Prerequisites

Before you begin, ensure you have the following:

  • A Virtual Private Server (VPS) running a modern Linux distribution (e.g., Ubuntu 22.04).
  • Docker and Docker Compose installed on the VPS.
  • A domain name pointed to your VPS's IP address.
  • Credentials for any required third-party services (e.g., AWS S3 bucket details, OneSignal App ID).

Configuration: The .env file

The entire application is configured via environment variables. Create a file named .env in the root of the project by copying the .env.example file. This is the most critical step.


# Server Configuration
HOST=0.0.0.0
PORT=1337
APP_KEYS=your_randomly_generated_app_keys
API_TOKEN_SALT=your_random_api_token_salt
ADMIN_JWT_SECRET=your_random_admin_jwt_secret
JWT_SECRET=your_random_jwt_secret
NODE_ENV=production

# Database Configuration
DATABASE_CLIENT=mysql
DATABASE_HOST=db # The name of the database service in docker-compose.yml
DATABASE_PORT=3306
DATABASE_NAME=ngos_db
DATABASE_USERNAME=strapi_user
DATABASE_PASSWORD=your_secure_password
DATABASE_SSL=false

# AWS S3 for file uploads and backups
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_ACCESS_SECRET=your_aws_secret
AWS_REGION=your_s3_bucket_region
AWS_BUCKET_NAME=your_s3_bucket_name

# Other services...

Note: The database DATABASE_HOST is set to db, which is the service name of the MySQL container defined in the docker-compose.yml file. Docker's internal networking will resolve this hostname to the correct container.

Quick Deployment Guide (Manual)

This guide assumes you are deploying manually on your VPS.

  1. Clone the Repository:
    git clone https://github.com/Moomken/ngos-backend.git
cd ngos-backend
  2. Create and Populate the .env file:
    cp .env.example .env
nano .env  # Or use your preferred editor to fill in the values
  3. Build and Run the Docker Containers:
    The docker-compose.yml file is configured to build the Strapi image and run both the Strapi application and the MySQL database service. 
    docker-compose up --build -d
    • --build forces Docker to rebuild the Strapi image if the Dockerfile has changed.
    • -d runs the containers in detached mode (in the background).
  4. Access Your Application:
    Once the containers are up, your Strapi application will be available at http://your_domain_or_ip:1337.
  5. Create Your First Admin User:
    Navigate to http://your_domain_or_ip:1337/admin to create the first administrator account for the Strapi backend.

For a production setup, you would typically run the application behind a reverse proxy like Nginx to handle HTTPS (SSL) and serve the application on the standard port 443.