SignalBridge

Campus Employability Signal Infrastructure

SignalBridge is a production-ready full-stack web application that revolutionizes campus recruitment by replacing static resumes and cutoffs with continuous, verifiable employability signals. The system models employability as a dynamic system using time-weighted skill evidence, failure and recovery signals, skill provenance, signal decay, and counterfactual hiring simulation.

🎯 Core Innovations

1. Employability Signal Engine - Computes role-specific readiness scores with confidence intervals and volatility metrics
2. Skill Signal Half-Life Model - Tracks skill decay over time with exponential time-weighting
3. Skill Provenance Graph - Tracks where each skill originated (course, project, self-learning, company task)
4. Negative Signal Capture - Tracks failed attempts, abandoned tasks, and misconception patterns
5. Adversarial Skill Validation - Uses Gemini AI to generate unseen task variants and evaluate process quality
6. Readiness Volatility Score - Measures stability of readiness over time
7. Counterfactual Hiring Simulator - Simulates hiring with/without filters to expose bias
8. Placement Cell Early-Warning Radar - Predicts oversupply/undersupply months before placement season

🏗️ Architecture

Tech Stack

• Frontend: Next.js 14 (React, TypeScript), Tailwind CSS, Recharts
• Backend: Node.js with Express, TypeScript
• Database:
  • PostgreSQL (users, roles, hiring rules)
  • Firebase Firestore (real-time signals, events, skill evidence)
• AI & Agents:
  • Google Gemini API for analysis
  • Multi-agent orchestration (ADK pattern)
• Auth: Firebase Authentication (Google + GitHub)

Project Structure

signalbridge/
├── frontend/          # Next.js application
├── backend/           # Express API server
├── agents/            # AI agent implementations
├── shared/            # Shared TypeScript types
└── firebase.rules     # Firestore security rules

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• PostgreSQL 14+
• Firebase project with Firestore enabled
• Google Cloud account with Gemini API access

Environment Variables

Create .env files in backend/ and frontend/:

backend/.env

PORT=3001
NODE_ENV=development

# PostgreSQL
DATABASE_URL=postgresql://user:password@localhost:5432/signalbridge
# OR
DB_USER=postgres
DB_PASSWORD=postgres
DB_HOST=localhost
DB_PORT=5432
DB_NAME=signalbridge

# Firebase
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_SERVICE_ACCOUNT={"type":"service_account",...}
# OR use application default credentials

# Gemini API
GEMINI_API_KEY=your-gemini-api-key

# Frontend URL
FRONTEND_URL=http://localhost:3000

frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:3001
NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id

Installation

1. Install dependencies

# Root
npm install

# Backend
cd backend
npm install

# Frontend
cd ../frontend
npm install

# Agents
cd ../agents
npm install

2. Set up PostgreSQL

# Create database
createdb signalbridge

# Tables will be created automatically on first run

3. Set up Firebase

   • Create a Firebase project
   • Enable Firestore
   • Enable Authentication (Google + GitHub providers)
   • Deploy security rules: firebase deploy --only firestore:rules

4. Run seed script (optional)

cd backend
npm run build
node dist/scripts/seed.js

Running the Application

Development mode:

# From root directory
npm run dev

# Or run separately:
# Terminal 1 - Backend
cd backend
npm run dev

# Terminal 2 - Frontend
cd frontend
npm run dev

Production build:

npm run build

# Start backend
cd backend
npm start

# Start frontend
cd frontend
npm start

The application will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001

📱 User Roles & Dashboards

Student Dashboard

• Skill Trajectory Timeline - Visualize readiness over time
• Signal Decay Visualization - See how skills decay without reinforcement
• Failure-to-Recovery Graph - Track learning from mistakes
• Provenance Map - See where each skill came from

Recruiter Dashboard

• Capability-Based Search - Search by readiness, volatility, evidence
• Candidate Comparison - Compare multiple candidates side-by-side
• Counterfactual Hiring Insights - See bias metrics and false negatives
• Bias Simulation - Run simulations with/without filters

Placement Cell Dashboard

• Cohort Readiness Heatmaps - View readiness by role and batch
• Early-Warning Alerts - Get notified of supply/demand gaps
• Training ROI Insights - See which courses generate employable skills

🤖 AI Agents

The system includes four autonomous agents:

1. SkillDecayAgent - Calculates decay-adjusted readiness scores
2. FailureAnalysisAgent - Clusters misconception and recovery patterns
3. HiringBiasSimulationAgent - Runs counterfactual simulations
4. PlacementRiskForecastAgent - Predicts cohort placement risks

Agents run independently and write structured outputs to Firestore. They can be triggered via API:

POST /api/agents/trigger
{
  "agentName": "SkillDecayAgent",
  "input": { "studentId": "student_1" }
}

🔒 Security

• Role-based access control (RBAC)
• Firebase security rules for Firestore
• Input validation using Zod
• JWT token authentication
• SQL injection protection via parameterized queries

📊 API Endpoints

Authentication

• POST /api/auth/profile - Register/update user profile
• GET /api/auth/me - Get current user

Students

• GET /api/students/dashboard - Get dashboard data
• GET /api/students/provenance - Get skill provenance map
• POST /api/students/evidence - Add skill evidence

Recruiters

• POST /api/recruiters/search - Search candidates
• POST /api/recruiters/compare - Compare candidates
• POST /api/recruiters/simulate - Run hiring simulation
• GET /api/recruiters/bias-metrics - Get bias metrics
• POST /api/recruiters/roles - Create role

Placement Cell

• GET /api/placement/cohort-readiness - Get cohort readiness
• GET /api/placement/early-warnings - Get early warnings
• GET /api/placement/training-roi - Get training ROI
• GET /api/placement/courses-roi - Get all courses ROI

Signals

• POST /api/signals/recompute/:studentId - Recompute signals
• GET /api/signals/skill/:studentId/:skillName - Get skill signal
• GET /api/signals/trajectory/:studentId/:roleId - Get trajectory

Agents

• POST /api/agents/trigger - Trigger agent
• GET /api/agents/status/:executionId - Get execution status
• GET /api/agents/executions - List executions

🧪 Testing

# Backend tests (when implemented)
cd backend
npm test

# Frontend tests (when implemented)
cd frontend
npm test

📦 Deployment

Backend (Node.js/Express)

• Deploy to Heroku, Railway, or AWS Elastic Beanstalk
• Set environment variables
• Ensure PostgreSQL connection
• Configure Firebase service account

Frontend (Next.js)

• Deploy to Vercel (recommended) or Netlify
• Set environment variables
• Configure Firebase client config

Database

• PostgreSQL: Use managed service (AWS RDS, Heroku Postgres, etc.)
• Firestore: Automatically managed by Firebase

Firebase Rules

firebase deploy --only firestore:rules

🛠️ Development

Code Structure

• Backend: Modular service architecture with clear separation of concerns
• Frontend: Component-based React with TypeScript
• Agents: Independent agent modules with shared Firebase config
• Shared Types: Common TypeScript interfaces

Adding New Features

1. Define types in shared/types/index.ts
2. Implement backend service in backend/src/services/
3. Add API route in backend/src/routes/
4. Create frontend component in frontend/src/components/
5. Update dashboard if needed

📝 License

This project is proprietary and confidential.

🤝 Contributing

This is a production system. All changes should be:

• Fully tested
• Documented
• Reviewed before deployment

📧 Support

For issues or questions, contact the development team.

---

SignalBridge - Transforming campus recruitment through dynamic employability signals.