sGHS - Stable Ghana Cedis Platform

A comprehensive digital financial platform for the Stable Ghana Cedis (sGHS) ecosystem, providing both administrative and client-facing applications with full-stack implementations.

The sGHS platform is a Ghana Cedi-pegged, fiat-collateralized token designed to enable fast, low-cost, and programmable GHS-denominated payments for individuals and businesses across Ghana and the Ghanaian diaspora.

sGHS Whitepaper: Each token is backed 1:1 by segregated Ghana cedi reserves held in regulated financial institutions and subject to regular third-party attestations and transparent reserve reporting.

Tip

This platform provides a complete ecosystem for sGHS operations, from administrative oversight to end-user financial services, all built with modern technologies and Ghana-specific integrations.

🏗️ Project Architecture

The sGHS platform is structured as a monorepo containing multiple applications and services:

sGHS/
├── admin/                    # Administrative platform
│   ├── backend/             # NestJS API server
│   └── frontend/            # Next.js admin dashboard
├── client/                   # Client-facing platform
│   ├── backend/             # NestJS API server
│   └── frontend/            # Next.js client application
├── shared/                   # Shared utilities and types
├── docs/                     # Documentation
└── infrastructure/           # Deployment and DevOps

🎯 Platform Components

🔧 Admin Platform

Purpose: Platform management, compliance monitoring, and operational oversight

Admin Backend (admin/backend/)

• Framework: NestJS with TypeScript
• Database: PostgreSQL with Prisma ORM
• Authentication: JWT with role-based access control
• Features:
  • User management and KYC/AML processing
  • Transaction monitoring and compliance reporting
  • Reserve management and audit trails
  • Multi-signature governance workflows
  • Real-time notifications and alerts

Admin Frontend (admin/frontend/)

• Framework: Next.js 15 with TypeScript
• UI: Shadcn UI components with Tailwind CSS
• Features:
  • Real-time dashboard with platform metrics
  • Transaction monitoring and compliance tools
  • User management and role assignment
  • Reserve breakdown and audit reporting
  • Multi-signature approval workflows

👥 Client Platform

Purpose: End-user financial services and sGHS wallet management

Client Backend (client/backend/)

• Framework: NestJS with TypeScript
• Database: PostgreSQL with Prisma ORM
• Blockchain: Ethereum integration for sGHS token operations
• Features:
  • sGHS wallet management
  • Transaction processing (send/receive/deposit/withdraw)
  • Ghana banking integration (Bank of Ghana, GCB, Ecobank, etc.)
  • Mobile money integration (MTN, Vodafone, AirtelTigo)
  • KYC/AML compliance and transaction monitoring

Client Frontend (client/frontend/)

• Framework: Next.js 15 with TypeScript
• UI: Shadcn UI components with Ghana-themed presets
• Features:
  • sGHS digital wallet with real-time balance
  • Send/Receive/Deposit/Withdraw functionality
  • QR code generation and wallet address sharing
  • Transaction history and receipt management
  • Ghana banking and mobile money integration

🛠️ Tech Stack

Backend Technologies

• Framework: NestJS (Node.js)
• Language: TypeScript
• Database: PostgreSQL
• ORM: Prisma
• Authentication: JWT with RBAC
• Blockchain: Ethereum (Web3.js/Ethers.js)
• API: RESTful APIs with OpenAPI documentation
• Testing: Jest with comprehensive test coverage
• Validation: Class-validator and class-transformer

Frontend Technologies

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4
• Components: Shadcn UI
• State Management: Zustand
• Forms: React Hook Form with Zod validation
• Charts: Recharts
• Icons: Lucide React, Simple Icons
• Runtime: Bun (recommended) or Node.js

DevOps & Infrastructure

• Containerization: Docker
• Orchestration: Docker Compose
• CI/CD: GitHub Actions
• Monitoring: Application performance monitoring
• Security: Automated security scanning
• Deployment: Vercel (frontend), Railway/Heroku (backend)

🚀 Getting Started

Prerequisites

• Bun (recommended): curl -fsSL https://bun.sh/install | bash
• Node.js (alternative): Version 18+
• PostgreSQL: Version 14+
• Git: For cloning the repository

Quick Start

1. Clone the repository

   git clone https://github.com/Moneterea-Org/sGHS.git
   cd sGHS

2. Install dependencies for all platforms

   # Install admin dependencies
   cd admin/frontend && bun install
   cd ../backend && bun install
   
   # Install client dependencies
   cd ../../client/frontend && bun install
   cd ../backend && bun install

3. Set up environment variables

   # Copy example environment files
   cp admin/backend/.env.example admin/backend/.env
   cp client/backend/.env.example client/backend/.env

4. Start the development servers

   # Start admin platform
   cd admin/backend && bun run start:dev &
   cd ../frontend && bun dev &
   
   # Start client platform
   cd ../../client/backend && bun run start:dev &
   cd ../frontend && bun dev &

