💼🌳🚀 My Career NJ

Empowering New Jersey residents with data-driven career insights and training opportunities

📋 Table of Contents

• 🌟 Overview
• ✨ Key Features
• 🏗️ Architecture
• 🚀 Getting Started
• 📁 Project Structure
• 💻 Development
• 🚢 Deployment
• 🧪 Testing
• 🛠️ Tools and Libraries
• ❓ Troubleshooting
• 📚 Additional Resources
• 🤝 Contributing
• 📞 Support
• 🙏 Acknowledgments

🌟 Overview

My Career NJ is an official career development platform of the New Jersey Department of Labor & Workforce Development. This open-source web application (mycareer.nj.gov) serves as a comprehensive one-stop shop for New Jersey residents to explore training programs, discover in-demand career opportunities, and receive data-driven career advice tailored to their unique experiences and goals.

🎯 Mission

To provide accessible, user-friendly, and data-driven career development tools that help New Jersey residents advance their careers and contribute to the state's economic growth.

📍 Context

This platform is developed and maintained by the New Jersey Department of Labor & Workforce Development as part of the state's commitment to supporting workforce development and economic advancement. It serves as a bridge between job seekers, training providers, and employers across New Jersey.

Note: This repository does not currently include the Career Navigator component, which is maintained separately.

✨ Key Features

• 🎓 Training Program Explorer - Search and compare educational and training programs across New Jersey
• 📊 In-Demand Career Insights - Access real-time labor market data and career trends
• 🗺️ Career Pathways - Interactive career exploration with step-by-step guidance
• 🌐 Multilingual Support - Available in English and Spanish for broader accessibility
• 📱 Responsive Design - Optimized for desktop, tablet, and mobile devices
• ♿ Accessibility First - Built with WCAG compliance and comprehensive a11y testing
• 🔍 Advanced Search - Filter training programs by location, cost, duration, and outcomes
• 💼 Occupation Details - Comprehensive information including salary estimates and education requirements
• 📈 Data Integration - Real-time data from O*NET and CareerOneStop APIs

🏗️ Architecture

Technology Stack

• Frontend: Next.js 15 with React 19 and TypeScript
• Backend: TypeScript with Express-based server API
• Database: Multiple PostgreSQL tables (imported from CSV files in backend/data directory)
• Deployment: Amazon Web Services (AWS) instances running Node.js 20
• CI/CD: GitHub Actions for continuous integration and deployment

System Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Frontend  │    │   Backend    │    │  Database   │
│   (React)   │◄──►│  (Express)   │◄──►│ (PostgreSQL)│
└─────────────┘    └──────────────┘    └─────────────┘
                           │
                           ▼
                   ┌──────────────┐
                   │ External APIs│
                   │ (O*NET, COS) │
                   └──────────────┘

Data Sources

For detailed information about data tables and schema, see the data model documentation.

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js >= 18.0.0 (Download)
• npm >= 8.0.0 (comes with Node.js)
• PostgreSQL >= 12.0 (Download)
• Git (Download)

For Apple Silicon Mac users:

brew install jq

Installation

1. Clone the repository

   git clone https://github.com/newjersey/dol-mcnj-main.git
   cd dol-mcnj-main

2. Install dependencies

   ./scripts/install-all.sh

3. Set up PostgreSQL database

   Create the local database:

   psql -c 'create database d4adlocal;' -U postgres

   Run database migrations:

   ./scripts/db-migrate.sh

   ⚠️ Troubleshooting: If you encounter a password error, update the postgres password in:

   • backend/database.json (line 6)
   • backend/src/app.ts (fallback value)

4. Start the development servers

   In one terminal, start the backend:

   ./scripts/backend-start.sh

   In another terminal, start the frontend:

   ./scripts/frontend-start.sh

   The application will automatically open at http://localhost:3000

Verification

To verify your setup is working correctly:

1. ✅ Frontend loads at http://localhost:3000
2. ✅ Backend API responds at http://localhost:8080
3. ✅ Database connection is successful (check backend console logs)
4. ✅ No error messages in browser console

📁 Project Structure

dol-mcnj-main/
├── 📁 src/                      # Next.js application source
│   ├── 📁 app/                 # Next.js App Router pages
│   ├── 📁 components/          # React components
│   │   ├── 📁 utility/         # Generic UI components
│   │   ├── 📁 modules/         # Reusable features
│   │   ├── 📁 blocks/          # Complex composites
│   │   └── 📁 global/          # Site-wide components
│   ├── 📁 data/                # Static data files
│   └── � utils/               # Utility functions
├── 📁 backend/                  # Express TypeScript API
│   ├── 📁 src/                 # Source code
│   │   ├── 📁 routes/          # API route handlers
│   │   ├── 📁 domain/          # Business logic
│   │   └── 📁 database/        # Database utilities
│   ├── 📁 data/                # CSV data files
│   ├── 📁 migrations/          # Database migrations
│   └── 📄 package.json         # Backend dependencies
├── 📁 cypress/                  # End-to-end tests
├── 📁 scripts/                  # Build and deployment scripts
├── 📁 .github/                 # GitHub Actions workflows
├── � docs/                    # Documentation
└── 📄 README.md                # This file

