OnboardIQ

PS Title: Autonomous Developer Onboarding Agent Platform

Team Name: HacknCrack

Track: Agentic AI [Rezinix AI]

PPT link: https://drive.google.com/drive/folders/1VtqV5JZNiVMvmlnwF27vU-f_5x6e3Uwv?usp=sharing

Video Link: https://drive.google.com/drive/folders/1MNWMied_mxTCVTxqJhBTJX1l0HPSKyKo

Deployed Link: https://onboardiq-web.vercel.app

Additional Resources: https://drive.google.com/drive/folders/1Riek1LrUxTp8gDm4EtMQ0T5MMs26FdSq?usp=sharing

OnboardIQ is an AI-powered onboarding platform that guides new developers through role-specific onboarding checklists using conversational AI, RAG-based knowledge retrieval, and real-time task tracking. It integrates with GitHub, Slack, and Jira to automate common onboarding tasks.

Key USP: VS Code Extension - Onboard Where You Code

OnboardIQ ships with a VS Code extension that brings the entire onboarding experience directly into the developer's editor — no browser tab switching required. New hires can chat with the AI agent, track their checklist, verify their environment setup, and scan their workspace — all without leaving VS Code. The extension auto-detects the project's tech stack from package.json, requirements.txt, go.mod, etc., and pre-fills the onboarding profile. Environment verification runs CLI checks (Node, Git, Docker, Python) and auto-completes matching checklist tasks. Real-time WebSocket streaming means AI responses appear token-by-token, and checklist progress syncs live between the web app and the extension.

Architecture Overview

                    +------------------+
                    |   Next.js Web    |
                    |   (Port 3000)    |
                    +--------+---------+
                             |
                   REST API + WebSocket (Socket.io)
                             |
                    +--------+---------+
                    |  Fastify Server  |
                    |   (Port 4000)    |
                    +--------+---------+
                             |
          +------------------+------------------+
          |                  |                  |
  +-------+------+  +-------+------+  +--------+--------+
  |  PostgreSQL  |  |    Redis     |  |  External APIs  |
  |  + pgvector  |  |   (BullMQ)  |  | Groq, HF, Slack |
  |  (Port 5432) |  | (Port 6379) |  | GitHub, Jira    |
  +--------------+  +--------------+  +-----------------+

  +------------------+
  | VS Code Extension| -----> Socket.io -----> Fastify Server
  +------------------+

Tech Stack

Layer	Technology
Frontend	Next.js 14, React 18, TypeScript, Tailwind CSS, Framer Motion, Radix UI, React Markdown, Socket.io Client
Backend	Fastify 4, TypeScript, Prisma 5, Zod, Socket.io, BullMQ, Winston, Nodemailer
Database	PostgreSQL 16 + pgvector extension
Cache / Queue	Redis 7 (BullMQ for async jobs)
AI / LLM	Groq API (LLM chat responses)
Embeddings	Hugging Face Inference API (384-dim vectors)
Auth	JWT (@fastify/jwt) with bcrypt password hashing
Security	Helmet.js, CORS whitelist, rate limiting (100 req/min)
Shared	npm workspaces monorepo, shared types + Zod validators
DevOps	Docker Compose, multi-stage Dockerfile

Project Structure

