Skip to main content

​
Quick Start Guide

This guide will help you set up Millenium Potters on your local machine for development or evaluation purposes.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js 18+

Download from nodejs.org

PostgreSQL 18

Required for local development database
Production deployments use CockroachDB for enhanced scalability and automatic backups. This guide focuses on local development with PostgreSQL.

​
Installation Steps

1

Clone the Repository

First, clone the Millenium Potters repository to your local machine:
git clone <repository-url>
cd Millenium
The project structure includes:
Millenium/
├── frontend/           # Next.js 14 application
├── backend/            # Node.js/Express API server
└── USER_GUIDE.md       # End-user documentation
2

Install Dependencies

Install dependencies for both frontend and backend:
cd frontend
npm install
The backend includes Prisma ORM for database management and Supabase for authentication. The frontend uses Next.js 14 with Tailwind CSS and Aceternity UI components.
See: ~/workspace/source/frontend/package.json and ~/workspace/source/backend/package.json
3

Configure Environment Variables

Create environment files for local development.

​
Backend Configuration

Create backend/.env.local:
backend/.env.local
# Database Configuration
DATABASE_URL="postgresql://postgres:YOUR_PASSWORD@localhost:5432/millenium_local?schema=public"
DIRECT_URL="postgresql://postgres:YOUR_PASSWORD@localhost:5432/millenium_local?schema=public"

# Server Configuration
PORT=5000
NODE_ENV=development

# JWT Configuration
JWT_SECRET="your-secret-key-here-change-in-production"
JWT_EXPIRES_IN="7d"

# Supabase Authentication
SUPABASE_URL="your-supabase-url"
SUPABASE_ANON_KEY="your-supabase-anon-key"

# Cloudinary Storage (Optional for local dev)
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"
CLOUDINARY_API_SECRET="your-api-secret"

# Email Configuration (Optional)
SMTP_HOST="mail.yourdomain.com"
SMTP_PORT=587
SMTP_USER="your-email@domain.com"
SMTP_PASS="your-email-password"

​
Frontend Configuration

Create frontend/.env.local:
frontend/.env.local
# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:5000/api

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL="your-supabase-url"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"
Replace YOUR_PASSWORD with your PostgreSQL password. For Supabase credentials, create a free account at supabase.com.
You can skip Cloudinary configuration for local development. Document uploads will still work but files won’t persist in cloud storage.
4

Set Up the Database

Initialize the database schema using Prisma:
cd backend

# Generate Prisma Client
npx prisma generate

# Push schema to database
npx prisma db push
This creates all necessary tables including Users, Unions, UnionMembers, Loans, Repayments, and more. See the complete schema at ~/workspace/source/backend/prisma/schema.prisma.

​
Optional: Seed Sample Data

To populate the database with sample data for testing:
npm run seed
This creates:
  • Sample users (admin, supervisor, credit officers)
  • Test unions and members
  • Example loans with repayment schedules

​
Database Management Tools

Open Prisma Studio to view and edit your data:
npx prisma studio
Access the UI at: http://localhost:5555
5

Start the Development Servers

Run both the backend API and frontend application:
cd backend
npm run dev:local
The dev:local script uses the .env.local file for configuration. For production, use npm run dev which reads from .env.

​
Access the Application

Once both servers are running:

Frontend

http://localhost:3000

Backend API

http://localhost:5000/api

Health Check

http://localhost:5000/health
6

Log In and Explore

Open your browser to http://localhost:3000 and log in.

​
Default Credentials

If you ran the seed script, use these default accounts:
RoleEmailPassword
Adminadmin@millenium.comadmin123
Supervisorsupervisor@millenium.comsuper123
Credit Officerofficer@millenium.comofficer123
Change these passwords immediately in production environments!

​
Take the Interactive Tour

After logging in:
  1. The Command Center Tour will start automatically
  2. Or click your profile icon → “Take Tour” to start it manually
  3. Learn about dashboard features, navigation, and quick actions
See: ~/workspace/source/frontend/package.json:62 (Shepherd.js integration)

​
Verify Your Installation

Test the backend API is running:
curl http://localhost:5000/health
Expected response:
{
  "status": "ok",
  "database": "connected",
  "timestamp": "2026-03-11T12:00:00.000Z"
}
Verify Prisma can connect to PostgreSQL:
cd backend
npx prisma db pull
You should see: ”✓ Introspection complete”
Try logging in through the frontend UI or test the login endpoint:
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@millenium.com",
    "password": "admin123"
  }'
You should receive a JWT token in the response.

​
Next Steps

Now that you have Millenium Potters running locally, explore these features:

Create a Union

Go to Business Management → Unions → Add Union

Register Members

Add members to your union with full profile details

Process a Loan

Create a loan application and walk through the approval workflow

Record Repayments

Record payments and see the repayment schedule update automatically

​
Common Issues

Error: Can't reach database server at localhost:5432Solution:
  • Ensure PostgreSQL is running: sudo systemctl status postgresql
  • Check the port number in your DATABASE_URL
  • Verify your PostgreSQL password is correct
Error: Port 5000 is already in useSolution:
  • Change the PORT in backend/.env.local to a different value (e.g., 5001)
  • Update NEXT_PUBLIC_API_URL in frontend/.env.local to match
  • Or kill the process using port 5000: lsof -ti:5000 | xargs kill
Error: @prisma/client did not initialize yetSolution:
cd backend
npx prisma generate
Error: Module not found errorsSolution:
cd frontend
rm -rf node_modules package-lock.json
npm install

​
Development Scripts

Useful commands for development:

​
Backend Scripts

# Development with local database
npm run dev:local

# Development with production database
npm run dev

# Build for production
npm run build

# Start production server
npm run start

# Database management
npm run prisma:generate    # Generate Prisma Client
npm run prisma:push        # Push schema changes
npm run prisma:migrate     # Run migrations
npm run prisma:studio      # Open Prisma Studio

# Seed database
npm run seed
See: ~/workspace/source/backend/package.json:6-20

​
Frontend Scripts

# Development with Turbopack (faster)
npm run dev

# Build for production with Turbopack
npm run build

# Start production server
npm run start

# Run linter
npm run lint
See: ~/workspace/source/frontend/package.json:5-10

​
What’s Next?

Architecture Overview

Learn about the system architecture and technology stack

User Guide

Complete guide for using all features of the platform

API Reference

Explore REST API endpoints for integration

Deployment

Deploy to production with CockroachDB and Vercel
Join the interactive tour after logging in to learn about all the dashboard features and navigation options!

Build docs developers (and LLMs) love

Get started for freeTalk to us