unibridgeGhana

UniBridge Ghana Logo
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Frontend](https://img.shields.io/badge/Frontend-Next.js%2014-black)](https://nextjs.org/) [![Backend](https://img.shields.io/badge/Backend-FastAPI-009688)](https://fastapi.tiangolo.com/) [![Database](https://img.shields.io/badge/Database-PostgreSQL-336791)](https://postgresql.org/) [![Deployment](https://img.shields.io/badge/Deployment-Docker-2496ED)](https://docker.com/)

Ghana's first centralized university admissions platform, revolutionizing how students apply to tertiary institutions across the country.

UniBridge provides a streamlined, one-application solution for 100+ universities, integrated scholarship search, and comprehensive progress tracking.

Table of Contents

Project Overview

UniBridge Ghana eliminates the traditional barriers of university applications by providing a centralized platform where students complete one comprehensive application and apply to multiple institutions simultaneously. The platform serves as Ghana’s equivalent to the Common Application used in the United States, specifically designed for the Ghanaian educational ecosystem.

Live Demo

🌐 Try the live demo: https://tmarhguy.github.io/unibridgeGhana/

The GitHub Pages version showcases the complete user interface with mock data, demonstrating the platform’s potential for revolutionizing university admissions in Ghana.

Problem Statement

Previously, Ghanaian students faced:

Solution

UniBridge provides:

Key Features

Core Functionality

Feature Description Status
Centralized Applications Single application form for multiple universities ✅ Complete
Multi-Institution Support Support for 100+ public and private universities ✅ Complete
Direct Admissions Fast-track admissions for qualified candidates ✅ Complete
Scholarship Integration Comprehensive financial aid search and application ✅ Complete
Progress Tracking Real-time application status and deadline monitoring ✅ Complete
Document Security End-to-end encryption for sensitive documents ✅ Complete
Auto-save Functionality Automatic form data preservation ✅ Complete
Mobile Responsive Full functionality across all devices ✅ Complete

Student Features

University Features

Technical Features

Screenshots

Core Platform Overview

UniBridge Ghana landing page with call-to-action button and feature highlights Student dashboard showing application progress and university recommendations

Landing page and student dashboard interface

Application Management & Direct Admissions

Application progress tracker with timeline and status indicators Fast-track admissions interface for qualified candidates

Application tracking and streamlined admissions workflow

Financial Aid & Analytics Platform

Scholarship search interface with filtering and application tracking University analytics dashboard with institutional data and trends

Financial aid discovery and comprehensive university analytics

📷 Visual Documentation: For additional screenshots, mobile views, and admin interfaces, see docs/screenshots/

Architecture & Technology Stack

System Architecture

graph TD
    A[Students & Universities] --> B[Next.js Frontend]
    B --> C[API Gateway]
    C --> D[FastAPI Backend]
    D --> E[(PostgreSQL Database)]
    D --> F[(Redis Cache)]
    D --> G[(MinIO Storage)]
    D --> H[Celery Workers]

    I[Admin Portal] --> B
    J[Mobile App] --> C

    K[Payment Gateways] --> D
    L[WASSCE API] --> D
    M[Email Service] --> H

    style B fill:#0066cc,color:#fff
    style D fill:#009688,color:#fff
    style E fill:#336791,color:#fff
    style F fill:#dc382d,color:#fff
    style G fill:#c72e29,color:#fff

Frontend Architecture

├── Next.js 14 (App Router)
├── TypeScript (Type Safety)
├── Tailwind CSS (Styling)
├── React Query (State Management)
├── React Hook Form + Zod (Form Validation)
├── Radix UI (Accessible Components)
└── PWA Support (Offline Capability)

Backend Architecture

├── FastAPI (Python Web Framework)
├── SQLAlchemy (ORM)
├── PostgreSQL (Primary Database)
├── Redis (Caching & Sessions)
├── MinIO (Document Storage)
├── Alembic (Database Migrations)
├── Pydantic (Data Validation)
└── Celery (Background Tasks)

Infrastructure & DevOps

├── Docker (Containerization)
├── Kubernetes (Orchestration)
├── GitHub Actions (CI/CD)
├── Nginx (Load Balancing)
├── Let's Encrypt (SSL Certificates)
└── Prometheus + Grafana (Monitoring)

Database Schema

-- Core Tables
├── users (students, admins, university staff)
├── universities (institution profiles and requirements)
├── applications (application submissions and status)
├── documents (secure file storage references)
├── scholarships (financial aid opportunities)
├── notifications (real-time messaging system)
└── audit_logs (comprehensive activity tracking)

GitHub Pages Deployment

This project includes a GitHub Pages deployment configuration for showcasing the frontend interface. The static version is automatically deployed to https://tmarhguy.github.io/unibridgeGhana/ whenever changes are pushed to the main branch.

Features of the GitHub Pages Version

Demo Credentials

For testing the GitHub Pages version:

Installation & Setup

Prerequisites

Before setting up UniBridge Ghana locally, ensure you have the following installed:

Local Development Setup

1. Clone the Repository

git clone https://github.com/tmarhguy/unibridgeGhana.git
cd unibridgeGhana

2. Backend Setup

# Navigate to backend directory
cd backend

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your database and Redis configurations

# Run database migrations
alembic upgrade head

# Start the backend server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

3. Frontend Setup

# Navigate to frontend directory (new terminal)
cd frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your API endpoints

# Start the development server
npm run dev

4. Database Setup

# Create PostgreSQL database
createdb unibridge_ghana

# Set up Redis (if not using Docker)
redis-server

Docker Setup (Alternative)

For a containerized setup:

# Clone and navigate to project
git clone https://github.com/tmarhguy/unibridgeGhana.git
cd unibridgeGhana

# Build and run with Docker Compose
docker-compose up --build

# Run database migrations
docker-compose exec backend alembic upgrade head

Production Deployment

Environment Configuration

# Production environment variables
export DATABASE_URL="postgresql://user:password@localhost:5432/unibridge_prod"
export REDIS_URL="redis://localhost:6379"
export SECRET_KEY="your-production-secret-key"
export ENVIRONMENT="production"

Build and Deploy

# Frontend build
cd frontend
npm run build
npm start

# Backend deployment
cd backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Usage Instructions

For Students

Getting Started

  1. Account Creation

    Navigate to /register
→ Complete profile setup
→ Verify email address
→ Access dashboard

  2. Application Process

    Dashboard → Start New Application
→ Complete Common Application sections:
  - Personal Information
  - Academic History (WASSCE/A-Level results)
  - Extracurricular Activities
  - Essays and Personal Statements
→ Select target universities
→ Submit application and payment

  3. Progress Tracking

    Dashboard → My Applications
→ View real-time status updates
→ Track deadlines and requirements
→ Receive notifications for updates

Example Application Flow

// Typical student workflow
const applicationFlow = {
  1: "Create account and verify email",
  2: "Complete personal information section",
  3: "Upload academic documents (WASSCE, transcripts)",
  4: "Write essays and personal statements",
  5: "Research and select target universities",
  6: "Review application and submit",
  7: "Pay application fees via Mobile Money/Bank",
  8: "Track application status in real-time",
  9: "Receive admission decisions",
  10: "Accept offers and complete enrollment",
};

For Universities

Administrative Access

  1. Institution Setup

    Admin Portal → Institution Settings
→ Configure admission requirements
→ Set up custom application supplements
→ Define evaluation criteria

  2. Application Review

    Admin Portal → Applications
→ Filter and sort applications
→ Review individual submissions
→ Make admission decisions
→ Send notifications to students

API Integration Example

// Example API usage for external integrations
const api = {
  baseURL: "https://api.unibridge.gh/v1",

  // Get university list
  async getUniversities() {
    const response = await fetch(`${this.baseURL}/universities`);
    return response.json();
  },

  // Submit application
  async submitApplication(data) {
    const response = await fetch(`${this.baseURL}/applications`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    return response.json();
  },
};

API Documentation

Core Endpoints

Method Endpoint Description Authentication
GET /api/v1/universities List all universities Public
POST /api/v1/applications Submit new application Required
GET /api/v1/applications/{id} Get application details Required
GET /api/v1/scholarships List available scholarships Public
POST /api/v1/documents Upload documents Required

Authentication

# Get access token
curl -X POST "https://api.unibridge.gh/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# Use token in requests
curl -H "Authorization: Bearer <token>" \
  "https://api.unibridge.gh/v1/applications"

Contributing

We welcome contributions from the community. Please follow these guidelines:

Development Process

  1. Fork the Repository

    git clone https://github.com/YOUR_USERNAME/unibridgeGhana.git
cd unibridgeGhana
git remote add upstream https://github.com/tmarhguy/unibridgeGhana.git

  2. Create Feature Branch

    git checkout -b feature/your-feature-name

  3. Development Standards

    • Follow TypeScript/Python type hints
    • Write comprehensive tests
    • Update documentation
    • Follow conventional commit messages

  4. Code Style

    # Frontend linting
npm run lint
npm run format

# Backend formatting
black app/
isort app/
flake8 app/

  5. Testing

    # Frontend tests
npm run test
npm run test:e2e

# Backend tests
pytest tests/ -v

  6. Submit Pull Request

    • Provide clear description
    • Reference related issues
    • Include screenshots for UI changes
    • Ensure all checks pass

Contribution Areas

Issue Reporting

When reporting issues, please include:

License

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

Project Status

Academic & Portfolio Project: This project was created for academic and portfolio purposes. While fully functional, it is not intended for production or official deployment without further review and development.

License Summary

Key Points

MIT License

Copyright (c) 2025 Tyrone Marhguy

Academic and portfolio project - not intended for production deployment.

Credits

Development Team

Acknowledgments

Built For Ghana’s Educational Ecosystem

UniBridge Ghana is designed specifically for the Ghanaian educational landscape, incorporating:

UniBridge Ghana - Connecting Students to Their Future

For support, contact us at support@unibridge.gh or visit our documentation.

This site is open source. Improve this page.