onboardiq/
├── apps/
│   ├── server/                  # Fastify backend
│   │   ├── prisma/
│   │   │   ├── schema.prisma    # Database schema (11 tables)
│   │   │   ├── init.sql         # pgvector extension init
│   │   │   └── seed.ts          # Demo user seeder
│   │   └── src/
│   │       ├── agents/          # 7 AI agents (persona, planner, RAG, action, verifier, reporting, KB)
│   │       │   ├── orchestrator.ts   # Central agent dispatcher
│   │       │   ├── persona-agent.ts  # Extracts user role/experience/stack
│   │       │   ├── planner-agent.ts  # Generates onboarding checklist
│   │       │   ├── rag-agent.ts      # RAG retrieval + LLM response
│   │       │   ├── action-agent.ts   # GitHub/Slack/Jira integrations
│   │       │   ├── verifier-agent.ts # Environment setup verification
│   │       │   └── reporting-agent.ts# HR completion reports
│   │       ├── lib/             # Utilities (env, mailer, logger, completion, ps03)
│   │       ├── queue/           # BullMQ workers (email, integrations, reindex)
│   │       ├── rag/             # RAG ingestion pipeline (chunking + embedding)
│   │       ├── routes/          # REST API routes
│   │       │   ├── auth.ts      # Register, login, profile
│   │       │   ├── sessions.ts  # Session CRUD
│   │       │   ├── chat.ts      # Chat messaging (streaming)
│   │       │   ├── admin.ts     # Admin dashboard APIs
│   │       │   ├── hr.ts        # HR reports
│   │       │   ├── verify.ts    # Verification submission
│   │       │   ├── knowledge.ts # Knowledge ingestion + search
│   │       │   └── integrations.ts # GitHub/Slack/Jira
│   │       ├── websocket/       # Socket.io event handlers
│   │       └── index.ts         # Server entry point
│   ├── web/                     # Next.js frontend
│   │   └── src/
│   │       ├── app/             # App Router pages (/, /onboard, /admin)
│   │       ├── components/      # UI components (chat, checklist, sidebar, theme)
│   │       ├── context/         # React contexts (auth, socket, session)
│   │       └── lib/             # API client, utilities
│   └── vscode-ext/              # VS Code extension
│       └── src/
│           ├── extension.ts     # Extension entry point
│           ├── providers/       # Webview chat provider
│           └── services/        # API, auth, socket, workspace scanner, verifier
├── packages/
│   └── shared/                  # Shared types, validators, constants
│       └── src/
│           ├── types.ts         # TypeScript type definitions
│           ├── validators.ts    # Zod request/response schemas
│           ├── constants.ts     # App constants, WebSocket events, RAG config
│           └── intake.ts        # Intake form logic
├── docker/
│   └── Dockerfile               # Multi-stage Docker build
├── docs/
│   ├── architecture.md          # Architecture diagrams (Mermaid)
│   ├── demo_script.md           # Demo walkthrough
│   ├── site_design.md           # UI design notes
│   ├── postman_collection.json  # API testing collection
│   └── PS03/                    # Knowledge base (14 markdown files)
├── scripts/                     # Shell verification helpers
├── docker-compose.yml           # Local dev infrastructure
├── .env.example                 # Environment variable template
├── package.json                 # Root workspace config
└── tsconfig.base.json           # Base TypeScript config

Prerequisites

Node.js >= 18.x (20+ recommended)
npm >= 9.x
Docker & Docker Compose (for database/redis, or full stack)
Git

API Keys Required

Key	Source	Purpose
`GROQ_API_KEY`	console.groq.com	LLM chat responses
`HF_API_KEY`	huggingface.co/settings/tokens	Text embeddings for RAG

Note: GitHub, Slack, and Jira integrations are optional. Set MOCK_INTEGRATIONS=true to use mock implementations during development.

Local Setup

Option A: Docker (Recommended)

This starts PostgreSQL, Redis, the backend, and frontend in containers.

# 1. Clone the repository
git clone https://github.com/<your-org>/Syrus2026_HacknCrack.git
cd Syrus2026_HacknCrack

# 2. Create environment file
cp .env.example .env

# 3. Fill in required API keys in .env
#    - GROQ_API_KEY
#    - HF_API_KEY
#    - JWT_SECRET (change from default)

# 4. Start all services
docker compose up --build

The application will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:4000
Health Check: http://localhost:4000/health

Option B: Manual Setup

Step 1: Install Dependencies

git clone https://github.com/<your-org>/Syrus2026_HacknCrack.git
cd Syrus2026_HacknCrack
npm install

Step 2: Start PostgreSQL and Redis

Using Docker (infrastructure only):

docker compose up -d postgres redis

This starts:

PostgreSQL on localhost:5432
Redis on localhost:6379

Or install them locally:

PostgreSQL 16 with the pgvector extension enabled
Redis 7

Step 3: Configure Environment

cp .env.example .env

Edit .env and fill in the required values:

# Required - AI APIs
GROQ_API_KEY=your_groq_api_key
HF_API_KEY=your_huggingface_api_key

# Required - Auth
JWT_SECRET=your-secure-random-string

# Database (defaults work with docker compose)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/onboardiq?schema=public
DIRECT_URL=postgresql://postgres:postgres@localhost:5432/onboardiq?schema=public

# Redis (defaults work with docker compose)
REDIS_URL=redis://localhost:6379

# Knowledge base path
KNOWLEDGE_LOCAL_PATH=docs/PS03

# Keep mocks enabled for local dev
MOCK_INTEGRATIONS=true
MOCK_SMTP=true

Note: The backend reads the root .env file even if you run it from apps/server.

Step 4: Build Shared Package

The shared package must be built first as both server and web depend on it:

npm run build:shared

Step 5: Set Up the Database

cd apps/server
npx prisma generate
npx prisma db push
cd ../..

Important: PostgreSQL must have the pgvector extension available. The Docker image pgvector/pgvector:pg16 includes it automatically. If using a local PostgreSQL install, see the pgvector installation guide.

Step 6: Seed Demo Users (Optional)

cd apps/server
npx tsx prisma/seed.ts
cd ../..

This creates demo accounts:

admin@novabyte.dev (admin role)
hr@novabyte.dev (HR role)
riya@novabyte.dev (employee role)

Step 7: Ingest the Knowledge Base

The RAG system requires the PS03 documents to be indexed before retrieval works:

cd apps/server
npm run ingest
cd ../..

This chunks the markdown files from docs/PS03/, generates embeddings via Hugging Face, and stores them in the knowledge_chunks table.

Step 8: Start the Application

# Run both server and frontend concurrently
npm run dev

Or start them separately in two terminals:

# Terminal 1 - Backend (http://localhost:4000)
npm run dev:server

# Terminal 2 - Frontend (http://localhost:3000)
npm run dev:web

Database Setup

The database uses PostgreSQL 16 with the pgvector extension for vector similarity search.

Schema (11 Tables)

Table	Description
`users`	User accounts with roles (admin, hr, employee)
`sessions`	Onboarding sessions with progress tracking
`personas`	Detected employee personas (role, experience level, tech stack)
`messages`	Chat message history (user + assistant messages)
`checklist_items`	Onboarding task items with status tracking
`knowledge_chunks`	Vector-indexed document chunks (384-dim embeddings via pgvector)
`hr_reports`	Generated completion reports (HTML/JSON/text formats)
`audit_logs`	System-wide audit trail
`integration_logs`	External integration action logs
`timeline_events`	Session event timeline
`unresolved_questions`	Unanswered questions queued for admin FAQ review

Useful Prisma Commands

cd apps/server

# Generate Prisma client after schema changes
npx prisma generate

# Push schema to database (no migration history)
npx prisma db push

# Reset database (WARNING: deletes all data)
npx prisma db push --force-reset

# Open Prisma Studio (database GUI on http://localhost:5555)
npx prisma studio

Running the Application

Root Scripts

Command	Description
`npm run dev`	Start both server (4000) and web (3000) concurrently
`npm run dev:server`	Start backend only
`npm run dev:web`	Start frontend only
`npm run build`	Build all packages (shared -> server -> web)
`npm run build:shared`	Build shared package only
`npm run build:server`	Build server only
`npm run build:web`	Build Next.js frontend only
`npm run lint`	Lint server and web
`npm run test`	Run backend tests (Vitest)

Workspace-Specific Scripts

# Backend
npm run dev --workspace=apps/server
npm run build --workspace=apps/server
npm run ingest --workspace=apps/server    # Ingest knowledge base
npm run test --workspace=apps/server

# Frontend
npm run dev --workspace=apps/web
npm run build --workspace=apps/web
npm run lint --workspace=apps/web

Docker

docker compose up --build              # Full stack
docker compose up -d postgres redis    # Infrastructure only

API Endpoints

Base URL: http://localhost:4000

Authentication (`/api/auth`)

