Getting Started

Complete guide to setting up and running the Earna AI Credit Engine locally or in production.

Prerequisites

Before setting up the Credit Engine, ensure you have the following:

System Requirements

Node.js: Version 20.0.0 or higher
npm: Version 10.0.0 or higher
PostgreSQL: Version 15 or higher
Git: For cloning the repository

API Keys Required

Anthropic API Key: For Claude AI integration
Database URL: PostgreSQL connection string

Installation

1. Clone the Repository


git clone https://github.com/identity-wael/earna-ai.git
cd earna-ai/credit-engine

2. Install Dependencies


# From monorepo root
pnpm install
 
# This installs dependencies for all workspaces including credit-engine

3. Environment Configuration

Create a .env.local file in the root directory:


cp .env.example .env.local

Edit .env.local with your configuration:


# Database Configuration
DATABASE_URL="postgresql://user:password@localhost:5432/credit_engine"

# AI Provider
ANTHROPIC_API_KEY="sk-ant-api03-..."

# Authentication
NEXTAUTH_SECRET="your-secret-key-here"
NEXTAUTH_URL="http://localhost:3004"

# Optional: Error Tracking
SENTRY_DSN="https://..."

# Optional: Analytics
POSTHOG_API_KEY="phc_..."

4. Database Setup

Initialize Prisma


# Generate Prisma client
pnpm db:generate
 
# Push schema to database
pnpm db:push

Run Migrations (Production)


pnpm db:migrate

Access Database Studio


pnpm db:studio

This opens Prisma Studio at http://localhost:5555

Development

Running the Development Server


# From monorepo root (recommended)
pnpm turbo dev --filter=credit-engine
 
# Or from credit-engine directory
cd credit-engine && pnpm dev

The API will be available at:

Local: http://localhost:3004
Health Check: http://localhost:3004/api/health

Available Scripts

Command	Description
Command	From Root
---------	-----------
Development	`pnpm turbo dev --filter=credit-engine`
Build	`pnpm turbo build --filter=credit-engine`
Type Check	`pnpm turbo typecheck --filter=credit-engine`
Lint	`pnpm turbo lint --filter=credit-engine`
Start Production	N/A
Generate Prisma	N/A
Push Schema	N/A
Run Migrations	N/A
Prisma Studio	N/A

Testing the API

Health Check


curl http://localhost:3004/api/health

Expected response:


{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Test Chat Endpoint


curl -X POST http://localhost:3004/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "role": "user",
      "content": "How can I improve my credit score from 650 to 750?"
    }]
  }'

Project Structure


credit-engine/
├── app/
│   └── api/                 # API routes
│       ├── chat/            # Credit advisory chat endpoint
│       │   └── route.ts
│       ├── health/          # Health check endpoint
│       │   └── route.ts
│       └── test/            # Test endpoints
│           └── route.ts
├── lib/
│   ├── ai/                  # AI provider system
│   │   ├── claude-provider.ts   # Claude AI integration
│   │   ├── credit-prompts.ts    # Credit-specific prompts
│   │   ├── provider.ts          # Provider interface
│   │   └── service.ts           # AI service layer
│   └── prisma.ts            # Database client
├── prisma/
│   └── schema.prisma        # Database schema
├── auth.ts                  # Authentication configuration
├── next.config.ts           # Next.js configuration
└── package.json             # Dependencies and scripts

Configuration Files

next.config.ts


import type { NextConfig } from "next";
 
const nextConfig: NextConfig = {
  experimental: {
    serverActions: {
      bodySizeLimit: '10mb',
    },
  },
};
 
export default nextConfig;

tsconfig.json


{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Troubleshooting

Common Issues

Port Already in Use

If port 3004 is already in use:


# Find process using port 3004
lsof -i :3004
 
# Kill the process
kill -9 <PID>
 
# Or use a different port
PORT=3005 pnpm turbo dev --filter=credit-engine
 
# From credit-engine directory
PORT=3005 pnpm dev

Database Connection Issues

Verify PostgreSQL is running:


psql -U postgres -c "SELECT version();"

Check connection string format:


postgresql://[user]:[password]@[host]:[port]/[database]

Ensure database exists:


createdb credit_engine

Anthropic API Key Issues

Verify API key is valid
Check for correct format: sk-ant-api03-...
Ensure no extra spaces or quotes in .env.local

Getting Help

GitHub Issues: Report bugs or request features
Documentation: Full documentation
Discord: Join our developer community

Next Steps

Once your development environment is set up:

Explore the Architecture - Understand the system design
Review API Reference - Learn about available endpoints
Check Security Guidelines - Implement best practices
Plan Deployment - Prepare for production