SSA Health Platform: Local Development Environment Setup

This guide walks you through setting up a fully functional local development environment for the SSA Health Platform. You will clone the repository, install dependencies for both the React frontend and the NestJS backend, configure your environment variables, initialize the PostgreSQL database with Prisma, and verify that everything is running. By the end you will have the admin UI available at http://localhost:5173 and the API with its Swagger documentation at http://localhost:3000.

Prerequisites

Before you begin, make sure the following are installed and available in your terminal:

Requirement	Minimum version	Notes
Node.js	18+	Use nvm to manage versions
PostgreSQL	14+	Must include the `pgvector` extension
Git	Any recent version	Required to clone the repository

To verify your Node.js version:

node --version

To verify PostgreSQL is running and accessible:

psql --version

The pgvector extension is required for the AI chatbot module. If your PostgreSQL installation does not include it, follow the pgvector installation guide before proceeding.

Clone and install

Clone the repository and install dependencies for both the backend and frontend. The two applications live in separate subdirectories and each has its own package.json.Clone the repository:

git clone https://github.com/LMendoza70/SSA.git
cd SSA

Install backend dependencies (NestJS):

cd backend
npm install

Install frontend dependencies (React + Vite):

cd ../frontend
npm install

You can run both npm install commands in parallel from two terminal tabs to save time.

Configure environment

Each application requires its own .env file. Copy the examples below into the corresponding directories and update the values to match your local setup.Backend — backend/.env:

DATABASE_URL="postgresql://user:password@localhost:5432/ssa_db"
JWT_SECRET="your-secret-key"
JWT_REFRESH_SECRET="your-refresh-secret"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_EXPIRES_IN="7d"
STORAGE_DRIVER="local"
STORAGE_LOCAL_PATH="./uploads"

Frontend — frontend/.env:

VITE_API_URL="http://localhost:3000"

Never commit .env files to version control. Both files are included in .gitignore by default. Use strong, randomly generated values for JWT_SECRET and JWT_REFRESH_SECRET in any shared or staging environment.

Initialize the database

Before running migrations, make sure the vector extension is enabled in your PostgreSQL database. Connect to the target database and run:

CREATE EXTENSION IF NOT EXISTS vector;

Then run the Prisma migrations and seed the database with initial data:

cd backend
npx prisma migrate dev
npx prisma db seed

prisma migrate dev applies all pending migrations and regenerates the Prisma client. prisma db seed populates the database with the initial roles, permissions, and any required reference data.

To open an interactive view of your database schema and data, run npx prisma studio from the backend directory.

Run the application

Start the backend and frontend servers. Each runs in its own terminal session.

# Backend — starts on port 3000
cd backend && npm run start:dev

# Frontend — starts on port 5173
cd frontend && npm run dev

The backend uses NestJS watch mode (start:dev), so it will automatically reload on file changes. The frontend uses Vite’s HMR (Hot Module Replacement) for instant updates.

Verify the installation

Once both servers are running, open the following URLs in your browser:

URL	What you should see
`http://localhost:5173`	The SSA admin UI — login screen
`http://localhost:3000/api/docs`	Swagger UI with all API endpoints documented

Log in using the credentials created by the database seed script. If the admin UI loads and the Swagger page lists your API routes, the platform is running correctly.

For production deployment, see the Deployment Guide.

Get Started

Product

SSA Health Platform: Local Development Environment Setup

Build docs developers (and LLMs) love

Get Started

Product

Documentation Index

Build docs developers (and LLMs) love