Table of Contents

Engineering Onboarding Guide

Welcome to Qwestly! This guide will help you get up and running as an engineer on our team.

Company Overview

Qwestly is transforming the hiring landscape through AI-driven job matching. We're building a passive job marketplace that connects top talent with forward-thinking companies, eliminating the desperation cycle of traditional job searching.

Our Mission

Replace the current hiring workflow with an AI-driven marketplace where hiring managers and candidates each have AI assistants that assess compatibility, communicate autonomously, and report back when matches are found.

Team Structure

Leadership:

Adam Boender - CEO & Co-founder (Product/Business)
Dominick Pham - CTO & Co-founder (Engineering)

Engineering Team:

1 Full-time engineer
Contractors for specialized work (UX design, etc.)

Technology Stack

Frontend Applications

Framework: Next.js 15+ with TypeScript
Styling: Tailwind CSS with custom component library
State Management: Zustand, Jotai for specific use cases
UI Components: Radix UI primitives with custom styling
Authentication: Auth0

Backend Services

Primary API: Python (FastAPI, hosted on Vercel)
Database: MongoDB (Atlas)
File Storage: AWS S3
Email: SendGrid

AI/ML Stack

LLM Framework: LangChain with multiple providers
AI Providers: Anthropic Claude, OpenAI, Google Vertex AI, Groq, Mistral
Vector Storage: Supabase
Document Processing: PyPDF, Mammoth (for Word docs)

Development Tools

Package Manager: npm
Testing: Vitest (unit), Playwright (e2e), Jest (legacy)
Linting: ESLint + Prettier
Version Control: Git with GitHub
CI/CD: GitHub Actions + Vercel
Design System: Custom Qwestly UI component library

Repository Architecture

We operate separate repositories (not a monorepo) for clear separation of concerns:

Core Repositories

qwestly-app - Main application portal (hiring managers)
candidate - Candidate-facing portal
public-site - Public marketing website (qwestly.com)
api-python - Python backend for document processing and RAG
qwestly-ui - Shared component library
qwestly-docs - Engineering documentation (this repo)

Workspace Structure

/Users/dominick/Work/qwestly-workspace/
├── qwestly-app/          # Main app
├── candidate/            # Candidate portal  
├── public-site/          # Marketing site
├── api-python/           # Python backend
├── qwestly-ui/           # Component library
├── qwestly-docs/         # Documentation
├── assets/               # Design assets
├── compliance/           # SOC2 policies
└── docs/                 # Company documents

Development Environment Setup

Prerequisites

Node.js 18+ (use nvm for version management)
npm (package manager)
Python 3.9+ (for api-python)
Git with SSH keys configured
VS Code (recommended editor)

Initial Setup

