Local Development

Auto-generate your docs

This guide walks you through setting up the development environment and running the platform locally.

Project Setup

1. Clone the Repository

git clone <repository-url>
cd alliance-risk-analysis-tool

2. Install Dependencies

The project uses pnpm workspaces to manage the monorepo:

pnpm install

This installs dependencies for all packages:

@alliance-risk/api - NestJS backend
@alliance-risk/web - Next.js frontend
@alliance-risk/shared - Shared types and constants
@alliance-risk/infra - AWS CDK infrastructure

The installation may take a few minutes. pnpm will install dependencies and run postinstall scripts for packages like Prisma and NestJS.

3. Configure Environment Variables

Set up environment variables for local development. See the Environment Variables guide for complete configuration details. For the API package:

cp packages/api/.env.example packages/api/.env

Edit packages/api/.env with your local PostgreSQL credentials:

DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/alliance_risk_dev

Never commit .env files to version control. They contain sensitive credentials.

4. Set Up the Database

Generate Prisma Client

cd packages/api
npx prisma generate

Run Database Migrations

Apply all Prisma migrations to your local PostgreSQL database:

cd packages/api
npx prisma migrate deploy

migrate deploy applies all pending migrations without creating new ones. Use migrate dev when developing new schema changes.

Seed the Database

Populate the database with initial data (admin user and sample prompts):

cd packages/api
npx tsx prisma/seed.ts

Or from the project root:

pnpm --filter @alliance-risk/api exec prisma db seed

The seed script creates an initial admin user. Check packages/api/prisma/seed.ts for credentials.

5. Build Shared Package

The @alliance-risk/shared package must be built before the API and Web packages can import from it:

pnpm --filter @alliance-risk/shared build

You only need to rebuild the shared package when you modify types, enums, or constants in packages/shared/src/.

Running Development Servers

Start All Services

Run both the API and Web development servers concurrently:

pnpm dev

This starts:

API Server on http://localhost:3001 (NestJS with hot reload)
Web Server on http://localhost:3000 (Next.js with Fast Refresh)

Start Services Individually

You can also run each service separately:

# Start NestJS backend on port 3001
pnpm dev:api

# Or from the api package directory
cd packages/api
pnpm dev

# Start Next.js frontend on port 3000
pnpm dev:web

# Or from the web package directory
cd packages/web
pnpm dev

The Web app expects the API to be running on http://localhost:3001. You can override this with the NEXT_PUBLIC_API_URL environment variable.

Development Workflow

Database Management

View Database with Prisma Studio:

cd packages/api
npx prisma studio

This opens an interactive database GUI at http://localhost:5555. Create a New Migration:

cd packages/api
npx prisma migrate dev --name description_of_changes

Reset Database (DESTRUCTIVE):

cd packages/api
npx prisma migrate reset

migrate reset drops the database, recreates it, applies all migrations, and runs seed. All data will be lost.

Testing

# Run tests for all packages
pnpm test

# Run API tests
pnpm --filter @alliance-risk/api test

# Run specific test file
pnpm --filter @alliance-risk/api test -- --testPathPattern=auth.service

# Watch mode
pnpm --filter @alliance-risk/api test:watch

# Coverage
pnpm --filter @alliance-risk/api test:cov

# Run Web tests
pnpm --filter @alliance-risk/web test

# Run specific test file
pnpm --filter @alliance-risk/web test -- --testPathPattern=login-form

# Watch mode
pnpm --filter @alliance-risk/web test:watch

# Run API E2E tests
pnpm --filter @alliance-risk/api test:e2e

Linting

# Lint all packages
pnpm lint

# Lint API
pnpm --filter @alliance-risk/api lint

# Lint Web
pnpm --filter @alliance-risk/web lint

Building

# Build all packages
pnpm build

# Build API
pnpm --filter @alliance-risk/api build

# Build Web (static export)
pnpm --filter @alliance-risk/web build

# Build Shared
pnpm --filter @alliance-risk/shared build

Project Structure

alliance-risk-analysis-tool/
├── packages/
│   ├── api/                 # NestJS backend (port 3001)
│   │   ├── src/
│   │   │   ├── auth/        # Cognito authentication
│   │   │   ├── admin/       # User management
│   │   │   ├── prompts/     # Prompt CRUD & versioning
│   │   │   ├── jobs/        # Async job processing
│   │   │   ├── bedrock/     # AWS Bedrock integration
│   │   │   └── database/    # Prisma service
│   │   └── prisma/
│   │       ├── schema.prisma
│   │       ├── migrations/
│   │       └── seed.ts
│   ├── web/                 # Next.js frontend (port 3000)
│   │   ├── src/
│   │   │   ├── app/         # App Router pages
│   │   │   ├── components/  # React components
│   │   │   ├── hooks/       # React Query hooks
│   │   │   └── lib/         # API client, utilities
│   │   └── public/
│   ├── shared/              # Shared types & constants
│   │   └── src/
│   │       ├── enums/
│   │       ├── types/
│   │       └── constants/
│   └── infra/               # AWS CDK infrastructure
│       ├── lib/
│       └── cfn/
├── scripts/                 # Deployment scripts
├── docs/                    # Documentation
└── pnpm-workspace.yaml      # pnpm workspace config

Common Issues

Port Already in Use

If port 3001 or 3000 is already in use:

# Find and kill the process using port 3001
lsof -ti:3001 | xargs kill -9

# Find and kill the process using port 3000
lsof -ti:3000 | xargs kill -9

Prisma Client Out of Sync

If you see “Prisma Client did not initialize yet”:

cd packages/api
npx prisma generate

Database Connection Failed

Verify PostgreSQL is running and credentials are correct:

# Test connection
psql -U postgres -d alliance_risk_dev

# Check service status
brew services list  # macOS
sudo systemctl status postgresql  # Linux

Module Not Found in Shared Package

Rebuild the shared package:

pnpm --filter @alliance-risk/shared build

Next Steps

Now that your local environment is running:

Access the frontend at http://localhost:3000
API health check at http://localhost:3001/api/health
Review Environment Variables for AWS service configuration
Deploy to AWS using the infrastructure deployment guides

Setup

AWS Infrastructure

Operations

Project Setup

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Set Up the Database

Generate Prisma Client

Run Database Migrations

Seed the Database

5. Build Shared Package

Running Development Servers

Start All Services

Start Services Individually

Development Workflow

Database Management

Testing

Linting

Building

Project Structure

Common Issues

Port Already in Use

Prisma Client Out of Sync

Database Connection Failed

Module Not Found in Shared Package

Next Steps

​Project Setup

​1. Clone the Repository

​2. Install Dependencies

​3. Configure Environment Variables

​4. Set Up the Database

​Generate Prisma Client

​Run Database Migrations

​Seed the Database

​5. Build Shared Package

​Running Development Servers

​Start All Services

​Start Services Individually

​Development Workflow

​Database Management

​Testing

​Linting

​Building

​Project Structure

​Common Issues

​Port Already in Use

​Prisma Client Out of Sync

​Database Connection Failed

​Module Not Found in Shared Package

​Next Steps

Project Setup

1. Clone the Repository

2. Install Dependencies

3. Configure Environment Variables

4. Set Up the Database

Generate Prisma Client

Run Database Migrations

Seed the Database

5. Build Shared Package

Running Development Servers

Start All Services

Start Services Individually

Development Workflow

Database Management

Testing

Linting

Building

Project Structure

Common Issues

Port Already in Use

Prisma Client Out of Sync

Database Connection Failed

Module Not Found in Shared Package

Next Steps