Local Development Setup

Overview

The IGAD Innovation Hub is an AI-powered platform built with a modern serverless architecture. This guide will help you set up your local development environment for both frontend and backend development.

Prerequisites

Before you begin, ensure you have the following installed:

Required Software

Node.js 18+

Required for frontend development and infrastructure deployment

node --version  # Should be 18.x or higher

Python 3.11+

Required for backend development

python3 --version  # Should be 3.11.x or higher

AWS CLI

Required for AWS service interactions

aws --version

AWS SAM CLI

Optional but recommended for local Lambda testing

sam --version

AWS Credentials

You’ll need AWS credentials configured with access to:

DynamoDB - Database operations
S3 - Document storage and vector storage
Cognito - User authentication
Bedrock - Claude AI integration
Lambda - Function invocation (for async operations)

The project uses the IBD-DEV AWS profile for development. Configure this profile in your AWS credentials file:

aws configure --profile IBD-DEV

Ensure the region is set to us-east-1:

aws configure set region us-east-1 --profile IBD-DEV

Repository Structure

allianceIGAD/
├── igadapp/
│   ├── frontend/           # React + TypeScript + Vite
│   ├── backend/            # Python + FastAPI + Lambda
│   ├── infrastructure/     # AWS CDK stacks
│   ├── scripts/            # Deployment scripts
│   ├── config/             # Environment configs
│   └── template.yaml       # SAM template
├── planning/               # Planning notes
├── prompts/                # Prompt templates
└── specs/                  # Designs and mockups

Frontend Setup

The frontend is a React 18 single-page application built with Vite.

1. Navigate to Frontend Directory

cd igadapp/frontend

2. Install Dependencies

npm install

This installs all dependencies from package.json including:

React 18 - UI framework
TypeScript - Type safety
Vite - Build tool and dev server
Tailwind CSS - Styling
React Query - Server state management
Zustand - Client state management
React Router - Navigation
Axios - HTTP client

3. Configure Environment Variables

Create a .env file in the frontend directory:

VITEAPIBASEURL=http://localhost:8000/api

For production builds, this should point to your deployed API Gateway endpoint.

4. Start Development Server

npm run dev

The frontend will be available at http://localhost:3000

Available Scripts

Command	Description
`npm run dev`	Start dev server (port 3000, hot reload)
`npm run build`	Production build
`npm run preview`	Preview production build
`npm run typecheck`	TypeScript type checking
`npm run lint`	Run ESLint (strict, maxwarnings 0)
`npm run lint:fix`	Auto-fix linting issues
`npm run format`	Format with Prettier
`npm run test`	Run Vitest tests
`npm run test:coverage`	Run tests with coverage

Backend Setup

The backend is a FastAPI application designed to run in AWS Lambda with DynamoDB.

1. Navigate to Backend Directory

cd igadapp/backend

2. Install Dependencies

pip install -r requirements.txt

Key dependencies:

FastAPI 0.104.1 - Web framework
Uvicorn ~0.30.0 - ASGI server
boto3 >=1.42.0 - AWS SDK
Pydantic 2.5.0 - Data validation
Mangum 0.17.0 - Lambda adapter
awslambdapowertools 2.25.0 - Lambda utilities

3. Configure Environment Variables

Create a .env file in the backend directory:

# AWS Configuration
AWSREGION=useast1
AWSPROFILE=IBDDEV

# Cognito
COGNITOUSERPOOLID=useast1IMi3kSuB8
COGNITOCLIENTID=7p11hp6gcklhctcr9qffne71vl

# DynamoDB
TABLENAME=igadtestingmaintable

# S3
PROPOSALSBUCKET=igadproposaldocuments<account-id>

# Lambda Workers
WORKERFUNCTIONNAME=igadtestingAnalysisWorkerFunction

# Environment
ENVIRONMENT=testing
CORSALLOWEDORIGINS=http://localhost:3000

Replace <account-id> with your AWS account ID. You can find resource names from deployed stacks in AWS CloudFormation.

4. Start Development Server

python startserver.py

Or directly with uvicorn:

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

The API will be available at http://localhost:8000

API Docs (Swagger): http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Available Make Commands

The backend includes a Makefile for common tasks:

Command	Description
`make format`	Format with Black + isort
`make lint`	Run Flake8 linter
`make typecheck`	Run Mypy type checker
`make check`	All checks without fixing
`make test`	Run all pytest tests
`make testcov`	Run tests with coverage
`make allchecks`	Format, lint, type-check, and test

Verify Installation

Frontend Health Check

Open http://localhost:3000 in your browser
You should see the IGAD Innovation Hub login page
Check the browser console for errors

Backend Health Check

Visit http://localhost:8000/docs
Try the health check endpoint:

curl http://localhost:8000/api/health

Expected response:

{
  "status": "healthy",
  "service": "igadapi",
  "timestamp": "20260304T12:00:00Z"
}

Common Setup Issues

Frontend won't connect to backend

Verify backend is running on port 8000
Check VITEAPIBASEURL in frontend .env
Ensure CORS is configured correctly in backend
Check browser console for CORS errors

AWS credentials not found

Run aws configure --profile IBDDEV
Set region to useast1
Export profile: export AWSPROFILE=IBDDEV
Verify credentials: aws sts getCallerIdentity --profile IBDDEV

DynamoDB connection errors

Verify table exists: aws dynamodb describeTable --tablename igadtestingmaintable --profile IBDDEV
Check IAM permissions for DynamoDB access
Ensure TABLENAME environment variable is set

Python import errors

Ensure you’re in the backend directory
Activate virtual environment if using one
Reinstall dependencies: pip install -r requirements.txt
Check Python version: python3 --version (should be 3.11+)

Next Steps

Frontend Development

Learn about React architecture, component patterns, and state management

Backend Development

Explore FastAPI routes, service architecture, and AI integration

Infrastructure

Understand AWS CDK stacks and deployment configuration

Development Workflow

Start backend: cd igadapp/backend && python startserver.py
Start frontend: cd igadapp/frontend && npm run dev
Make changes to code
Hot reload automatically updates both servers
Run tests before committing
Format and lint code

Use two terminal windows or tabs - one for frontend and one for backend - to see logs from both simultaneously.

Get Started

Core Features

Development

Deployment

Overview

Prerequisites

Required Software

Node.js 18+

Python 3.11+

AWS CLI

AWS SAM CLI

AWS Credentials

Repository Structure

Frontend Setup

1. Navigate to Frontend Directory

2. Install Dependencies

3. Configure Environment Variables

4. Start Development Server

Available Scripts

Backend Setup

1. Navigate to Backend Directory

2. Install Dependencies

3. Configure Environment Variables

4. Start Development Server

Available Make Commands

Verify Installation

Frontend Health Check

Backend Health Check

Common Setup Issues

Next Steps

Frontend Development

Backend Development

Infrastructure

Development Workflow

Build docs developers (and LLMs) love

Get Started

Core Features

Development

Deployment

​Overview

​Prerequisites

​Required Software

Node.js 18+

Python 3.11+

AWS CLI

AWS SAM CLI

​AWS Credentials

​Repository Structure

​Frontend Setup

​1. Navigate to Frontend Directory

​2. Install Dependencies

​3. Configure Environment Variables

​4. Start Development Server

​Available Scripts

​Backend Setup

​1. Navigate to Backend Directory

​2. Install Dependencies

​3. Configure Environment Variables

​4. Start Development Server

​Available Make Commands

​Verify Installation

​Frontend Health Check

​Backend Health Check

​Common Setup Issues

​Next Steps

Frontend Development

Backend Development

Infrastructure

​Development Workflow

Build docs developers (and LLMs) love

Overview

Prerequisites

Required Software

AWS Credentials

Repository Structure

Frontend Setup

1. Navigate to Frontend Directory

2. Install Dependencies

3. Configure Environment Variables

4. Start Development Server

Available Scripts

Backend Setup

1. Navigate to Backend Directory

2. Install Dependencies

3. Configure Environment Variables

4. Start Development Server

Available Make Commands

Verify Installation

Frontend Health Check

Backend Health Check

Common Setup Issues

Next Steps

Development Workflow