• Project Overview
• Live Demo
• Key Features
• Screenshots
• Architecture & Technology Stack
• Installation & Setup
• GitHub Pages Deployment
• Usage Instructions
• API Documentation
• Contributing
• License
• Credits

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.

🌐 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.

Previously, Ghanaian students faced:

• Repetitive application processes across multiple universities
• Fragmented scholarship and financial aid information
• Lack of standardized application tracking
• Complex document submission requirements
• Limited transparency in admissions processes

UniBridge provides:

• Unified Application Process: One application for 100+ tertiary institutions
• Integrated Financial Aid: Comprehensive scholarship database and application tracking
• Real-time Progress Monitoring: Live updates on application status and deadlines
• Secure Document Management: Encrypted storage and streamlined document submission
• Direct Admissions Workflow: Streamlined process for qualified candidates

• Smart Application Form: Dynamic forms that adapt to institution requirements
• University Discovery: Advanced search and filtering by programs, location, and requirements
• Essay Management: Built-in writing tools with auto-save and version control
• Payment Integration: Multiple payment options including Mobile Money and bank transfers
• Notification System: Real-time alerts for deadlines, updates, and decisions
• Analytics Dashboard: Personal insights on application progress and success rates

• Admin Portal: Comprehensive application review and management system
• Custom Requirements: Institution-specific supplements and requirements
• Bulk Processing: Efficient tools for handling large volumes of applications
• Analytics & Reporting: Detailed insights on applicant demographics and trends
• Secure Communication: Direct messaging system with applicants

• High Performance: Sub-second page load times with optimized caching
• Scalability: Microservices architecture supporting concurrent users
• Security: Enterprise-grade encryption and data protection
• Accessibility: WCAG 2.1 AA compliant for inclusive access
• Offline Support: Progressive Web App capabilities for limited connectivity areas

Landing page and student dashboard interface

Application tracking and streamlined admissions workflow

Financial aid discovery and comprehensive university analytics

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

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

├── 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)

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

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

-- 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)

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.

• Static Site Generation: Optimized Next.js build for static hosting
• Mock Data: Realistic sample data for universities, applications, and scholarships
• Demo Authentication: Bypassed authentication for easy testing
• Responsive Design: Full mobile and desktop compatibility
• Automated Deployment: GitHub Actions workflow for seamless updates

For testing the GitHub Pages version:

• Email: Any valid email format (e.g., demo@example.com)
• Password: Any password
• Authentication is bypassed for demonstration purposes

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

• Node.js (v18.0 or higher)
• Python (v3.11 or higher)
• PostgreSQL (v14 or higher)
• Redis (v6.0 or higher)
• Docker (optional, for containerized setup)
• Git (for version control)

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

# 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

# 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

# Create PostgreSQL database
createdb unibridge_ghana

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

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 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"

# 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

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
   

// 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",
};

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
   

// 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();
  },
};

# 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"

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

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

• Frontend Development: React/Next.js components and features
• Backend Development: FastAPI endpoints and database models
• UI/UX Design: Interface improvements and user experience
• Documentation: Technical documentation and user guides
• Testing: Unit tests, integration tests, and E2E tests
• DevOps: Infrastructure and deployment improvements

When reporting issues, please include:

• Environment: OS, browser, version
• Steps to Reproduce: Detailed reproduction steps
• Expected Behavior: What should happen
• Actual Behavior: What actually happens
• Screenshots: Visual evidence if applicable

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

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.

• Open Source: Free to use, modify, and distribute under MIT License terms
• Commercial Use: Permitted without restrictions
• Educational Use: Encouraged for learning and academic purposes
• Attribution: Copyright notice and license terms must be included in redistributions
• No Warranty: Provided "AS IS" without warranty of any kind

• Perfect for Learning: Ideal for students and developers learning modern web development
• Portfolio Showcase: Demonstrates full-stack development capabilities
• Educational Priority: Special focus on African educational technology solutions
• Open Development: All code is open source and available for study

MIT License

Copyright (c) 2025 Tyrone Marhguy

Academic and portfolio project - not intended for production deployment.

• Lead Developer: Tyrone Marhguy
• Contributors: See CONTRIBUTORS.md for full list

• Ghana Education Service: For guidance on educational requirements
• University Partners: Public and private institutions across Ghana
• Open Source Community: For the amazing tools and libraries
• Beta Testers: Students and educators who provided invaluable feedback

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

• WASSCE Integration: Direct support for West African Secondary School Certificate Examination
• Local Payment Systems: Mobile Money, GCB, and other local banking integrations
• Regional Coverage: Support for universities across all 10 regions of Ghana
• Cultural Sensitivity: Interface and processes designed for Ghanaian users
• Accessibility: Support for multiple languages and varying internet connectivity

UniBridge Ghana - Connecting Students to Their Future

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