Individual Platform Setup

Admin Platform

cd admin/frontend
bun install
bun dev
# Admin dashboard: http://localhost:3000

cd ../backend
bun install
bun run start:dev
# Admin API: http://localhost:3001

Client Platform

cd client/frontend
bun install
bun dev
# Client app: http://localhost:3002

cd ../backend
bun install
bun run start:dev
# Client API: http://localhost:3003

📊 Platform Features

Admin Platform Features

• Dashboard: Real-time platform metrics and compliance monitoring
• User Management: KYC/AML processing and user verification
• Transaction Monitoring: Real-time transaction screening and reporting
• Reserve Management: 1:1 backing verification and reserve tracking
• Compliance Center: Regulatory reporting and audit management
• Multi-signature Governance: Secure approval workflows for critical operations

Client Platform Features

• sGHS Wallet: Digital wallet with blockchain integration
• Send sGHS: Peer-to-peer transfers with memo support
• Receive sGHS: QR code generation and address sharing
• Deposit Funds: Convert Ghana Cedis to sGHS via multiple channels
• Withdraw Funds: Convert sGHS back to Ghana Cedis
• Transaction History: Complete transaction tracking and filtering
• Banking Integration: Seamless integration with Ghanaian financial institutions

🏦 Ghana Financial Integration

Traditional Banks

• Bank of Ghana
• GCB Bank
• Ecobank Ghana
• Stanbic Bank Ghana
• Fidelity Bank Ghana
• Access Bank Ghana
• Standard Chartered Bank Ghana
• Zenith Bank Ghana

Mobile Money Providers

• MTN Mobile Money
• Vodafone Cash
• AirtelTigo Money

Cash Services

• Physical locations across all 16 regions of Ghana
• Partner locations in major cities and towns
• 24/7 availability at select locations

🔐 Security & Compliance

Regulatory Compliance

• Bank of Ghana (BoG): Full compliance with Ghanaian banking regulations
• AML/KYC: Anti-money laundering and know-your-customer procedures
• FATF Standards: International compliance with Financial Action Task Force guidelines
• Audit Trails: Complete transaction and operational logging
• Multi-signature Governance: Secure approval workflows for critical operations

Security Features

• 1:1 Reserve Backing: All sGHS tokens backed by Ghana Cedi reserves
• Blockchain Security: Ethereum network integration with smart contract security
• Data Protection: GDPR-compliant data handling and privacy protection
• Transaction Monitoring: Real-time screening for suspicious activities
• Access Control: Role-based access control with granular permissions

🧪 Development

Available Scripts

Backend (NestJS)

• bun run start - Start production server
• bun run start:dev - Start development server with hot reload
• bun run start:debug - Start with debugging enabled
• bun run build - Build for production
• bun run test - Run unit tests
• bun run test:e2e - Run end-to-end tests
• bun run test:cov - Run tests with coverage

Frontend (Next.js)

• bun dev - Start development server
• bun build - Build for production
• bun start - Start production server
• bun test - Run tests
• bun run lint - Run ESLint
• bun run format - Format code with Prettier

Testing

• Unit Tests: Comprehensive test coverage for all components
• Integration Tests: API endpoint testing
• E2E Tests: Full user journey testing
• Security Tests: Automated security vulnerability scanning

📈 Monitoring & Analytics

Admin Monitoring

• Platform performance metrics
• User activity and growth analytics
• Transaction volume and compliance metrics
• Reserve composition and backing verification
• System health and error monitoring

Client Analytics

• User spending patterns and insights
• Transaction frequency and amounts
• Geographic distribution of users
• Mobile money vs bank transfer preferences
• Platform usage statistics

🤝 Contributing

The sGHS platform is actively developed to support Ghana's digital economy. Contributions are welcome for:

• Backend Development: API enhancements, blockchain integration, security improvements
• Frontend Development: UI/UX improvements, new features, accessibility enhancements
• DevOps: Infrastructure improvements, deployment automation, monitoring
• Compliance: Regulatory updates, security enhancements, audit improvements
• Documentation: Technical documentation, user guides, API documentation

📄 License

This project is part of the sGHS platform initiative to provide Ghana with a sovereign digital currency solution.

🌍 Impact

The sGHS platform aims to:

• Promote Financial Inclusion: Bring digital financial services to underserved communities
• Reduce Remittance Costs: Enable low-cost cross-border payments for the Ghanaian diaspora
• Support Local Economy: Encourage transactions in Ghana Cedis rather than foreign currencies
• Enable Innovation: Provide a programmable currency for developers and entrepreneurs
• Ensure Sovereignty: Maintain Ghana's monetary sovereignty in the digital age

---

Building Ghana's Digital Future with sGHS! 🇬🇭

Empowering individuals, businesses, and developers with a stable, programmable, and compliant digital representation of the Ghana Cedi.