NGO Platform

Multi-tenant SaaS platform for NGO management

Academic project for Bialystok University of Technology (2025/2026)

Overview

Modern platform for NGO organizations to manage volunteers, events, and operations with web and mobile interfaces. Built with .NET Aspire orchestration for simplified development and deployment.

Features

• 🏢 Multi-Tenant Architecture - Multiple NGOs on single platform
• 👥 Role-Based Access - SuperAdmin, TenantAdmin, and Volunteer roles
• 📅 Event Management - Create, manage, and track volunteer events
• 📱 Multi-NGO Mobile Apps - Build separate branded apps per NGO
• 🎨 Custom Branding - Each NGO has unique colors, name, and configuration
• 🔐 JWT Authentication - Secure token-based auth with refresh tokens
• 🎯 Clean Architecture - CQRS + DDD patterns in backend
• 🚀 .NET Aspire - Service orchestration with built-in observability

Quick Start

Prerequisites

• .NET 10 SDK
• Node.js 22+
• Yarn 4 (enable: corepack enable)
• Azure CLI (install and login: az login)
• Docker Desktop

Start Development Environment

1. Login to Azure:

az login --use-device-code

2. Configure mobile platform (optional):

Edit Infrastructure/NGOPlatform.AppHost/appsettings.Development.json:

{
  "ASPIRE_MOBILE_PLATFORM": "no-mobile"  // "no-mobile", "ios", or "android"
}

3. Start everything with Aspire:

cd Infrastructure
dotnet run --project NGOPlatform.AppHost

This starts everything:

• All backend APIs (SuperAdmin, TenantAdmin, Volunteer, Shared)
• Frontend web apps (SuperAdmin, TenantAdmin)
• Mobile app (iOS/Android if configured)
• Mailpit container
• Aspire Dashboard

URLs:

• Aspire Dashboard: http://localhost:15000 (monitoring, logs, metrics)
• SuperAdmin Web: http://localhost:5174
• TenantAdmin Web: http://localhost:5173
• Mailpit (Email Testing): http://localhost:8025

📖 Full setup guide: Docs/SETUP.md

Technology Stack

Backend

• .NET 10 with C# 14
• .NET Aspire - Service orchestration, monitoring, telemetry
• Azure SQL Database - Active Directory authentication
• EF Core 10 - Entities only, manual T-SQL migrations
• MediatR - CQRS pattern implementation
• JWT - Authentication with refresh tokens
• AutoMapper - Object mapping
• FluentValidation - Input validation

Frontend

• React 19 - Web applications
• React Native 0.76 - Mobile application
• TypeScript 5.9 - Type safety
• Vite 7 - Build tool and dev server
• Expo SDK 52 - React Native tooling
• Yarn v4 - Workspace monorepo management

Infrastructure

• .NET Aspire - Dashboard, service discovery, health checks
• Docker - Mailpit container for email testing
• Azure - SQL Database, App Service hosting
• GitHub Actions - CI/CD pipelines

Project Structure

NGO-Platform/
├── Infrastructure/                      # .NET solution
│   ├── NGOPlatform.AppHost/          # 🆕 Aspire orchestrator
│   ├── NGOPlatform.ServiceDefaults/  # 🆕 Aspire shared config
│   ├── NGOPlatform.Shared/           # Shared domain (auth, users, roles)
│   │   ├── Shared.Api/               # Common API utilities
│   │   ├── Shared.Application/       # CQRS commands/queries
│   │   ├── Shared.Domain/            # Domain entities
│   │   ├── Shared.Infrastructure/    # EF Core, repositories
│   │   └── Shared.Kernel/            # Exceptions, base classes
│   ├── NGOPlatform.SuperAdmin/       # Platform administration
│   │   ├── SuperAdmin.Api/
│   │   ├── SuperAdmin.Application/
│   │   ├── SuperAdmin.Domain/
│   │   └── SuperAdmin.Infrastructure/
│   ├── NGOPlatform.TenantAdmin/      # Tenant management
│   └── NGOPlatform.Volunteer/        # Volunteer operations
│
├── Frontend/                          # Yarn v4 monorepo
│   ├── apps/
│   │   ├── superadmin/               # React + Vite (port 5174)
│   │   ├── tenantadmin/              # React + Vite (port 5173)
│   │   └── volunteer/                # React Native + Expo
│   └── packages/shared/              # Shared code
│       ├── src/
│       │   ├── components/           # UI components
│       │   ├── hooks/                # React hooks
│       │   ├── contexts/             # React contexts
│       │   ├── config/               # Configuration
│       │   ├── types/                # TypeScript types
│       │   └── utils/                # Utilities
│
├── DevelopmentScripts/                # Utility scripts
│   ├── generate-diagrams.ps1         # PlantUML → PNG/SVG
│   └── run-database-scripts.ps1      # Manual DB migrations
│
└── Docs/                              # Documentation
    ├── SETUP.md                       # Quick start guide
    ├── diagrams/                      # PlantUML diagrams
    └── confluence/                    # Living documentation

Development Tools

.NET Aspire Dashboard

URL: http://localhost:15000

Features:

• Live logs from all services
• Resource health monitoring
• Distributed tracing (OpenTelemetry)
• Metrics and telemetry
• Environment configuration
• Service dependencies visualization

Mailpit (Email Testing)

URL: http://localhost:8025

• Captures all outgoing emails
• SMTP server at localhost:1025
• No real emails sent
• Web UI for viewing emails

Documentation

• 📘 Quick Setup Guide
• 🏗️ Architecture Overview
• 💻 Backend Guide
• 🎨 Frontend Guide
• 🔧 Infrastructure
• 🛠️ Development Guide
• 📊 Data Model
• 📝 Logging Best Practices
• ✅ Code Quality Checklist
• 👥 Team & Roles

Contributing

→ See CONTRIBUTING.md for complete guide

Quick links:

• Development workflow and branch naming
• Code standards and best practices
• Testing requirements
• PR process and checklist
• Documentation guidelines

Development Workflow

• Main Branch: develop (integration and active development)
• Production: main (production-ready releases)
• Features: feature/PT2025BMHW-XXX-description
• Bugfixes: bugfix/PT2025BMHW-XXX-description

Team

• Marcin Kondrat - Full-Stack & DevOps
• Mateusz - Full-Stack & Database
• Jowita - Frontend & UX
• Kacper - Backend & QA

See TEAM.md for detailed roles and responsibilities.

License

Academic project - Bialystok University of Technology (BUT)

Contact

Repository: https://github.com/breftejk/NGO-Platform