Clone repositories (you'll need access to each):

cd ~/Work/qwestly-workspace/
git clone git@github.com:qwestly/qwestly-app.git
git clone git@github.com:qwestly/candidate.git
git clone git@github.com:qwestly/public-site.git
git clone git@github.com:qwestly/api-python.git
git clone git@github.com:qwestly/qwestly-ui.git
git clone git@github.com:qwestly/qwestly-docs.git

Install dependencies for each Node.js project:

# For each repository
cd qwestly-app && npm install
cd ../candidate && npm install
cd ../public-site && npm install
cd ../qwestly-ui && npm install

Python environment setup:

cd api-python
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt

Environment Variables

Each repository requires environment variables. Request access to:

Development secrets from Dominick
Auth0 credentials for authentication
Database connection strings
API keys for AI providers
AWS credentials for S3 access

Development Workflow

Start development servers:

# Main app (usually port 3000)
cd qwestly-app && npm run dev

# Candidate app (usually port 3001)  
cd candidate && npm run dev

# Python API (usually port 8000)
cd api-python && python -m uvicorn api.main:app --reload

Component library development:
```
cd qwestly-ui && npm run dev
```

Code Standards & Practices

Code Style

TypeScript everywhere (strict mode)
Functional components with hooks
Composition over inheritance
Consistent naming conventions (camelCase for JS, kebab-case for files)

Git Workflow

Feature branches from main
Descriptive commit messages following conventional commits
Pull requests required for all changes
Code review required before merge (minimum 1 approver)

Testing Requirements

Unit tests for utility functions and complex logic
Component tests for UI components
E2E tests for critical user journeys
Run tests locally before pushing

Security Practices

Never commit secrets (use .env files)
Dependency scanning via Trivy (automated)
Secret scanning via TruffleHog (automated)
Regular security updates

Architecture Patterns

Frontend Architecture

Component-based architecture with Radix UI primitives
Custom hooks for shared logic
Server components where possible (Next.js App Router)
Client components for interactivity
Atomic design principles in component library

API Design

RESTful endpoints where appropriate
GraphQL for complex data fetching (if implemented)
Proper error handling with meaningful messages
Request/response validation with Zod (frontend) and Pydantic (backend)

Data Flow

Server-side rendering for SEO and performance
Client-side state for user interactions
Optimistic updates for better UX
Error boundaries for graceful error handling

AI Integration Patterns

LangChain Usage

Modular chain composition for complex workflows
Provider abstraction for easy model switching
Prompt engineering best practices
Cost optimization through smart provider routing

Document Processing

PDF extraction via PyPDF2 in Python backend
Word document processing via Mammoth
Text chunking for RAG applications
Vector embeddings stored in Supabase

Deployment & CI/CD

Deployment Strategy

Vercel for all frontend applications (automatic deployment)
GitHub Actions for security scanning and compliance
Preview deployments for all pull requests
Production deployment on merge to main

CI/CD Pipeline

Pull Request → Security Scan → Code Quality → Vercel Preview
     ↓
Peer Review + Approval  
     ↓
Merge to Main → Security Scan → Vercel Production Deploy

Environment Management

Development - Local development with hot reload
Preview - Automatic Vercel preview deploys for PRs
Production - Main branch auto-deploys to production

SOC2 Compliance

As a startup handling sensitive data, we maintain SOC2 compliance:

Key Requirements

2FA enabled on all GitHub accounts
Branch protection rules enforced
Code review required for all changes
Security scanning on every commit
Audit trails maintained for all deployments

Your Responsibilities

Enable 2FA on GitHub account
Follow security practices (no hardcoded secrets)
Participate in code reviews
Report security concerns immediately

Common Development Tasks

Adding a New Feature

Create feature branch from main
Implement feature with tests
Update documentation if needed
Create pull request with description
Address code review feedback
Merge after approval

Adding a New Dependency

Evaluate security and licensing
Add via npm (not yarn)
Update package.json and lock file
Document any breaking changes

Debugging Issues

Check browser console and network tab
Review server logs (Vercel Functions tab)
Use debugger in VS Code
Check environment variables
Verify database connections

Performance Optimization

Use Next.js built-in optimization
Implement proper caching strategies
Optimize images with Next.js Image
Monitor Core Web Vitals
Use Vercel Analytics for insights

Resources & Learning

Internal Documentation

CI/CD Implementation - /docs/CI-CD/index.md
SOC2 Compliance - /docs/SOC2/index.md
Component Library - qwestly-ui/README.md

External Resources

Next.js Documentation - https://nextjs.org/docs
Tailwind CSS - https://tailwindcss.com/docs
Radix UI - https://www.radix-ui.com/
LangChain - https://docs.langchain.com/
FastAPI - https://fastapi.tiangolo.com/

AI/LLM Resources

Anthropic Claude - https://docs.anthropic.com/
OpenAI API - https://platform.openai.com/docs
Prompt Engineering - https://docs.anthropic.com/claude/docs/prompt-engineering

Team Communication

Daily Practices

Async-first communication (we're a small team)
GitHub for technical discussions (use issues and PRs)
Slack for quick coordination (if implemented)
Regular check-ins with team leads

Code Reviews

Constructive feedback focused on code quality
Security-minded reviews (look for potential issues)
Performance considerations
Documentation updates when needed

Getting Help

Technical Issues

Check existing documentation first
Search GitHub issues for similar problems
Ask team members via appropriate channels
Create GitHub issue for bugs or feature requests

Access Issues

Repository access - Contact Dominick
Environment variables - Contact Dominick
Third-party services - Contact Adam or Dominick

Escalation Path

Team member for quick questions
Dominick (CTO) for technical architecture
Adam (CEO) for product and business questions

First Week Checklist

Day 1

Day 2-3

Read through codebase overview
Review component library
Understand AI integration patterns
Set up VS Code with recommended extensions

Day 4-5

Pick up first small task/bug fix
Submit first pull request
Complete code review cycle
Deploy to preview environment

End of Week 1

Understand development workflow
Know how to run tests
Familiar with deployment process
Connected with team members

Long-term Learning Goals

Technical Growth

Master our AI integration patterns
Understand SOC2 compliance requirements
Contribute to architecture decisions
Mentor future team members

Product Understanding

Deep understanding of hiring pain points
User empathy for both candidates and hiring managers
Market dynamics and competitive landscape
Business model and revenue streams

Welcome to the team! We're excited to have you join us in transforming the hiring landscape. If you have any questions not covered in this guide, don't hesitate to reach out.

Document Owner: Dominick Pham, CTO
Last Updated: July 1, 2025
Next Review: October 1, 2025

_private/qwestly-docs/Engineering/Onboarding.md