Skip to content

RUNNING_GUIDE.md

Latest commit

 

History

History
222 lines (166 loc) · 5.57 KB

RUNNING_GUIDE.md

File metadata and controls

222 lines (166 loc) · 5.57 KB

Microfinance Platform - Running Guide

Architecture Overview

This is a monorepo-based microfinance platform with three main components:

1. Backend Server (server/)

  • Technology: Node.js + Express + TypeScript + Prisma
  • Database: PostgreSQL (Supabase)
  • Cache: Redis (Upstash)
  • Features: Authentication, Customer Management, Loan Processing, EMI Scheduling, Repayments, Document Management, Reports

2. Web Application (apps/web/)

  • Technology: React + Vite + TypeScript + Tailwind CSS
  • State Management: Zustand + React Query
  • Features: Customer Dashboard, Loan Applications, Admin Panel, Reports

3. Mobile Application (apps/mobile/)

  • Technology: React Native + Expo Router + NativeWind
  • Features: Mobile-optimized customer interface, Loan Applications, EMI Tracking

Prerequisites

Before running the application, ensure you have:

  1. Node.js (v18 or higher)
  2. npm or yarn
  3. PostgreSQL database (Supabase recommended)
  4. Redis (Upstash recommended)
  5. Cloudinary account (for file uploads)
  6. Email service (Brevo SMTP recommended)

Environment Setup

1. Database Configuration

  • Set up a PostgreSQL database (Supabase recommended)
  • Get the database connection string
  • Update server/.env with your database URL

2. External Services

  • Cloudinary: Create account and get API credentials
  • Redis: Set up Upstash Redis
  • Email: Configure Brevo SMTP

3. Environment Variables

Copy the example environment file and configure:

cp server/.env.example server/.env

Required configuration:

  • Database connection
  • JWT secrets (generate 32+ character secrets)
  • Redis configuration
  • Cloudinary credentials
  • Email SMTP settings
  • Admin credentials

Running the Application

Step 1: Install Dependencies

npm install

Step 2: Set Up Database

# Generate Prisma client
npm run db:generate -w server

# Push database schema (for development)
npm run db:push -w server

# Or run migrations (for production)
npm run db:migrate -w server

Step 3: Start Backend Server

# Start server in development mode
npm run dev:server

# Server will run on http://localhost:5000
# API base path: /api/v1

Step 4: Start Web Application

# Start web app in development mode
npm run dev:web

# Web app will run on http://localhost:5173

Step 5: Start Mobile Application (Optional)

# Start mobile app
npm run start -w apps/mobile

# This will start Expo development server
# Use Expo Go app to test on mobile device

Service Endpoints

Backend API

  • Base URL: http://localhost:5000/api/v1
  • Authentication: /auth/*
  • Customers: /customers/*
  • Loans: /loans/*
  • EMI: /emi/*
  • Repayments: /repayments/*
  • Documents: /documents/*
  • Reports: /reports/*

Web Application

  • URL: http://localhost:5173
  • Customer Portal: /customer/*
  • Admin Panel: /admin/*

Mobile Application

  • Development: Expo QR code in terminal
  • Features: Mobile-optimized customer interface

Default Admin Account

After setting up the environment, you can access the admin panel with:

  • Phone: 9999999999 (or your configured ADMIN_PHONE)
  • Password: ChangeMe@123 (or your configured ADMIN_DEFAULT_PASSWORD)

Important: Change the default admin password after first login.

Troubleshooting

Common Issues

  1. Database Connection Errors

    • Verify DATABASE_URL in .env
    • Ensure PostgreSQL is running
    • Check network connectivity

  2. Prisma Client Not Generated

    • Run npm run db:generate -w server
    • Ensure Prisma is installed

  3. Port Already in Use

    • Change PORT in .env (default: 5000)
    • Or kill process using the port

  4. Environment Variables Missing

    • Copy .env.example to .env
    • Fill in all required variables

  5. Redis Connection Issues

    • Verify Upstash Redis configuration
    • Check Redis URL and token

Health Checks

  • Backend Health: GET http://localhost:5000/api/v1/health
  • Database: Check Prisma connection in server logs
  • Redis: Verify Redis connection in server logs

Development Workflow

Making Changes

  1. Backend changes: Server auto-restarts on file changes
  2. Web changes: Vite hot reloads the application
  3. Mobile changes: Expo hot reloads the mobile app

Database Schema Changes

  1. Update server/prisma/schema.prisma
  2. Run npm run db:push -w server (dev) or create migration
  3. Regenerate Prisma client: npm run db:generate -w server

Adding New Features

  1. Backend: Add routes, services, and database models
  2. Frontend: Add components, pages, and API calls
  3. Test: Verify functionality across web and mobile

Production Deployment

Backend

npm run build -w server
npm start -w server

Web

npm run build -w apps/web

Mobile

npm run build -w apps/mobile

Security Considerations

  1. Environment Variables: Never commit .env files
  2. JWT Secrets: Use strong, randomly generated secrets
  3. Database: Use strong passwords and SSL
  4. API Security: Implement rate limiting and authentication
  5. File Uploads: Validate file types and sizes

Monitoring

  • Server Logs: Check console output for server logs
  • Database: Monitor Prisma queries and performance
  • API: Use browser dev tools for network requests
  • Errors: Check console for error messages

Support

For issues or questions:

  1. Check this guide
  2. Review environment configuration
  3. Check logs for error messages
  4. Verify all services are running