​
Development Setup

This guide will help you set up RippleCore for local development. You’ll have a fully functional social impact evidence platform running in under 10 minutes.

​
Prerequisites

Before you begin, ensure you have installed:

​
1. Clone the Repository

git clone https://github.com/ripplecore/ripplecore-forge.git
cd ripplecore-forge

​
2. Install Dependencies

RippleCore uses a Turborepo monorepo with pnpm workspaces: 
pnpm install
This installs dependencies for all apps and packages in the monorepo.

​
3. Start Infrastructure

RippleCore requires PostgreSQL 18 and Redis 7. Start them with Docker: 
pnpm db:up
This starts:
  • PostgreSQL 18 on port 5432
  • Redis 7 on port 6379
Verify containers are running: 
docker ps | grep -E "postgres|redis"

​
4. Configure Environment

Create environment files for each app: 
# Generate better-auth secret first
npx @better-auth/cli secret

# Then create .env.local with:
DATABASE_URL="postgresql://ripplecore:ripplecore_dev@localhost:5432/ripplecore"
REDIS_URL="redis://:ripplecore_dev@localhost:6379"
BETTER_AUTH_SECRET="<paste-generated-secret>"
BETTER_AUTH_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

DATABASE_URL="postgresql://ripplecore:ripplecore_dev@localhost:5432/ripplecore"
REDIS_URL="redis://:ripplecore_dev@localhost:6379"
BETTER_AUTH_SECRET="<same-secret-as-app>"
BETTER_AUTH_URL="http://localhost:3000"

NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_API_URL="http://localhost:3002"
Important: Use the same BETTER_AUTH_SECRET across all apps for session sharing to work correctly.

​
5. Generate Auth Schema

RippleCore uses better-auth for authentication. Generate the database schema: 
npx @better-auth/cli generate \
  --output ./packages/database/schema/auth.ts \
  --config ./packages/auth/server.ts

​
6. Push Database Schema

Apply the complete database schema (13 tables) to PostgreSQL: 
pnpm db:generate
pnpm db:push
This creates tables for: users, sessions, organizations, kindness acts, volunteer activities, donations, wellbeing surveys, and more.

​
7. Start Development Servers

Start all apps in development mode: 
pnpm dev
This starts:
Success! Navigate to http://localhost:3000 to see RippleCore running.

​
First Steps

​
Create Your First Organization

  1. Visit http://localhost:3000
  2. Click Sign Up and create an account
  3. Complete organization onboarding (takes 2 minutes)
  4. Choose your license tier: Starter (≤50 users), Growth (50-500), or Enterprise (500+)

​
Log Your First Evidence

1

Log a Kindness Act

Navigate to Kindness module and record your first peer recognition. Takes 30 seconds!
{
  "description": "Helped colleague with code review",
  "category": "peer_recognition",
  "verificationLevel": 2
}
2

Create Volunteer Opportunity

Go to Volunteer module and create a community service event with GPS verification.
{
  "title": "Community Garden Cleanup",
  "location": { "latitude": 51.5074, "longitude": -0.1278 },
  "maxParticipants": 20
}
3

Record a Donation

Visit Donation module to track charitable contributions with multi-currency support.
{
  "amount": 100.00,
  "currency": "GBP",
  "cause": "Environmental Conservation"
}

​
Development Tools

​
Database Management

Drizzle Studio provides a web UI for database management: 
pnpm db:studio
Opens on http://localhost:3005 with full access to all tables.

​
View Logs

# PostgreSQL logs
pnpm db:logs postgres

# Redis logs
pnpm db:logs redis

# All infrastructure logs
pnpm db:logs

​
Reset Database

This will delete all data. Only use in development.
pnpm db:down
pnpm db:up
pnpm db:push

​
Testing Your Setup

​
Run the Test Suite

# All tests (Vitest + Playwright)
pnpm test

# Specific package tests
pnpm --filter @repo/kindness test
pnpm --filter @repo/volunteer test

​
Type Checking

# Check all packages
pnpm check

# Specific app
pnpm --filter @repo/app check

​
Linting & Formatting

# Fix all issues (Biome)
pnpm fix

​
Common Issues

Symptom: Error: connect ECONNREFUSED 127.0.0.1:5432Solution:
# Ensure Docker is running
docker ps

# Restart infrastructure
pnpm db:down && pnpm db:up
Symptom: Invalid session or Authentication failedSolution:
# Regenerate auth secret
npx @better-auth/cli secret

# Update .env.local in all apps
# Restart dev servers
Symptom: Error: Redis connection failedSolution:
# Check Redis container
docker ps | grep redis

# Verify REDIS_URL in .env.local
echo $REDIS_URL
Symptom: ERR_PNPM_* errors during installationSolution:
# Clear caches and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

​
Next Steps

Key Concepts

Understand verification tiers, the 30-second rule, and multi-tenant architecture

Employee Guide

Learn how to log evidence as an employee user

Admin Guide

Set up organization settings and manage licenses

API Reference

Explore the complete API documentation

​
Architecture Overview

RippleCore uses a modern, scalable tech stack:
  • Frontend: Next.js 16 + React 19 + Tailwind CSS 4
  • Backend: Hono.js API + Next.js Server Components
  • Database: PostgreSQL 18 with Drizzle ORM
  • Cache: Redis 7 (session storage + evidence caching)
  • Auth: better-auth with organization multi-tenancy
  • Monorepo: Turborepo 2.5.8 + pnpm workspaces
All data is organization-scoped with row-level security and Redis caching for sub-200ms response times.
Need Help? Join our GitHub Discussions or email support@ripplecore.co.uk.