Method	Endpoint	Description	Auth
POST	`/api/auth/register`	Register a new user	No
POST	`/api/auth/login`	Login (returns JWT token)	No
GET	`/api/auth/profile`	Get current user profile	Yes
PUT	`/api/auth/profile`	Update profile / upload avatar	Yes

Sessions (`/api/sessions`)

Method	Endpoint	Description	Auth
GET	`/api/sessions`	List user's onboarding sessions	Yes
POST	`/api/sessions`	Create a new onboarding session	Yes
GET	`/api/sessions/:id`	Get session details + checklist	Yes
PUT	`/api/sessions/:id/status`	Update session status	Yes
POST	`/api/sessions/:id/onboarding-profile`	Submit onboarding profile	Yes

Chat (`/api/chat`)

Method	Endpoint	Description	Auth
POST	`/api/chat`	Send a message (streaming response)	Yes
POST	`/api/chat/action`	Execute an action button	Yes
GET	`/api/chat/:sessionId`	Get chat history for a session	Yes

Admin (`/api/admin`)

Method	Endpoint	Description	Role
GET	`/api/admin/sessions`	List all sessions (filtered, paginated)	admin
GET	`/api/admin/sessions/:id`	Full session details with messages	admin
POST	`/api/admin/sessions/:id/action`	Approve / reject a session	admin
GET	`/api/admin/audit`	View audit log	admin

HR (`/api/hr`)

Method	Endpoint	Description	Role
GET	`/api/hr/reports`	List HR reports	hr, admin
POST	`/api/hr/reports/:sessionId`	Generate completion report	hr, admin
POST	`/api/hr/send-report`	Email report to HR	hr, admin

Knowledge (`/api/knowledge`)

Method	Endpoint	Description	Role
POST	`/api/knowledge/ingest`	Trigger knowledge base re-indexing	admin
GET	`/api/knowledge/chunks`	Search knowledge chunks	any
POST	`/api/knowledge/faq`	Submit an unanswered question	any

Verification (`/api/verify`)

Method	Endpoint	Description	Auth
POST	`/api/verify/submit`	Submit verification script output	Yes

Integrations (`/api/integrations`)

Method	Endpoint	Description	Auth
POST	`/api/integrations/github/:action`	GitHub actions (repo access, invite, create issue)	Yes
POST	`/api/integrations/slack/:action`	Slack actions (send message, interactive buttons)	Yes
POST	`/api/integrations/jira/:action`	Jira actions (create ticket)	Yes

Health Check

Method	Endpoint	Description
GET	`/health`	Server health status

A Postman collection is available at docs/postman_collection.json for API testing.

Agent System

OnboardIQ uses an MCP-style orchestrator pattern with 7 specialized AI agents that communicate via structured AgentMessage objects:

Agent	File	Purpose
PersonaAgent	`agents/persona-agent.ts`	Extracts structured persona (name, role, experience, tech stack) from user's first message via LLM
PlannerAgent	`agents/planner-agent.ts`	Generates a role-specific onboarding checklist (10-30 tasks) grounded in PS03 resources
RAGAgent	`agents/rag-agent.ts`	Retrieves relevant knowledge via vector similarity search, generates grounded LLM responses with source citations
ActionAgent	`agents/action-agent.ts`	Executes integration actions (GitHub repo access, Slack messages, Jira tickets) - mock or real
VerifierAgent	`agents/verifier-agent.ts`	Validates environment setup script outputs against verification criteria
ReportingAgent	`agents/reporting-agent.ts`	Compiles session data into HR completion reports (HTML/JSON/text)
KBAgent	`agents/index.ts`	Captures unanswered questions for admin FAQ review

How Agents Communicate

User Message → AgentOrchestrator.dispatch()
                    ├── PersonaAgent (first message only)
                    ├── PlannerAgent (after persona detected)
                    ├── RAGAgent (for knowledge queries)
                    ├── ActionAgent (for integration tasks)
                    ├── VerifierAgent (for setup verification)
                    └── ReportingAgent (on session completion)

RAG Pipeline

