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:
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
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
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:
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
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
http://localhost:5555.
Create a New Migration:
cd packages/api
npx prisma migrate dev --name description_of_changes
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
Linting
# Lint all packages
pnpm lint
Building
# Build all packages
pnpm 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
