Charity Service Platform (Transparent Donations)

A platform for transparent charitable donations where donors support verified organizations through campaigns. Administrators moderate and approve campaigns to ensure trust and accountability. The project focuses on transparency, traceability of donations, and clear campaign management.

---

Table of Contents

• Overview
• Roles and Use Cases
• Features
• Architecture
• Data Model (ERD)
• Statuses and Rules
• API (Draft Structure)
• Running the Project
• Project Structure
• Development Plan and Contribution
• Diagrams

---

Overview

The Charity Service Platform connects donors with charitable organizations through fundraising campaigns. Organizations create campaigns, donors make contributions, and administrators review and approve campaigns before they become publicly available.

---

Roles and Use Cases

Roles

• Donor

  • Browse campaigns
  • Donate to campaigns
  • View personal donation history

• Organization

  • Register an organization
  • Create and manage campaigns
  • Submit campaigns for approval
  • View reports and analytics

• Administrator

  • Approve or reject campaigns
  • Moderate users and content
  • View moderation records and platform reports

---

Features

Must Have

• User registration and authentication
• Role-based access (Donor / Organization / Admin)
• Organization registration and verification
• Campaign creation and management
• Donation processing and donation history
• Administrative moderation tools

Should Have

• Campaign and organization donation summaries

Could Have

• Campaign categories and tags
• Donation comments
• Basic analytics and reporting export

---

Architecture

The system follows a layered (clean) architecture:

• API (HTTP layer)

  • Router (mux) and middleware
  • Request handlers

• Service layer (Business Logic)

  • AuthService
  • CampaignService
  • DonationService

• Repository layer (Data Access)

  • UserRepo
  • OrgRepo
  • CampaignRepo
  • DonationRepo
  • ModerationRepo

• Domain layer

  • Entities: User, Organization, Campaign, Donation, ModerationRecord

• Integrations (could be)

  • Payment gateway
  • Email / SMS notifications

• Database

  • PostgreSQL

---

Data Model (ERD)

Entities

Users

• user_id : UUID
• name : string
• email : string (unique)
• password_hash : string
• role : DONOR | ORG | ADMIN
• created_at : datetime

Organizations

• org_id : UUID
• owner_user_id : UUID (FK → Users)
• name : string
• description : text
• status : PENDING | APPROVED | SUSPENDED
• created_at : datetime

Campaigns

• campaign_id : UUID
• org_id : UUID (FK → Organizations)
• title : string
• description : text
• target_amount : decimal
• current_amount : decimal
• status : DRAFT | PENDING | APPROVED | REJECTED | PAUSED | ENDED
• start_date : date
• end_date : date
• created_at : datetime

Donations

• donation_id : UUID
• campaign_id : UUID (FK → Campaigns)
• donor_user_id : UUID (FK → Users)
• amount : decimal
• payment_ref : string
• status : PENDING | PAID | FAILED | REFUNDED
• created_at : datetime

ModerationRecords

• moderation_id : UUID
• campaign_id : UUID (FK → Campaigns)
• admin_user_id : UUID (FK → Users)
• reason : text
• action : APPROVE | REJECT
• created_at : datetime

---

Statuses and Rules

Organization Status

• PENDING
• APPROVED
• SUSPENDED

Campaign Status

• DRAFT
• PENDING
• APPROVED
• REJECTED
• PAUSED
• ENDED

Donation Status

• PENDING
• PAID
• FAILED
• REFUNDED

Moderation Action

• APPROVE
• REJECT

---

API (Draft Structure)

This is a high-level API outline based on the architecture and diagrams. Final routes may differ.

Authentication

• POST /auth/register – Register a new user
• POST /auth/login – Login and get JWT token

Register Example:

curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "name": "John Doe", "password": "secret123"}'

Login Example:

curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret123"}'

Response:

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Protected Routes

Use the JWT token in the Authorization header:

curl -X GET http://localhost:8080/me \
  -H "Authorization: Bearer <your-jwt-token>"

Campaigns

• GET /campaigns – browse campaigns (public)
• GET /campaigns/{id} – campaign details (public)
• POST /campaigns – create campaign (requires auth)
• PUT /campaigns/{id} – update campaign (requires auth, owner only)
• DELETE /campaigns/{id} – end campaign (requires auth, owner only)

Donations

• POST /donations – donate to a campaign (requires auth)
• GET /my/donations – view user's donation history (requires auth)
• GET /campaigns/{id}/donations – view campaign donations (public)

Users

• GET /users – list all users (public)
• GET /users/{id} – get user by ID (public)
• GET /me – get current user (requires auth)
• PUT /me – update current user (requires auth)
• DELETE /me – delete current user (requires auth)

---

Environment Variables

Copy .env.example to .env and configure:

Variable	Description	Default
SERVER_PORT	Port to run the server	8080
JWT_SECRET	Secret key for JWT signing	your-super-secret-key-change-in-production
JWT_EXPIRATION_HOURS	JWT token expiration in hours	24
DB_HOST	PostgreSQL host	localhost
DB_PORT	PostgreSQL port	5432
DB_USER	PostgreSQL user	postgres
DB_PASSWORD	PostgreSQL password	postgres
DB_NAME	PostgreSQL database name	crowdfunding
DB_SSLMODE	PostgreSQL SSL mode	disable

---

Prerequisites

For Local Development

• Go 1.21+
• Node.js 20+ (for frontend and fake services)
• PostgreSQL 14+

For Docker Deployment

• Docker 24+
• Docker Compose 2.20+

---

Running the Project

Option 1: Docker Deployment (Recommended for Production)

Deploy the entire stack with a single command:

# Clone the repository
git clone https://github.com/your-username/final-project.git
cd final-project

# Create environment file
cp .env.example .env
# Edit .env with secure values for production

# Start all services
docker-compose up -d --build

This starts:

• PostgreSQL database
• Go Backend API on internal port 8080
• React Frontend served via nginx
• Fake Services (payment & approval simulation) on internal port 3001
• Nginx reverse proxy on ports 80/443

Access Points

• Main Application: http://apex.maqsatto.tech (or http://localhost)
• API Endpoints: http://apex.maqsatto.tech/api/
• Fake Services: http://apex.maqsatto.tech/fake-api/

Useful Docker Commands

# View logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f backend

# Restart a service
docker-compose restart backend

# Stop all services
docker-compose down

# Stop and remove volumes (clears database)
docker-compose down -v

# Rebuild specific service
docker-compose up -d --build backend

Option 2: Local Development

1. Set up PostgreSQL database

# Create the database
psql -U postgres -c "CREATE DATABASE crowdfunding;"

2. Configure environment

# Copy example env file
cp .env.example .env

# Edit .env with your database credentials

3. Run the Go backend

go mod tidy
go run .

4. Run the frontend (separate terminal)

cd frontend
npm install
npm run dev

5. Run fake services (separate terminal)

cd internal/utils
npm install
npm start

The server will automatically run database migrations on startup.

---

Production Deployment

Server Setup (apex.maqsatto.tech)

1. SSH into server

ssh root@164.92.192.185

2. Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

3. Clone and deploy

git clone https://github.com/your-username/final-project.git
cd final-project
cp .env.example .env
nano .env  # Configure secure values
docker-compose up -d --build

SSL/HTTPS Setup (Optional)

1. Install certificates (using Let's Encrypt):

mkdir -p nginx/ssl
certbot certonly --standalone -d apex.maqsatto.tech
cp /etc/letsencrypt/live/apex.maqsatto.tech/fullchain.pem nginx/ssl/
cp /etc/letsencrypt/live/apex.maqsatto.tech/privkey.pem nginx/ssl/

2. Uncomment HTTPS configuration in nginx/nginx.conf

3. Restart nginx:

docker-compose restart nginx

---

Project Structure

├── Dockerfile                 # Go backend Docker build
├── docker-compose.yml         # Multi-service orchestration
├── main.go                    # Application entry point
├── frontend/
│   ├── Dockerfile             # Frontend Docker build
│   ├── nginx.conf             # Frontend nginx config
│   └── src/                   # React application
├── internal/
│   ├── config/                # Configuration management
│   ├── database/              # Database connection
│   ├── domain/                # Domain entities
│   ├── http/                  # HTTP layer (handlers, middleware, router)
│   ├── repository/            # Data access layer
│   ├── service/               # Business logic
│   ├── utils/                 # Fake payment/approval services
│   │   ├── Dockerfile
│   │   ├── server.js
│   │   ├── paymentService.js
│   │   └── approvalService.js
│   └── worker/                # Background workers
├── nginx/
│   └── nginx.conf             # Reverse proxy configuration
└── docs/                      # Documentation

---

Diagrams

All diagrams and design documents are located in the /docs directory:

• Use-Case Diagram – user roles and system interactions
• ERD (Entity-Relationship Diagram) – database structure and relations
• UML / Architecture Diagram – layered architecture (API, services, repositories, database)
• Project Proposal – system description, requirements, and milestones