MKiba - Financial Services Platform

A comprehensive financial services platform built with FastAPI backend and Next.js frontend, featuring integrated monitoring and observability.

👨‍💻 Author

Amoni Kevin - GitHub

🏗️ Tech Stack

Backend

• FastAPI - Modern Python web framework
• SQLAlchemy - Database ORM
• Alembic - Database migrations
• Pydantic - Data validation
• Prometheus - Metrics collection
• SQLite/PostgreSQL - Database

Frontend

• Next.js 14 - React framework
• TypeScript - Type safety
• Tailwind CSS - Styling
• React Hook Form - Form management

Monitoring & Observability

• Prometheus - Metrics collection and storage
• Grafana - Visualization and dashboards
• Docker - Containerization for monitoring services

🚀 Quick Start

Prerequisites

• Python 3.8+
• Node.js 18+
• Docker (optional, for monitoring services)

Development Setup

1. Clone the repository

   git clone <repository-url>
   cd Mkiba

2. Start the complete development environment

   # Windows
   start-development.bat
   
   # This will automatically:
   # - Check system requirements
   # - Start monitoring services (if Docker is available)
   # - Launch backend server (FastAPI)
   # - Launch frontend server (Next.js)

3. Access the services

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/api/docs
   • Metrics Endpoint: http://localhost:8000/metrics
   • Prometheus: http://localhost:9090 (if Docker available)
   • Grafana: http://localhost:3001 (admin/admin, if Docker available)

Manual Setup

If you prefer manual setup or need to troubleshoot:

Backend Setup

cd mkiba-backend

# Create virtual environment
python -m venv venv
venv\Scripts\activate  # Windows
# source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements/dev.txt

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Run migrations
alembic upgrade head

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

Frontend Setup

cd mkiba-frontend

# Install dependencies
npm install

# Setup environment
cp .env.example .env.local
# Edit .env.local with your configuration

# Start development server
npm run dev

Monitoring Setup (Optional)

cd monitoring

# Start monitoring stack
docker-compose -f docker-compose.monitoring.yml up -d

# Or use the convenience script
start-monitoring.bat

📊 Monitoring & Observability

The platform includes comprehensive monitoring capabilities:

Available Metrics

• HTTP Request Metrics: Request count, duration, status codes
• Application Metrics: Active requests, response times
• System Metrics: Memory usage, CPU utilization
• Business Metrics: Transaction counts, user activities

Grafana Dashboards

• MKiba Overview: Main application dashboard
• HTTP Request Rate: Request volume and patterns
• Response Time Percentiles: Performance analysis
• Error Rate Monitoring: Error tracking and alerting
• Service Health: Overall system status

Alerts

Pre-configured alerts for:

• Backend service downtime
• High response times (>2s)
• Error rates above 5%
• High system resource usage

🧪 Testing

Backend Tests

cd mkiba-backend
pytest tests/ -v

Frontend Tests

cd mkiba-frontend
npm test
npm run test:e2e

🔧 Configuration

Environment Variables

Backend (.env)

DATABASE_URL=sqlite:///./mkiba_dev.db
SECRET_KEY=your-secret-key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
ENVIRONMENT=development

Frontend (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_APP_NAME=MKiba

Monitoring Configuration

• Prometheus: monitoring/prometheus/prometheus.yml
• Grafana: monitoring/grafana/
• Alerts: monitoring/prometheus/alert_rules.yml

📁 Project Structure

Mkiba/
├── mkiba-backend/          # FastAPI backend
│   ├── app/
│   │   ├── api/            # API routes
│   │   ├── core/           # Core functionality
│   │   ├── models/         # Database models
│   │   ├── schemas/        # Pydantic schemas
│   │   └── services/       # Business logic
│   ├── tests/              # Backend tests
│   └── requirements/       # Python dependencies
├── mkiba-frontend/         # Next.js frontend
│   ├── src/
│   │   ├── app/            # App router pages
│   │   ├── components/     # React components
│   │   └── lib/            # Utilities
│   └── tests/              # Frontend tests
├── monitoring/             # Monitoring stack
│   ├── prometheus/         # Prometheus config
│   ├── grafana/            # Grafana dashboards
│   └── docker-compose.monitoring.yml
├── start-development.bat   # Development startup script
└── stop-development.bat    # Development shutdown script

🚢 Deployment

Production Deployment

1. Backend Deployment

   cd mkiba-backend
   docker build -t mkiba-backend .
   docker run -p 8000:8000 mkiba-backend

2. Frontend Deployment

   cd mkiba-frontend
   npm run build
   npm start

3. Monitoring Deployment

   cd monitoring
   docker-compose -f docker-compose.monitoring.yml up -d

Environment-Specific Configurations

• Development: Local SQLite, hot reload enabled
• Staging: PostgreSQL, reduced logging
• Production: PostgreSQL, optimized settings, SSL enabled

🛠️ Development Workflow

1. Start Development Environment

   start-development.bat

2. Make Changes

   • Backend changes auto-reload with --reload flag
   • Frontend changes auto-reload with Next.js hot reload

3. Monitor Changes

   • Check metrics at http://localhost:8000/metrics
   • View dashboards at http://localhost:3001

4. Run Tests

   # Backend
   cd mkiba-backend && pytest
   
   # Frontend
   cd mkiba-frontend && npm test

5. Stop Development Environment

   stop-development.bat

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Update documentation as needed
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Code Style

• Backend: Follow PEP 8, use Black formatter
• Frontend: Follow ESLint rules, use Prettier formatter
• Commits: Use conventional commit messages

📄 License

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

🆘 Troubleshooting

Common Issues

1. Port Already in Use

   # Kill processes on ports 3000, 8000
   stop-development.bat

2. Docker Not Running

   • Start Docker Desktop
   • Monitoring services will be disabled if Docker unavailable

3. Database Issues

   cd mkiba-backend
   alembic upgrade head

4. Node Modules Issues

   cd mkiba-frontend
   rm -rf node_modules package-lock.json
   npm install

Getting Help

• Check the API Documentation
• Review Monitoring Documentation
• Open an issue for bugs or feature requests

📈 Performance Monitoring

The platform includes built-in performance monitoring:

• Response Time Tracking: P50, P95, P99 percentiles
• Error Rate Monitoring: 4xx and 5xx error tracking
• Resource Usage: Memory and CPU monitoring
• Custom Business Metrics: Transaction volumes, user engagement

Access real-time dashboards at http://localhost:3001 when monitoring services are running.