Ingestion: Markdown docs from docs/PS03/ are split into chunks (400 tokens, 50 token overlap), embedded via Hugging Face API (384-dim vectors), and stored in the knowledge_chunks pgvector table
Retrieval: User query is embedded → top-5 similar chunks retrieved via cosine distance (threshold >= 0.7)
Generation: Retrieved chunks are injected as context into the Groq LLM prompt → grounded response with source citations returned

RAG Config (from shared constants):

TOP_K = 5 — Number of chunks retrieved
SCORE_THRESHOLD = 0.7 — Minimum relevance score
CHUNK_SIZE_TOKENS = 400 — Target chunk size
CHUNK_OVERLAP_TOKENS = 50 — Overlap between chunks

WebSocket Events

Real-time communication uses Socket.io on the backend port (4000).

Connection

import { io } from 'socket.io-client';

const socket = io('http://localhost:4000', {
  auth: { token: 'your-jwt-token' }
});

Client → Server

Event	Payload	Description
`chat:message`	`{ sessionId, content }`	Send a chat message
`chat:action`	`{ sessionId, action }`	Click an action button
`checklist:update`	`{ itemId, status }`	Update checklist item status

Server → Client

Event	Payload	Description
`chat:stream`	`{ chunk }`	Streamed response token
`chat:response`	`{ message, sources }`	Full response with metadata and citations
`checklist:updated`	`{ item }`	Checklist item status changed
`checklist:progress`	`{ completed, total }`	Overall progress update
`session:updated`	`{ session }`	Session state change
`persona:detected`	`{ persona }`	Persona extraction result
`notification`	`{ type, message }`	Toast notification

VS Code Extension (USP)

Why It's a USP

Most onboarding platforms are browser-only — developers constantly switch between the onboarding portal and their IDE. OnboardIQ eliminates this friction with a native VS Code extension that brings the full onboarding experience into the editor:

