Developers Guide¶

1. System Overview
2. Architecture
3. Database Documentation
4. API Documentation
5. Docker & Deployment
6. CI/CD Pipeline
7. Resources
8. Contact & Support

System Overview ¶

The Dereja Monitoring and Evaluation System is a comprehensive platform designed to track, analyze, and report on various development programs and initiatives.

Key Features: - Real-time data collection and analysis - Multi-container Docker architecture - RESTful API for integrations - Metabase analytics integration - CI/CD deployment pipeline - AI chatbot interface

Architecture Diagram¶

graph TD
    subgraph Web Layer
        Nginx --> PHP
        Nginx --> WebData
    end

    subgraph Database Layer
        PHP --> MariaDB
        PHP --> PostgreSQL
        PHP --> MongoDB
    end

    subgraph Admin Tools
        phpMyAdmin --> MariaDB
        pgAdmin --> PostgreSQL
        MongoExpress --> MongoDB
    end

    subgraph Analytics
        Metabase --> PostgreSQL
    end

    subgraph AI
        Chatbot --> NLP_Models
    end

    classDef web fill:#4CAF50,stroke:#388E3C;
    classDef db fill:#2196F3,stroke:#1976D2;
    classDef admin fill:#9C27B0,stroke:#7B1FA2;
    classDef analytics fill:#FF9800,stroke:#F57C00;
    classDef ai fill:#E91E63,stroke:#C2185B;

    class Nginx,WebData,PHP web
    class MariaDB,PostgreSQL,MongoDB db
    class phpMyAdmin,pgAdmin,MongoExpress admin
    class Metabase analytics
    class Chatbot ai

Architecture ¶

Container Architecture¶

