Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js 20.x or later
  • npm, yarn, or pnpm package manager
  • PostgreSQL database (local or hosted)
  • Git for version control

​
Installation

1

Clone the repository

Clone the jøsh repository to your local machine:
git clone <repository-url>
cd jmash
2

Install dependencies

Install the project dependencies using your preferred package manager:
npm install
The project uses Next.js 15 with React 18, Prisma ORM, and various AI/communication integrations.
3

Configure environment variables

Create a .env file in the root directory and configure your environment variables.See the Environment Variables page for a complete reference.
Never commit your .env file to version control. It contains sensitive credentials.
4

Set up the database

Generate the Prisma client and run database migrations:
npm run db:generate
This will:
  • Generate the Prisma client based on your schema
  • Create all necessary database tables and relationships
  • Apply any pending migrations
5

Start the development server

Launch the Next.js development server:
npm run dev
The application will be available at http://localhost:3000

​
Development Scripts

The following npm scripts are available for development:
ScriptCommandDescription
devnpm run devStart Next.js development server
buildnpm run buildBuild production bundle
startnpm startStart production server
lintnpm run lintRun ESLint code linting
db:generatenpm run db:generateGenerate Prisma client
db:migratenpm run db:migrateRun database migrations
sms:checknpm run sms:checkCheck SMS segment calculations

​
Project Structure

The jøsh codebase follows Next.js 15 App Router conventions: 
src/
├── app/              # Next.js app router pages and API routes
│   ├── api/          # API route handlers
│   └── ...           # Page components
├── lib/              # Utility functions and business logic
├── server/           # Server-side code (tRPC, database)
└── components/       # React components
prisma/
└── schema.prisma     # Database schema definition
The application uses tRPC for type-safe API calls between client and server.

​
Database Schema

The application uses PostgreSQL with Prisma ORM. Key models include:
  • User - Application users with voting history
  • Photo - Photo entries with ELO ratings
  • Vote - User votes for photo comparisons
  • TpoUser - TPO (Time, Place, Occasion) dating users
  • TpoDate - Scheduled dates between users
  • Shot - Shot-shooting feature entries
View the complete schema at prisma/schema.prisma:1

​
AI & Communication Integrations

jøsh integrates with several external services:
  • OpenAI - AI-powered features via AI SDK
  • Mistral - Alternative AI provider
  • Supabase - File storage and authentication
  • Surge SMS - SMS messaging for dating features
  • PostHog - Analytics and feature flags
All integrations require proper environment variable configuration. Missing variables will cause runtime errors.

​
Troubleshooting

​
Database Connection Issues

If you encounter database connection errors:
  1. Verify your DATABASE_URL and DIRECT_URL are correct
  2. Ensure PostgreSQL is running
  3. Check that the database exists
  4. Run npm run db:migrate to apply migrations

​
Prisma Client Errors

If Prisma client is not found: 
npm run db:generate

​
Port Already in Use

If port 3000 is already in use, you can specify a different port: 
PORT=3001 npm run dev

​
Next Steps

Environment Variables

Configure all required environment variables

Deployment

Deploy jøsh to production

Build docs developers (and LLMs) love

Get started for freeTalk to us