Quickstart Guide

Get your local ForgeX development environment running with Docker Compose. From zero to first bid in under 10 minutes.

Prerequisites

tip

Before you begin, ensure you have:

Node.js v18 or higher (Download)
Docker Desktop (Download)
Git for version control
Google Cloud Console access for OAuth credentials

tip

Already have these? Skip to Installation.

Installation

Clone the Repository

Clone the ForgeX repository to your local machine:

git clone https://github.com/Site-Companies/PSS-Bid-Manager.git
cd PSS-Bid-Manager

Configure Google OAuth (for SuperTokens)

ForgeX uses SuperTokens with Google OAuth for authentication. You'll need Google OAuth credentials:

Go to Google Cloud Console
Create a new project (or select existing)
Enable the Google+ API
Create OAuth 2.0 Client ID credentials:
- Application type: Web application
- Authorized redirect URIs:
  - http://localhost:3000/auth/callback
  - http://localhost:3001/auth/callback
Copy the Client ID and Client Secret

warning

Keep your OAuth credentials secure. Never commit them to version control.

Set Up Environment Files

Copy the example environment files:

# Bids Service Backend
cp services/bids/backend/.env.example services/bids/backend/.env

# Bids Service Frontend
cp services/bids/frontend/.env.example services/bids/frontend/.env

Edit services/bids/backend/.env with your credentials:

# Google OAuth
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

# SuperTokens Core Connection
SUPERTOKENS_CONNECTION_URI=http://supertokens:3567
API_DOMAIN=http://localhost:5001
WEBSITE_DOMAIN=http://localhost:3000

# Database
DATABASE_URL=postgresql://postgres:devpassword@bids-db:5432/bids_db

# Node Environment
NODE_ENV=development

# Resend Email API (optional for local dev)
RESEND_API_KEY=re_xxxxxxxxxxxxx
EMAIL_FROM="Precision Platform <noreply@precisionsiteservices.com>"

tip

SuperTokens Core is included in the Docker Compose setup and will start automatically on port 3567.

(Optional) Set Up GCP Service Account

For file uploads to Google Cloud Storage (production feature):

gcloud iam service-accounts keys create ./gcp-key.json \
  --iam-account=YOUR_SERVICE_ACCOUNT@PROJECT.iam.gserviceaccount.com \
  --project=YOUR_PROJECT_ID

note

Local development works without GCS. Skip this step if you're just testing locally.

The gcp-key.json file is gitignored automatically.

Start Docker Compose

Start all 10 containers (3 databases + 7 services):

docker-compose up -d

What's starting:

Databases: bids-db, projects-db, field-db (PostgreSQL)
Frontends: portal, bids-frontend, projects-frontend, field-frontend
Backends: bids-backend, projects-backend, field-backend

note

First-time startup takes 2-5 minutes to pull images and build containers. Grab a coffee! ☕

Run Database Migrations

Initialize the database schema:

docker-compose exec bids-backend npx prisma migrate dev

Seed the database with sample data:

docker-compose exec bids-backend npx prisma db seed

Sample data includes:

2 test users (your Google account will be added on first login)
5 clients with bids
Pricing catalog (concrete, rebar, equipment, materials)
Global variables (tax rates, overhead, profit)

Access ForgeX

Open your browser and navigate to:

Service	URL	Purpose
Portal	http://localhost:3000	Authentication & app launcher
Bids	http://localhost:3001	Bid management (main app)
Bids API	http://localhost:5001/api	Backend API
Projects	http://localhost:3002	Project management (Phase 2)
Field	http://localhost:3003	Field operations (Phase 3)

tip

Sign in with your Google account at http://localhost:3000

warning

First login: Your Google account won't have permissions yet. You'll see an "Unauthorized" message. Check the next step to grant access.

Grant Admin Access (First Time Only)

After your first login attempt, manually grant yourself admin access:

# Open Prisma Studio
cd services/bids/backend && npx prisma studio

Navigate to the User table
Find your user record (by email)
Change role to ADMIN
Change status to ACTIVE
Save

Refresh the browser and sign in again. You now have full access! 🎉

Your First Bid

Let's create a sample bid to test the workflow:

Access the Bids App

Sign in at http://localhost:3000
Click the Bids tile
You'll see the dashboard with sample bids

Create a Client

Click "Add Client" in the top-right
Fill in:
- Company name: "Test Construction Co."
- Contact name: "John Doe"
- Email: "john@testco.com"
- Phone: "(555) 123-4567"
Click Save

Create a Bid

Click "Add Bid"
Fill in:
- Client: Select "Test Construction Co."
- Job Name: "Memorial Park Foundation"
- Location: "Houston, TX"
- Bid Number: "B-2025-001"
Click Create Bid

