JAVA-PROJECT - SkillBridge Platform

A full-stack peer-to-peer learning and skill exchange platform with clear separation between frontend and backend services.

🏗️ Project Structure

JAVA-PROJECT/
├── backend/                    # Java 25 + Spring Boot 3.5 REST API
│   ├── src/main/java/         # Backend source code
│   ├── src/test/java/         # Backend tests (62 tests, all passing)
│   ├── src/main/resources/    # DB migrations, config, static assets
│   ├── pom.xml                # Maven configuration
│   ├── README.md              # Backend setup & architecture
│   └── Context files/         # Backend technical documentation
├── src/                        # Frontend React/TypeScript code
│   ├── components/            # React components
│   ├── routes/                # TanStack Router pages
│   ├── services/              # API service layer
│   ├── hooks/                 # React custom hooks
│   ├── lib/                   # Utilities & API client
│   └── types/                 # TypeScript types & DTOs
├── public/                    # Static assets
├── package.json               # Frontend dependencies
├── vite.config.ts             # Frontend build config
├── tsconfig.json              # TypeScript config
└── .github/workflows/ci.yml   # CI/CD pipeline

🚀 Quick Start

Run this folder on Windows

From the project root, start the frontend:

npm install
npm run dev

Open http://localhost:3000. Keep the terminal open. If port 3000 is occupied, stop your previous frontend instance or use npm run dev -- --port 3001.

In a second PowerShell terminal, start the Java API:

cd backend
.\mvnw.cmd "-Dfrontend.skip=true" spring-boot:run

The API requires a running PostgreSQL database named skillbridge and a private backend/.env containing JWT_SECRET (at least 32 characters). On a new checkout, copy backend/.env.example to backend/.env, fill in the database settings, and generate a fresh secret. Keep .env private. Quote Maven -D arguments in PowerShell as shown above.

API: http://localhost:9095. Health check: http://localhost:9096/actuator/health. -Dfrontend.skip=true avoids reinstalling/building the frontend when running the API alongside Vite.

Sign in at http://localhost:3000/login using an account in your local database. New users can choose Create an account or open http://localhost:3000/register. Registration requires first name, last name, email, and matching passwords (8–100 characters, including a letter and a number). Successful registration signs you in automatically. Duplicate emails receive a sign-in suggestion. Registration, login, session restoration, role checks, and logout use the real Java API. The account menu displays your name and contains Log out. Other dashboard statistics, certificates, notifications, and page content still display demo data.

To review authentication locally, run npm run test:auth-api while the backend is running. It creates or reuses a synthetic local account and saves its credentials in the ignored auth-test.local file for browser testing. It does not modify your existing accounts. Do not commit that file. Logout clears browser credentials and cached queries immediately and revokes the server refresh-token family; already issued stateless access tokens expire according to the backend JWT lifetime.

Backend migration V24 removes the old demo rule that assigned privileged roles from email wording. New registrations receive USER (Learner); existing roles are preserved. Flyway applies the migration when the backend starts.

To run the compiled frontend locally:

npm run build
npm start

Stop the dev server first, since both use port 3000 by default. The Node server and its runtime dependencies are in .output/server, with assets in .output/public; keep the entire .output folder together. This SSR frontend runs separately from Spring Boot and cannot be served by copying assets into a JAR.

Prerequisites

• Java 25 (for backend): Download from Adoptium
• Node.js 22.22.2+ (for frontend): Download from nodejs.org
• PostgreSQL 16+ or Neon serverless (for database)

Backend Setup

cd backend

# Create .env file with database credentials
# Copy from .env.example and add your Neon credentials

# Install dependencies & run tests
./mvnw clean test

# Start backend server (port 9095)
./mvnw spring-boot:run
# Or on Windows:
.\mvnw.cmd spring-boot:run

Backend runs on http://localhost:9095 API docs available at http://localhost:9095/swagger-ui.html

🔌 API Connectivity

The frontend and backend communicate via HTTP REST API:

Connection Flow:

Browser (localhost:3000)
    ↓
src/lib/api-client.ts (fetch, errors, and token refresh)
    ↓ VITE_API_BASE_URL=http://localhost:9095
src/services/*.ts (API calls)
    ↓
Backend /api/v1/* endpoints (port 9095)
    ↓
PostgreSQL database

CORS Configuration

Backend accepts requests from any localhost port during development:

# backend/src/main/resources/application.yml
skillbridge:
  cors:
    allowed-origins: "http://localhost:*"

For production, set FRONTEND_ORIGINS environment variable to specific domain.

📚 Documentation

🔐 Environment Variables

Backend (.env in backend/ folder)

# Database (Neon or local PostgreSQL)
DATABASE_URL=jdbc:postgresql://[host]:5432/skillbridge
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=your_password

# Server
SERVER_PORT=9095

# JWT Security (change in production!)
JWT_SECRET=your_256_bit_secret_key_here

# Frontend CORS (production)
FRONTEND_ORIGINS=https://your-frontend-domain.com

# Feature flags
FLYWAY_ENABLED=true

Frontend (.env in root folder)

VITE_API_BASE_URL=http://localhost:9095

✅ Verification Checklist

After setup, verify everything works:

# 1. Backend health check
curl http://localhost:9096/actuator/health

# 2. Backend API accessible
curl http://localhost:9095/api/skills

# 3. Frontend runs
npm run dev

# 4. Frontend console shows no CORS errors
# (Open http://localhost:3000 in browser, check DevTools Console)

# 5. Make test API call from frontend
# (Try login, reload, and logout in UI)

🧪 Testing

Backend Tests

cd backend
./mvnw test          # Run all 62 tests
./mvnw test -Dtest=SkillControllerTest  # Run specific test

Frontend Tests

npm test             # Authentication validation, session, API-client and route tests
npm run test:auth-api # Real local API checks; requires the running backend
npm run test:registration-api # Creates a synthetic local account; validates registration and default roles
npm run build        # Type check and build
npx tsc --noEmit     # Type check without building

📦 Building for Production

Backend

cd backend
./mvnw clean package -DskipTests
# JAR file: backend/target/skillbridge-backend-*.jar

Frontend

npm run build
# Built server and assets: .output/

🔄 CI/CD Pipeline

GitHub Actions automatically runs on push to main branch:

• Backend: Compiles, runs 62 tests, packages JAR
• Frontend: Type checks, builds, validates

See .github/workflows/ci.yml for details.

📝 License

Apache 2.0 - See LICENSE

---

Last Updated: 2026-08-30 Status: Full-stack ready for development

See backend/README.md for detailed setup instructions.

Frontend Setup

# Install dependencies
npm install

# Create .env file with API URL
echo "VITE_API_BASE_URL=http://localhost:9095" > .env

# Run development server (port 3000)
npm run dev

# Build for production
npm run build

Frontend runs on http://localhost:3000