graph TD
    subgraph Docker_Network["Docker Network: 192.168.160.0/24"]
        WebData["Web Data Sync (192.168.160.55)
        (PHP-FPM Alpine)
        - File sync
        - Permissions management"]

        PHP["PHP Application (192.168.160.10)
        (PHP 7.4 + Nginx)
        - Main business logic
        - API endpoints"]

        Nginx["Nginx Reverse Proxy (192.168.160.20)
        - Ports 8880/8843
        - SSL termination
        - Load balancing"]

        subgraph Database_Layer["Database Layer"]
            MariaDB["MariaDB (192.168.160.50)
            - me_dereja DB
            - Port 3306"]

            PostgreSQL["PostgreSQL (192.168.160.40)
            - merqderejadb
            - Port 5432"]

            MongoDB["MongoDB (192.168.160.80)
            - merqderejadev
            - Port 27017"]
        end

        subgraph Admin_Interfaces["Admin Interfaces"]
            phpMyAdmin["phpMyAdmin (192.168.160.60)
            - Port 3307"]

            pgAdmin["pgAdmin (192.168.160.70)
            - Port 5454"]

            MongoExpress["Mongo Express (192.168.160.90)
            - Port 8018"]
        end

        Metabase["Metabase Analytics (192.168.160.30)
        - Port 4000
        - BI Dashboard"]

        Chatbot["AI Chatbot (192.168.160.100)
        (Python/Streamlit)
        - Port 8502
        - NLP processing"]
    end

    Nginx -->|Proxy PHP requests| PHP
    PHP -->|MySQL Connection| MariaDB
    PHP -->|PostgreSQL Connection| PostgreSQL
    PHP -->|MongoDB Connection| MongoDB
    WebData -->|Sync files| PHP
    WebData -->|Serve static content| Nginx
    phpMyAdmin -->|Manage| MariaDB
    pgAdmin -->|Manage| PostgreSQL
    MongoExpress -->|Manage| MongoDB
    Metabase -->|Analyze data| PostgreSQL
    Nginx -->|Serve static assets| WebData
    Chatbot -->|API calls| PHP
    Chatbot -->|Data store| MongoDB

    classDef web fill:#47C5FFFF,stroke:#039be5;
    classDef db fill:#F4FF78FF,stroke:#c0ca33;
    classDef admin fill:#FF7EA9FF,stroke:#f48fb1;
    classDef analytics fill:#AD76FFFF,stroke:#673ab7;
    classDef ai fill:#BEFF73FF,stroke:#689f38;

    class Nginx,PHP,WebData web
    class MariaDB,PostgreSQL,MongoDB db
    class phpMyAdmin,pgAdmin,MongoExpress admin
    class Metabase analytics
    class Chatbot ai

Service Port Mapping:

Database Documentation ¶

Core Schema Diagram¶

erDiagram
    CANDIDATES ||--o{ EDUCATION : has
    CANDIDATES ||--o{ EMPLOYMENT : has
    CANDIDATES ||--o{ DERJA_SERVICES : uses

    CANDIDATES {
        int CandidateID PK
        string Full_Name
        string Sex
        date DOB
        string Phone_Number
        string Email_Address
        string Region
    }

    EDUCATION {
        int EduID PK
        string Institution_Name
        string Field_Of_Study
        float GPA
        int CandidateID FK
    }

    EMPLOYMENT {
        int EmploymentID PK
        string Employment_Status
        string Employment_Company
        string Employment_Position
        int CandidateID FK
    }

    DERJA_SERVICES {
        int ServiceID PK
        string Dereja_Training_Services
        string Dereja_Event_Services
        int CandidateID FK
    }

Example Queries¶

1. Get candidate details:

SELECT
    c.CandidateID,
    c.Full_Name,
    e.Field_Of_Study,
    e.GPA,
    d.Dereja_Training_Services,
    emp.Employment_Status
FROM CANDIDATES c
JOIN EDUCATION e ON c.CandidateID = e.CandidateID
JOIN DERJA_SERVICES d ON c.CandidateID = d.CandidateID
JOIN EMPLOYMENT emp ON c.CandidateID = emp.CandidateID
WHERE c.Region = 'Oromia';

2. Employment status count:

SELECT
    Employment_Status,
    COUNT(*) AS Count
FROM EMPLOYMENT
GROUP BY Employment_Status;

API Documentation ¶

Candidate Data Endpoint¶

GET /api/candidates
Authorization: Bearer {token}

Response Structure:

{
  "success": true,
  "data": [
    {
      "CandidateID": "11",
      "Full_Name": "Meti Terefe Beyera",
      "Sex": "Female",
      "DOB": "1998-08-03",
      "Phone_Number": "904172631",
      "Email_Address": "methyterefe@gmail.com",
      "Region": "Oromia",
      "Education": {
        "Institution_Name": "Adama Science and Technology University",
        "Field_Of_Study": "Computer Science",
        "GPA": "3.23"
      },
      "Dereja_Services": {
        "Training": "ESJR",
        "Events": "Job Fair"
      },
      "Employment_Status": "Wage Employed",
      "Employment_Company": "Kenera General Plc",
      "Employment_Position": "Engineer"
    },
    {
      "CandidateID": "12",
      "Full_Name": "Sultan Woyema Beketa",
      "Sex": "Male",
      "Phone_Number": "970581770",
      "Email_Address": "sultanwoyenabkt@gmail.com",
      "Region": "Oromia",
      "Education": {
        "Institution_Name": "Adama Science and Technology University",
        "Field_Of_Study": "Civil Engineering",
        "GPA": "3.69"
      },
      "Dereja_Services": {
        "Training": "ESJR",
        "Events": "Campaign"
      },
      "Employment_Status": "Not Employed"
    }
  ]
}

Endpoint Parameters¶

Example Requests¶

curl -X GET "https://mne.dereja.com/app/api/v1.php?table=candidates&action=list&records=5&skip=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Running Directly on Browser¶

https://mne.dereja.com/app/api/v1.php?table=candidates&action=list&records=5&skip=10&apikey=your_api_key

Docker & Deployment ¶

docker-compose.yml Structure¶

version: '3.9'

services:
  # Core Services
  nginx:
    ports: ["8880:80", "8443:443"]
    depends_on: [php, metabase, chat]

  php:
    build:
      context: .
      target: base
    expose: ["9009"]

  db:
    image: mariadb:latest
    environment:
      MYSQL_DATABASE: me_dereja
      MYSQL_USER: me_dereja
      MYSQL_PASSWORD: me_dereja

  # Analytics
  metabase:
    image: metabase/metabase:latest
    ports: ["4000:3000"]
    environment:
      MB_DB_TYPE: postgres
      MB_DB_HOST: postgres

  # AI Chatbot
  chat:
    build:
      context: .
      target: ai_chatbot
    ports: ["8502:8502"]
    healthcheck:
      test: ["CMD", "curl", "--fail", "http://localhost:8502/_stcore/health"]

  # Management Tools
  phpmyadmin:
    image: phpmyadmin:latest
    ports: ["3307:80"]

  portainer:
    image: portainer/portainer-ce:latest
    ports: ["9099:9000"]

Deployment Commands¶

# Start the stack
docker-compose -f docker-compose.yml -p derejame up -d --build

# Stop and remove everything
docker-compose -p derejame down --volumes --rmi all

# Rebuild specific service
docker-compose -f docker-compose.yml -p derejame up -d --build php

Dockerfile Stages¶

# Base application image
FROM php:7.4-fpm as base
RUN apt-get update && apt-get install -y \
    libpng-dev libzip-dev mariadb-client
COPY . /var/www/html

# Nginx extended image
FROM nginx:latest as nginx_extended
RUN apt-get install -y mariadb-client postgresql-client
COPY config/nginx.conf /etc/nginx/conf.d/default.conf

# AI Chatbot image
FROM python:3.9-slim as ai_chatbot
WORKDIR /ai
COPY ai/chat/requirements.txt .
RUN pip install -r requirements.txt
COPY ai/chat .
EXPOSE 8502
CMD ["streamlit", "run", "app.py"]

CI/CD Pipeline ¶

graph LR
    A[Code Commit] --> B[Build App Image]
    A --> C[Build Chatbot Image]
    B --> D[Push to Registry]
    C --> D
    D --> E[Deploy to Production]

.gitlab-ci.yml Configuration¶

stages:
  - build
  - deploy

variables:
  DOCKER_REGISTRY: "docker.io"
  IMAGE_NAME: "mikeintosh/derejame"
  COMPOSE_PROJECT_NAME: "derejame"

build-app:
  stage: build
  script:
    - docker build -t $DOCKER_REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHORT_SHA .
    - docker push $DOCKER_REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHORT_SHA

deploy-production:
  stage: deploy
  script:
    - docker-compose -f docker-compose.yml -p $COMPOSE_PROJECT_NAME down
    - docker-compose -f docker-compose.yml pull
    - docker-compose -f docker-compose.yml -p $COMPOSE_PROJECT_NAME up -d
  only:
    - main

Pipeline Stages¶

Resources ¶

Deployment Assets¶

• docker-compose.yml
• Dockerfile
• .gitlab-ci.yml

API Tools¶

• Postman Collection
• Python SDK
• PHP SDK

Database Dumps¶

• Sample SQL Dump
• Schema Migration Scripts

Contact & Support ¶

Support Channels¶

• Email: support@merqconsultancy.org
• Emergency Support: +251 911 234 567
• Git Repository: gitlab.com/mikeintoshsystems/derejame

System Information¶

Dereja M&E System v3.2.1
API Version: v2.4
Database Schema: 5.1
Last Updated: July 25, 2025

Maintenance Schedule¶

```