Add a Scope

Open your new bid
Click "Add Scope"
Fill in:
- Name: "Foundation Slab"
- Shape: SLAB
Click Save

Add a Concrete Item

Navigate to the Concrete tab
Click "Add Concrete Item"
Fill in:
- Name: "Main slab"
- Shape: SLAB
- Length: 50 ft
- Width: 40 ft
- Depth: 6 in
- Rebar Size: #4
- Rebar Spacing: 12"
- Check "Auto-add to Materials"
Click Save

Watch the magic: Square feet, cubic yards, and costs calculate automatically! 🪄

Review Costs

Go back to the bid summary
View the cost breakdown:
- Concrete module cost
- Scope total (with multiplier applied)
- Bid total (with overhead + profit)

Congratulations! You just created your first ForgeX bid. 🎉

Development Workflow

Hot Reload

All frontend services support hot module replacement (HMR):

# Edit a file in services/bids/frontend/src/
# Save → Browser automatically refreshes

tip

VSCode users: Install the Prisma extension for schema syntax highlighting.

Making Backend Changes

After editing Prisma schema or backend code:

# Rebuild the backend container
docker-compose up -d --build bids-backend

# Create a new migration (if schema changed)
docker-compose exec bids-backend npx prisma migrate dev --name your-migration-name

# Regenerate Prisma client
docker-compose exec bids-backend npx prisma generate

Database Access

Option 1: Prisma Studio (Recommended)

cd services/bids/backend && npx prisma studio

Opens a browser-based GUI at http://localhost:5555

Option 2: psql (Terminal)

docker-compose exec bids-db psql -U postgres -d bids_db

Option 3: TablePlus / pgAdmin

Host: localhost
Port: 5432
Database: bids_db
User: postgres
Password: devpassword

Troubleshooting

Port Already in Use

Error: Bind for 0.0.0.0:3001 failed: port is already allocated

Solution:

Check for conflicting processes:

lsof -i :3001

Stop the conflicting service or change the port in docker-compose.yml
Restart Docker Compose:

docker-compose down && docker-compose up -d

OAuth Fails

Error: "Invalid credentials" or redirect fails

Solutions:

Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in .env
Check authorized redirect URIs in Google Cloud Console:
- http://localhost:3000/auth/callback
- http://localhost:3001/auth/callback
Ensure you're using a web application OAuth client (not iOS/Android)

Database Migration Errors

Error: "Migration failed" or "Table already exists"

Solutions:

Reset the database (⚠️ deletes all data):

docker-compose down -v
docker-compose up -d
docker-compose exec bids-backend npx prisma migrate dev
docker-compose exec bids-backend npx prisma db seed

Check migration status:

docker-compose exec bids-backend npx prisma migrate status

Container Won't Start

Error: Container exits immediately or logs show errors

Solutions:

View logs:

docker logs bidmanager-bids-backend

Check environment variables:

docker-compose exec bids-backend env | grep GOOGLE

Rebuild containers:

docker-compose up -d --build

Hot Reload Not Working

Error: Frontend changes don't reflect in browser

Solutions:

Check volume mounts in docker-compose.yml:

volumes:
  - ./services/bids/frontend:/app
  - /app/node_modules

Restart the frontend container:

docker-compose restart bids-frontend

Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)

Quick Reference Commands

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs (follow mode)
docker logs -f bidmanager-bids-backend

# Restart a single service
docker-compose restart bids-backend

# Rebuild after code changes
docker-compose up -d --build bids-backend

# Access database
docker-compose exec bids-db psql -U postgres -d bids_db

# Open Prisma Studio
cd services/bids/backend && npx prisma studio

# Run migrations
docker-compose exec bids-backend npx prisma migrate dev

# Seed database
docker-compose exec bids-backend npx prisma db seed

# Reset database (⚠️ deletes data)
docker-compose down -v && docker-compose up -d

What's Next?

📖

Core Concepts

Understand bids, scopes, and modules

📄

Creating a Bid

Step-by-step bid workflow

🧮

Estimation Modules

Deep dive into all 6 modules

🗺️

Architecture

System design and tech stack

💻

API Reference

Explore the REST API

☁️

Deployment

Deploy to production (GCP)

note

Need help? Check the Troubleshooting section or review the full architecture.

Prerequisites​

Installation​

Your First Bid​

Development Workflow​

Hot Reload​

Making Backend Changes​

Database Access​

Troubleshooting​

Quick Reference Commands​

What's Next?​

Core Concepts

Creating a Bid

Estimation Modules

Architecture

API Reference

Deployment

Prerequisites

Installation

Your First Bid

Development Workflow

Hot Reload

Making Backend Changes

Database Access

Troubleshooting

Quick Reference Commands

What's Next?