Capability	How It Works
In-editor AI Chat	Chat with the onboarding agent in the VS Code sidebar — streamed token-by-token via WebSocket
Auto Tech Detection	Scans `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, Dockerfiles to auto-populate the onboarding profile
Environment Verification	Runs CLI checks (Node, npm, Git, Docker, Python) and auto-completes matching checklist tasks on the backend
Live Checklist Sync	Progress updates in real-time between the web app and extension — complete a task in VS Code, see it update on the web instantly
Workspace Doc Scanning	Reads README.md, CONTRIBUTING.md, and `docs/*/.md` to give the AI agent workspace context
Panel Mode	Open the onboarding UI as a full editor tab for a bigger view
Secure Auth	JWT tokens stored in VS Code's `SecretStorage` (OS keychain)

Extension Architecture

apps/vscode-ext/
├── src/
│   ├── extension.ts                  # Entry point — activates on startup
│   ├── providers/
│   │   └── chat-view-provider.ts     # WebView UI (sidebar + panel)
│   └── services/
│       ├── api.ts                    # HTTP client with SecretStorage token management
│       ├── auth.ts                   # Login / register / logout
│       ├── session.ts                # Session + checklist + chat (REST)
│       ├── socket.ts                 # Socket.io client for real-time streaming
│       ├── verifier.ts              # Environment CLI checks
│       └── workspace-scanner.ts     # Tech stack + docs auto-detection
├── package.json                      # Extension manifest (commands, views, config)
├── tsconfig.json
└── esbuild.js                        # Build config (esbuild bundler)

Extension Metadata:

Name: onboardiq
Display Name: OnboardIQ - Developer Onboarding Agent
Publisher: hackncrack
Activation: onStartupFinished (activates when VS Code finishes loading)
Min VS Code: ^1.85.0
Configuration: onboardiq.serverUrl (default: http://localhost:4000)

Complete User Workflow

┌─────────────────────────────────────────────────────────────────────┐
│                    VS CODE EXTENSION WORKFLOW                       │
└─────────────────────────────────────────────────────────────────────┘

STEP 1: ACTIVATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  VS Code starts → extension activates (onStartupFinished)
    ├── Initializes 6 services (API, Auth, Session, Socket, Scanner, Verifier)
    ├── Creates status bar item: "$(checklist) OnboardIQ"
    ├── Registers WebView provider for sidebar panel
    ├── Registers 6 commands
    └── Shows welcome notification (first install only)
                                    │
                                    ▼
STEP 2: OPEN EXTENSION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  User clicks OnboardIQ icon in Activity Bar → sidebar opens
    ├── ApiClient.init() → loads saved token from SecretStorage
    ├── Validates token with GET /api/auth/me
    └── If NOT authenticated → shows Login / Register form
        If authenticated → skips to Step 4
                                    │
                                    ▼
STEP 3: LOGIN / REGISTER
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  User enters credentials in the sidebar form
    ├── POST /api/auth/login (or /register)
    ├── JWT token stored in VS Code SecretStorage (OS keychain)
    └── User data sent to webview → UI updates
                                    │
                                    ▼
STEP 4: LOAD SESSION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SessionService.getOrCreateActiveSession()
    ├── Finds existing active session OR creates a new one
    ├── Fetches chat messages + checklist from backend
    ├── SocketService.connect(sessionId) → WebSocket connection
    │   ├── auth: { token } in handshake
    │   ├── emit 'join:session' to subscribe to session room
    │   └── Register listeners: chat:stream, chat:response,
    │       checklist:progress, persona:detected, notification
    └── If no profile submitted → shows Profile View
        If profile exists → shows Main View (Chat + Tasks + Verify)
                                    │
                                    ▼
STEP 5: SUBMIT ONBOARDING PROFILE (first time only)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Profile form with 3 fields:
    ├── Role dropdown:  Backend | Frontend | DevOps | Full Stack
    ├── Experience dropdown:  Intern | Junior | Senior
    └── Tech stack chips:  manual input + auto-detect via [Scan Workspace]

  [Scan Workspace] button:
    ├── WorkspaceScanner reads package.json, requirements.txt, go.mod, etc.
    ├── Detects: "Node.js", "React", "TypeScript", "Docker", ...
    └── Auto-populates tech stack chips (user can add/remove)

  [Start] → POST /api/sessions/{id}/profile
    ├── Backend runs PersonaAgent → extracts structured persona
    ├── Backend runs PlannerAgent → generates role-specific checklist
    └── Returns: { persona, checklist, progress, welcomeMessage }
        → Switches to Main View
                                    │
                                    ▼
STEP 6: MAIN VIEW — Three Tabs
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ┌───────────────────────────────────────────────┐
  │  [Chat]    [Tasks]    [Verify]                │
  ├───────────────────────────────────────────────┤
  │                                               │
  │  Tab content area                             │
  │                                               │
  └───────────────────────────────────────────────┘

  CHAT TAB:
    User types message → SocketService.sendMessage()
      → socket.emit('chat:message', { sessionId, message })
      → Backend processes with RAG Agent + knowledge retrieval
      → socket receives 'chat:stream' events (token by token)
         → Webview appends text with blinking cursor indicator
      → socket receives 'chat:response' (final message + sources)
         → Indicator removed, message finalized, scroll to bottom

  TASKS TAB:
    ├── Progress bar: "45% complete (9/20 tasks)"
    ├── Tasks grouped by category (Setup, Dependencies, Config, ...)
    ├── Each task shows status icon:
    │   ✓ completed (green)   ▶ in-progress (blue)
    │   ✕ blocked (red)       – skipped (muted)
    │   ○ pending (default)
    ├── Click task → toggles: pending → in_progress → completed
    │   → PUT /api/sessions/{id}/checklist/{taskId}
    │   → Backend broadcasts checklist:progress via WebSocket
    │   → Progress bar + VS Code status bar update in real-time
    └── Status bar shows: "$(checklist) OnboardIQ: 45% (9/20)"

  VERIFY TAB:
    [Run Verification] button
    ├── Runs 4 verification scripts in parallel:
    │   ┌────────────────────┬──────────────────────────────────────┐
    │   │ verify_node_setup  │ node --version, npm -v, pnpm -v     │
    │   │ verify_git_config  │ git --version, user.name, user.email │
    │   │ verify_docker_setup│ docker --version, compose version    │
    │   │ verify_python_setup│ python3 --version, pip3 --version    │
    │   └────────────────────┴──────────────────────────────────────┘
    ├── Each check: 10-second timeout, captures stdout/stderr
    ├── Results displayed with ✅ / ❌ per check
    ├── POST /api/verify → backend auto-completes matching tasks
    └── Example output:
         ✅ Node.js version: v20.11.0
         ✅ npm version: 10.2.4
         ❌ pnpm version: Not found
         ✅ Git version: 2.43.0
         ✅ Git user.name: John Doe
         ✅ Docker version: 24.0.7
                                    │
                                    ▼
STEP 7: PANEL MODE (Optional)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  User clicks "Open in editor panel"
    → Creates full WebviewPanel in the editor area
    → Same UI and functionality as sidebar, but larger
    → Both views stay synchronized via shared services
                                    │
                                    ▼
STEP 8: LOGOUT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  User clicks Logout
    ├── AuthService.logout() → clears token from SecretStorage
    ├── SocketService.disconnect() → closes WebSocket
    ├── Status bar hidden
    └── Webview returns to Login form

Extension Development Setup

cd apps/vscode-ext
npm install
npm run compile

Then press F5 in VS Code to launch the Extension Development Host.

Build tool: esbuild (fast bundling to dist/extension.js)
Configuration: Set onboardiq.serverUrl in VS Code settings to point to your backend (defaults to http://localhost:4000)

Authentication and Roles

The system uses JWT-based authentication with role-based access control (RBAC).

Roles

Role	Access
`employee`	Own session, chat, checklist, verification
`hr`	View sessions, approve completions, generate/send reports
`admin`	Full system access, audit logs, knowledge management

Auth Flow

User registers or logs in → receives JWT token
Token stored in localStorage, sent via Authorization: Bearer <token> header
WebSocket auth via { auth: { token } } in handshake
Passwords hashed with bcrypt (12 rounds)
Tokens expire after 7 days (configurable via JWT_EXPIRES_IN)

Frontend Routes

Route	Description
`/`	Landing page with login/register
`/onboard`	Employee onboarding chat + checklist
`/admin`	Admin/HR dashboard

Knowledge Base

The application is built around the PS03 resource pack in docs/PS03/:

File	Content
`company_overview.md`	Company background and culture
`engineering_standards.md`	Coding standards and practices
`architecture_documentation.md`	System architecture
`setup_guides.md`	Development environment setup
`policies.md`	Company policies
`org_structure.md`	Organization structure
`onboarding_faq.md`	Frequently asked questions
`onboarding_checklists.md`	Role-based onboarding tasks
`starter_tickets.md`	First tasks for new developers

The backend uses these resources for:

RAG retrieval — contextual answers grounded in company docs
Checklist generation — role-specific tasks from onboarding checklists
Task guidance — step-by-step help from setup guides and starter tickets
HR reporting — completion metrics from session state and checklist progress

Document Tier System

Tier 1 (Searchable): setup_guides, onboarding_faq, architecture_documentation — directly retrieved by RAG
Tier 2 (Supporting): Internal reference docs — used for context enrichment
Tier 3 (Hidden): Email templates, employee personas — never exposed to users

Testing

# Run all backend tests (Vitest)
npm run test

# Run in watch mode
cd apps/server
npx vitest --watch

Troubleshooting

`pgvector` extension not found

If you see an error about the vector type not existing:

# Connect to PostgreSQL and enable pgvector
psql -U postgres -d onboardiq
CREATE EXTENSION IF NOT EXISTS vector;

Or use the Docker image pgvector/pgvector:pg16 which includes it.

Server says `KNOWLEDGE_LOCAL_PATH does not exist`

Set in .env:

KNOWLEDGE_LOCAL_PATH=docs/PS03

And run from the repository root.

Login or register fails with database errors

cd apps/server
npx prisma db push
npx prisma generate

License

This project is private and proprietary.

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
apps		apps
docker		docker
docs		docs
packages/shared		packages/shared
scripts		scripts
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml
tsconfig.base.json		tsconfig.base.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation