> ## Documentation Index
> Fetch the complete documentation index at: https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Set up and run the CGIAR Risk Intelligence Tool on your local machine

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

## Project Setup

### 1. Clone the Repository

```bash theme={null}
git clone <repository-url>
cd alliance-risk-analysis-tool
```

### 2. Install Dependencies

The project uses pnpm workspaces to manage the monorepo:

```bash theme={null}
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

> [!NOTE]
>
> 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](https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/deployment/environment-variables.md) guide for complete configuration details.

**For the API package:**

```bash theme={null}
cp packages/api/.env.example packages/api/.env
```

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

```bash theme={null}
DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/alliance_risk_dev
```

> [!WARNING]
>
> Never commit `.env` files to version control. They contain sensitive credentials.

### 4. Set Up the Database

#### Generate Prisma Client

```bash theme={null}
cd packages/api
npx prisma generate
```

#### Run Database Migrations

Apply all Prisma migrations to your local PostgreSQL database:

```bash theme={null}
cd packages/api
npx prisma migrate deploy
```

> [!NOTE]
>
> `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):

```bash theme={null}
cd packages/api
npx tsx prisma/seed.ts
```

Or from the project root:

```bash theme={null}
pnpm --filter @alliance-risk/api exec prisma db seed
```

> [!NOTE]
>
> 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:

```bash theme={null}
pnpm --filter @alliance-risk/shared build
```

> [!NOTE]
>
> 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:

```bash theme={null}
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:

```bash API Only theme={null}
# Start NestJS backend on port 3001
pnpm dev:api

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

```bash Web Only theme={null}
# Start Next.js frontend on port 3000
pnpm dev:web

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

> [!NOTE]
>
> 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:**

```bash theme={null}
cd packages/api
npx prisma studio
```

This opens an interactive database GUI at `http://localhost:5555`.

**Create a New Migration:**

```bash theme={null}
cd packages/api
npx prisma migrate dev --name description_of_changes
```

**Reset Database (DESTRUCTIVE):**

```bash theme={null}
cd packages/api
npx prisma migrate reset
```

> [!WARNING]
>
> `migrate reset` drops the database, recreates it, applies all migrations, and runs seed. All data will be lost.

### Testing

```bash All Packages theme={null}
# Run tests for all packages
pnpm test
```

```bash API Tests theme={null}
# 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
```

```bash Web Tests theme={null}
# 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
```

```bash E2E Tests theme={null}
# Run API E2E tests
pnpm --filter @alliance-risk/api test:e2e
```

### Linting

```bash All Packages theme={null}
# Lint all packages
pnpm lint
```

```bash Individual Packages theme={null}
# Lint API
pnpm --filter @alliance-risk/api lint

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

### Building

```bash All Packages theme={null}
# Build all packages
pnpm build
```

```bash Individual Packages theme={null}
# 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:

```bash theme={null}
# 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":

```bash theme={null}
cd packages/api
npx prisma generate
```

### Database Connection Failed

Verify PostgreSQL is running and credentials are correct:

```bash theme={null}
# 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:

```bash theme={null}
pnpm --filter @alliance-risk/shared build
```

## Next Steps

Now that your local environment is running:

1. Access the frontend at `http://localhost:3000`
2. API health check at `http://localhost:3001/api/health`
3. Review [Environment Variables](https://alliancebioversityciat-alliance-risk-analysis-tool.mintlify.site/deployment/environment-variables.md) for AWS service configuration
4. Deploy to AWS using the infrastructure deployment guides


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.