Local Development Setup¶

This guide walks you through setting up the NeoCore CBMS AI development environment on a local machine.

Prerequisites¶

Tool	Version	Purpose
Java (JDK)	17+	Spring Boot services
Maven	3.8+	Backend build
Node.js	18+	React frontend
Docker Desktop	Latest	PostgreSQL, Kafka, Redis
Git	Latest	Version control

1. Clone Repositories¶

# Backend microservices
git clone <cbms-ai-microservices-repo-url>

# Frontend
git clone <cbms-ai-frontend-repo-url>

# Developer portal
git clone <cbms-ai-dev-portal-repo-url>

2. Start the Database¶

From the cbms-ai-microservices/ directory:

docker-compose up -d

This starts: - PostgreSQL 13 on port 5432 (database: neocoredb) - Redis on port 6379 (optional, if configured) - Kafka on port 9092 (optional, if configured)

3. Run Database Migrations¶

The common-service owns all Flyway migrations. Run it first so all schemas and functions are in place:

cd microservices/common-service
mvn spring-boot:run

Wait for the Started CommonServiceApplication log line, then stop it (Ctrl+C). Migrations are now applied.

4. Start Microservices¶

Start services in this order (gateway last):

# Start each service — use the .bat scripts on Windows
start-deposit-service.bat
start-customer-service.bat
start-product-service.bat
# ... other services as needed

# Start the API Gateway last
start-api-gateway.bat

Or use the Maven plugin:

cd microservices/customer-service
mvn spring-boot:run

5. Start the Frontend¶

cd cbms-ai-frontend/showcase-app
npm install
npm run dev

The frontend dev server starts at http://localhost:5173.

6. Verify Everything Works¶

Check	URL
Eureka Dashboard	`http://localhost:8761`
API Gateway health	`http://localhost:8080/actuator/health`
Customer service	`http://localhost:8082/actuator/health`
Deposit service	`http://localhost:8081/actuator/health`
Frontend	`http://localhost:5173`

Environment Variables¶

Each service reads from application.yml. For local development, defaults connect to the Docker PostgreSQL instance. To override:

# Example — override DB URL
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/neocoredb
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=yourpassword

Common Issues¶

Port already in use

Run netstat -ano | findstr :<port> to find the conflicting process and kill it with taskkill /PID <pid> /F.

Flyway migration fails

Ensure PostgreSQL is running and the neocoredb database exists. Connect via psql -U postgres -h localhost and run CREATE DATABASE neocoredb; if missing.

Frontend can't reach the backend

Check cbms-ai-frontend/showcase-app/src/api/showcaseClient.ts — the BASE_URL must point to http://localhost:8080 (the API Gateway).