Key Configuration Files

• Frontend Configuration

  • package.json - Root dependencies and scripts
  • next.config.ts - Next.js configuration
  • tsconfig.json - TypeScript configuration
  • eslint.config.mjs - ESLint rules

• Backend Configuration

  • backend/package.json - Dependencies and scripts
  • backend/database.json - Database connection settings
  • backend/tsconfig.json - TypeScript configuration

• CI/CD Configuration

  • .github/workflows/ - GitHub Actions workflows

💻 Development

Development Workflow

Always use the ship-it script for pushing changes (why?):

./scripts/ship-it.sh

Available Scripts

Script	Purpose	Usage
install-all.sh	Install all dependencies	./scripts/install-all.sh
backend-start.sh	Start backend dev server	./scripts/backend-start.sh
frontend-start.sh	Start frontend dev server	./scripts/frontend-start.sh
build.sh	Build for production	./scripts/build.sh
test-all.sh	Run all tests and linting	./scripts/test-all.sh
feature-tests.sh	Run Cypress e2e tests	./scripts/feature-tests.sh
ship-it.sh	Deploy changes	./scripts/ship-it.sh

Code Style Guidelines

• TypeScript: Strict type checking enabled
• Linting: ESLint with custom rules
• Formatting: Prettier for consistent code style
• Testing: Jest + React Testing Library for unit tests
• E2E Testing: Cypress with accessibility testing

Module Dependencies

This project uses good-fences to enforce module boundaries:

• frontend and backend cannot import from each other
• Backend follows dependency inversion with domain → routes/database

Check dependency compliance:

npm --prefix=backend run fences
npm --prefix=frontend run fences

🚢 Deployment

CI/CD Pipeline

We use GitHub Actions for automated deployments:

Phase 1: Parallel Checks

1. 📝 Lint & Format - Code quality checks
2. 🔐 Security Audit - Vulnerability scanning
3. � JSDoc Coverage - Documentation coverage
4. 🧪 Frontend Tests - Next.js unit tests
5. 🧪 Backend Tests - API unit tests with PostgreSQL

Phase 2: Build 6. �️ Build - Next.js production build

Phase 3: E2E 7. 🎭 E2E Tests - Cypress feature tests

See .github/workflows/README.md for detailed workflow documentation.

Environment Variables

🏗️ Build & Deployment

• NODE_ENV - Environment (dev, test, awsdev, awstest, awsprod)
• IS_CI - Boolean flag for CI environment

🗄️ Database Configuration

• DB_HOST_WRITER_AWSPROD - Production database host
• DB_PASS_AWSPROD - Production database password
• DB_HOST_WRITER_AWSDEV - Development database host
• DB_PASS_AWSDEV - Development database password

🚩 Feature Flags

• REACT_APP_FEATURE_MULTILANG - Enable/disable multi-language support
• REACT_APP_FEATURE_CAREER_PATHWAYS - Toggle career pathways feature
• REACT_APP_FEATURE_CAREER_NAVIGATOR - Toggle Career Navigator landing page
• REACT_APP_SIGNUP_FOR_UPDATES - Toggle user signup modal

🔌 External APIs

• ONET_BASEURL - O*NET API base URL
• ONET_USERNAME - O*NET API username
• ONET_PASSWORD - O*NET API password
• CAREER_ONESTOP_USERID - CareerOneStop API user ID
• CAREER_ONESTOP_AUTH_TOKEN - CareerOneStop API auth token

📊 Content & Analytics

• BASE_URL - Contentful GraphQL API base URL
• ENVIRONMENT - Contentful environment (usually 'master')
• SPACE_ID - Contentful space ID
• SENTRY_DSN - Sentry error tracking DSN

🌐 Additional Services

• ZIPCODE_BASEURL - Zipcode lookup service URL
• ZIPCODE_API_KEY - Zipcode service API key

Manual Deployment

For manual deployments (not recommended for production):

# Build everything
./scripts/build.sh

# Start production server
./scripts/prod-start.sh

🧪 Testing

Testing Stack

• Unit Tests: Jest + React Testing Library
• E2E Tests: Cypress
• Accessibility: cypress-axe
• Linting: ESLint
• Formatting: Prettier

Running Tests

# Run all tests and linting
./scripts/test-all.sh

# Run only e2e tests
./scripts/feature-tests.sh

# Run frontend tests only
npm --prefix=frontend test

# Run backend tests only
npm --prefix=backend test

Test Coverage

Tests cover:

• ✅ Component rendering and interactions
• ✅ API endpoint functionality
• ✅ Database operations
• ✅ User workflows (e2e)
• ✅ Accessibility compliance
• ✅ Responsive design

🛠️ Tools and Libraries

Frontend Libraries

• UI Framework: Material UI + NJ Web Design System
• Routing: Reach Router
• Internationalization: i18next
• State Management: React Context + Hooks
• HTTP Client: Axios
• Form Handling:Yup

Backend Libraries

• Framework: Express.js
• Database: PostgreSQL with custom query builders
• Authentication: Custom middleware
• Error Tracking: Sentry
• AWS SDK: AWS SDK for Node.js

Development Tools

• Analytics: Google Analytics
• Accessibility: axe DevTools, WAVE
• API Testing: WireMock for mocking external APIs

External Data Sources

• O*NET Web API - Occupation data and career information
• CareerOneStop - Labor market and training data

🔑 API Access: Request access to the NJInnovation Bitwarden account for API keys

❓ Troubleshooting

Common Issues

🔧 Installation Problems

Node version issues

# Check Node version
node --version  # Should be >= 18.0.0

# Use nvm to manage Node versions
nvm install 18
nvm use 18

PostgreSQL connection errors

# Check if PostgreSQL is running
brew services list | grep postgres  # macOS
sudo systemctl status postgresql   # Linux

# Reset postgres password
psql -U postgres -c "ALTER USER postgres PASSWORD 'your_password';"

Dependency installation failures

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules backend/node_modules
./scripts/install-all.sh

🚀 Runtime Issues

Frontend won't start

• Check if port 3000 is available
• Ensure backend is running on port 8080
• Check browser console for errors

Backend API errors

• Verify database connection
• Check environment variables
• Review backend console logs

Database migration failures

# Check database exists
psql -U postgres -l | grep d4adlocal

# Run migrations manually
cd backend
npm run db:migrate

🧪 Testing Issues

Cypress installation fails

# Install Cypress manually
cd frontend
npm install cypress --save-dev
npx cypress install

Tests fail in CI

• Check GitHub Actions secrets configuration
• Verify test database configuration
• Review workflow logs for specific failures

Getting Help

1. Check Logs: Always check console output first
2. Search Issues: Look through existing GitHub issues
3. Documentation: Review additional documentation files
4. Contact Team: Reach out via official support channels

📚 Additional Resources

📖 Documentation Hub

📂 Complete Documentation Index - Centralized documentation portal

Quick Access by Category:

• 🔐 Security & Encryption: docs/security/ - PII encryption, KMS, security guides
• 🚀 Deployment: docs/deployment/ - Production deployment procedures
• 🗄️ Database: docs/database/ - Data models, migrations, seeding
• 📋 Project: docs/project/ - Governance, decisions, contributors

External Links

• Live Application: mycareer.nj.gov
• NJ Department of Labor: nj.gov/labor
• New Jersey Web Design System: github.com/newjersey/njwds
• U.S. Web Design System: designsystem.digital.gov

API Documentation

• O*NET Web Services: services.onetcenter.org
• CareerOneStop API: careeronestop.org/Developers

🤝 Contributing

We welcome contributions from developers, designers, content creators, and anyone passionate about improving career development tools!

How to Contribute

1. 📖 Familiarize Yourself - Review project goals and technologies
2. 🔍 Find Issues - Check our issue tracker for "good first issue" labels
3. 🍴 Fork & Clone - Fork the repository and clone to your machine
4. 🔧 Make Changes - Follow our coding standards and include tests
5. 📝 Submit PR - Submit a pull request with clear description

Contribution Guidelines

• Follow the existing code style and conventions
• Include tests for new features
• Update documentation when necessary
• Ensure accessibility compliance
• Test across different browsers and devices

For detailed contribution guidelines, see CONTRIBUTORS.md.

Code of Conduct

We are committed to providing a welcoming and supportive environment. Please review and follow our Code of Conduct.

📞 Support

Getting Help

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues
• 📧 General Questions: Contact us via My Career NJ contact form
• 📚 Documentation: Check our additional resources

🙏 Acknowledgments

Contributors

We extend our heartfelt gratitude to all contributors who have dedicated their time and expertise to improve My Career NJ. Your efforts make a meaningful difference in the lives of New Jersey residents.

Special Thanks

• New Jersey Department of Labor & Workforce Development - Project sponsorship and guidance
• New Jersey Office of Innovation - Technical infrastructure and support
• Open Source Community - Libraries and tools that make this project possible
• New Jersey Residents - Feedback and insights that drive continuous improvement

Technology Partners

• O*NET Program - Occupational data and career information
• CareerOneStop - Labor market and training program data
• Amazon Web Services - Cloud infrastructure
• GitHub Actions - Continuous integration and deployment

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ for New Jersey by the Department of Labor & Workforce Development

Empowering careers, strengthening communities, building New Jersey's future.