4pplicant

AI-Powered Job Application Automation System

An intelligent job application automation platform that helps users discover jobs on LinkedIn and streamline the application process through AI-powered document generation and smart form filling.

---

Overview

4pplicant is a comprehensive job application automation system that combines:

• SimplifiedApp Dashboard: Job management and application processing interface (Next.js)
• Chrome Extension: Real-time job description and form field capture
• Job Collector Agent: Automated LinkedIn job scraping with intelligent pagination
• AI Agents: Document generation (CV, cover letters) and job analysis

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                      4pplicant System                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────┐        ┌──────────────────┐               │
│  │ SimplifiedApp│◄──────►│Chrome Extension  │               │
│  │  Dashboard   │  APIs  │(Job/Form Capture)│               │
│  │  (Next.js)   │        │                  │               │
│  └──────────────┘        └──────────────────┘               │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────────────────────┐                    │
│  │        PostgreSQL Database          │                    │
│  │   - Jobs, Profiles, CV, Covers      │                    │
│  └─────────────────────────────────────┘                    │
│         │                                                    │
│         ▼                                                    │
│  ┌─────────────────────────────────────┐                    │
│  │          AI Agents                  │                    │
│  │  - Job Collector (LinkedIn)         │                    │
│  │  - CV Writer (Claude/GPT-4)         │                    │
│  │  - Cover Letter Writer              │                    │
│  │  - Job Analysis                     │                    │
│  └─────────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘

---

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Chrome browser (for extension)
• npm or yarn

Installation

# Clone repository
git clone <repository-url>
cd 4pplicant-1

# Install dependencies
npm install

# Setup database
npm run db:push

# Start SimplifiedApp dashboard
npm run dev

The dashboard will start on port 3000 (or next available port). Open http://localhost:3000 in your browser.

Environment Setup

Create .env.local file:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/4pplicant"

# Authentication (Clerk)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="your-key"
CLERK_SECRET_KEY="your-key"

# AI Providers
OPENAI_API_KEY="your-key"
ANTHROPIC_API_KEY="your-key"

# Storage (Supabase)
NEXT_PUBLIC_SUPABASE_URL="your-url"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-key"
SUPABASE_SERVICE_ROLE_KEY="your-key"

Chrome Extension Setup

1. Navigate to chrome://extensions/
2. Enable "Developer mode" (top right)
3. Click "Load unpacked"
4. Select the /chrome-extension/ directory
5. Extension icon should appear in Chrome toolbar

---

Core Components

1. SimplifiedApp Dashboard

Location: /src/components/SimplifiedApp.tsx

The main user interface for job management and application processing.

Key Features:

• Job collection configuration and monitoring
• Job list with filtering and sorting
• Document generation (CV and cover letters)
• Form data review and management
• Real-time progress updates via Server-Sent Events (SSE)

Tech Stack: Next.js 14, React, TypeScript, Tailwind CSS, Shadcn/ui, Clerk Auth

Main Routes:

• / - SimplifiedApp dashboard (default landing page)
• /api/jobs/* - Job management endpoints
• /api/agent/* - Job collector agent endpoints
• /api/generate-simple - Document generation endpoint

2. Chrome Extension

Location: /chrome-extension/

Browser extension for capturing job descriptions and form fields in real-time.

Key Features:

• Job Description Capture: Select and capture job descriptions from any website
• Form Field Auto-capture: Detects and captures form fields as you type
• Smart Autofill: Pre-fill application forms using saved user data
• Document Generation: Trigger CV/cover letter generation from the extension
• Multi-select Support: Select multiple elements for complex job descriptions

Architecture (Refactored October 2024):

• Content scripts organized into 19 modular files (<350 lines each)
• Main coordinator: content/content.js (503 lines)
• UI overlay: content/overlay-ui.js (494 lines)
• Modules: AI processing, documents, forms, selection, UI, utilities

Tech Stack: Manifest V3, ES6 Modules, Playwright-style selectors

See Extension Documentation →

3. Job Collector Agent

Location: /src/lib/agents/linkedin-job-collector/

Automated LinkedIn job scraping with intelligent pagination and duplicate detection.

Key Features:

• Configurable search parameters (keywords, locations, job quantity)
• Smart recovery from LinkedIn anti-bot measures
• Offset detection (stops when no new jobs found)
• Keyword/location rotation for diverse results
• Real-time progress streaming to dashboard

Configuration Options:

• Job quantity limits
• Delay ranges (between jobs, between pages)
• Pagination limits per search
• Custom keywords and locations
• Rotation strategies

4. AI Agents

Location: /src/lib/

Intelligent automation agents for document generation and job analysis.

Agents:

• CV Writer (tools/cv-writer-agent.ts) - Generates tailored CVs based on job descriptions
• Cover Letter Writer (tools/cover-letter-writer.ts) - Creates customized cover letters
• Job Analysis (agents/job-analysis-agent.ts) - Extracts structured data from job descriptions
• Form Autofill (services/FormAutofillService.ts) - Intelligent form field matching

AI Models: Claude (Anthropic), GPT-4 (OpenAI)

---

Integration Flow

Job Application Workflow

1. Job Discovery
   └─→ Job Collector Agent scrapes LinkedIn
   └─→ Jobs saved to database with URLs and descriptions

2. Job Description Capture (Alternative)
   └─→ Chrome Extension captures job description from any site
   └─→ Job saved to database

3. Document Generation
   └─→ User clicks "Generate Documents" in SimplifiedApp
   └─→ AI analyzes job description
   └─→ CV and cover letter generated (streaming via SSE)
   └─→ Documents saved to Supabase storage

4. Form Filling (Chrome Extension)
   └─→ Extension detects application form
   └─→ Auto-captures fields as user types
   └─→ Builds master template of user data
   └─→ On return visits: auto-fills form using fuzzy matching

5. Application Submission
   └─→ User opens job URL from SimplifiedApp
   └─→ Chrome Extension auto-fills form
   └─→ User reviews and submits manually

SimplifiedApp ↔ Chrome Extension Integration

Communication: REST APIs + Port Discovery

Chrome Extension discovers Next.js server:

// Extension tries ports 3000-3010 until /api/health responds
for (let port = 3000; port <= 3010; port++) {
  const response = await fetch(`http://localhost:${port}/api/health`);
  if (response.ok) return port;
}

Extension calls SimplifiedApp APIs:

// Capture job description
POST /api/extension/process-job
{
  url: "https://...",
  jobDescriptionHtml: "...",
  jobTitle: "...",
  companyName: "..."
}

// Capture form field
POST /api/extension/capture-field
{
  jobId: "123",
  fieldName: "email",
  value: "user@example.com",
  ...
}

// Get autofill data
GET /api/extension/autofill-data?jobId=123

// Get document status
GET /api/extension/documents?jobId=123

---

Project Structure

4pplicant-1/
├── src/                          # Next.js application
│   ├── app/
│   │   ├── api/
│   │   │   ├── jobs/           # Job management APIs
│   │   │   ├── agent/          # Job collector agent APIs
│   │   │   ├── extension/      # Chrome Extension integration
│   │   │   └── generate-simple # Document generation (SSE)
│   │   └── layout.tsx
│   ├── components/
│   │   ├── SimplifiedApp.tsx   # Main dashboard (843 lines)
│   │   ├── CollectedJobsPanel.tsx
│   │   └── ...
│   └── lib/
│       ├── agents/             # Job collector, job analysis
│       ├── tools/              # CV writer, cover letter writer
│       ├── services/           # Form autofill, fuzzy matching
│       └── prisma/             # Database client
│
├── chrome-extension/           # Chrome Extension
│   ├── manifest.json
│   ├── content/
│   │   ├── content.js         # Main coordinator (503 lines)
│   │   ├── overlay-ui.js      # UI overlay (494 lines)
│   │   ├── ai-processing/     # AI integration (2 modules)
│   │   ├── documents/         # Document polling (2 modules)
│   │   ├── forms/             # Autofill (1 module)
│   │   ├── selection/         # Element highlighting (1 module)
│   │   ├── ui/                # UI components (3 modules)
│   │   └── utils/             # Utilities (2 modules)
│   ├── background/
│   │   └── service-worker.js
│   └── popup.html
│
├── prisma/                    # Database schema
│   └── schema.prisma
│
├── _docs/                     # Documentation
│   ├── user_manual/          # User guides
│   ├── handoff/              # Session notes
│   └── architecture/         # Architecture docs
│
└── CLAUDE.md                 # Project instructions for AI

---

Database Schema

Key Tables

Job

• Job listings from LinkedIn and other platforms
• Status tracking (NEW, APPLIED, BLOCKED_BY_LOGIN, etc.)
• Job description HTML and structured JSON data
• Links to CV and cover letter
• Captured application form inputs

UserProfile

• User authentication (Clerk integration)
• Master application form template
• Job collector agent configuration
• Links to all jobs, CVs, and cover letters

CV / CoverLetter

• Generated documents (one per job)
• File path in Supabase storage
• Creation timestamps

---

Configuration

Job Collector Agent Configuration

Configure via SimplifiedApp dashboard or UserProfile.agentConfig:

{
  "jobQuantity": 100,
  "noFocusMode": true,
  "delayBetweenJobsMin": 2000,
  "delayBetweenJobsMax": 5000,
  "delayBetweenPagesMin": 3000,
  "delayBetweenPagesMax": 7000,
  "maxPagesPerSearch": 5,
  "jobsPerCombination": 20,
  "useRotationStrategy": true,
  "enableSmartRecovery": true,
  "enableOffsetDetection": true,
  "customKeywords": "software engineer, frontend developer",
  "customLocations": "San Francisco, New York",
  "useCustomSearch": false
}

Master Form Template

Captured form fields stored in UserProfile.masterApplicationFormInputs:

{
  "email": "user@example.com",
  "phone": "+1234567890",
  "firstName": "John",
  "lastName": "Doe",
  "linkedinUrl": "https://linkedin.com/in/johndoe",
  "resume": "path/to/resume.pdf",
  ...
}

Chrome Extension uses fuzzy matching to auto-fill forms based on this template.

---

API Endpoints

Job Management

• GET /api/jobs - List jobs (with filters)
• GET /api/jobs/[id] - Get single job
• POST /api/jobs - Create job
• PATCH /api/jobs?id=[id] - Update job
• DELETE /api/jobs?id=[id] - Delete job
• POST /api/jobs/navigate - Get job URL for navigation

Job Collector Agent

• GET /api/agent/collect-dashboard - Start agent (SSE stream)
• POST /api/agent/stop - Stop running agent
• GET /api/agent-config - Get agent configuration
• PUT /api/agent-config - Update agent configuration

Document Generation

• POST /api/generate-simple - Generate CV & cover letter (SSE stream)

Chrome Extension

• GET /api/health - Health check (for port discovery)
• POST /api/extension/capture-field - Capture form field
• POST /api/extension/process-job - Process job description
• POST /api/extension/validate-selector - Validate CSS selector
• GET /api/extension/autofill-data - Get autofill data
• GET /api/extension/documents - Get document generation status

---

Development

Running Tests

# Run Next.js in development mode
npm run dev

# Run database migrations
npm run db:push

# Run Chrome Extension tests
cd chrome-extension
npm test

Code Quality Standards

• File size target: 150-250 lines per file
• Maximum file size: 350 lines (exceptions: main orchestrators up to 600 lines)
• Single responsibility: Each file should have one focused purpose
• No test/debug files in root: Use scripts/debug/ or delete after use
• Clear naming conventions: PascalCase for classes, kebab-case for utilities

See CLAUDE.md for complete code quality guidelines.

Debugging Tips

SimplifiedApp not working?

• Check browser console and Network tab
• Verify environment variables in .env.local
• Check database connection

Chrome Extension not working?

• Right-click extension icon → "Inspect popup" for background console
• Check page console for content script logs
• Verify Next.js server is running (extension needs it for APIs)

Database issues?

• Run npm run db:push to sync schema
• Check DATABASE_URL in .env.local
• Ensure PostgreSQL is running

---

Documentation

• Project Instructions (for AI)
• Chrome Extension Architecture
• User Manuals
• Architecture Documentation

---

Legacy Systems

Previous versions included:

• WR173R Dashboard - Original job management UI
• UJAP Configuration Tool - Platform adapter configuration tool

These systems were archived to the archive/wr173r-ujap-legacy branch in November 2024. They are preserved for reference but are no longer part of the active codebase.

---

Contributing

1. Follow code quality standards in CLAUDE.md
2. Update CLAUDE.md for significant architectural changes
3. Add tests for new features
4. Keep files under 350 lines
5. Use conventional commits

---

License

[Your License Here]

---

Support

For issues or questions:

1. Check CLAUDE.md for project context
2. Review relevant README files in subdirectories
3. Check browser console and server logs
4. Ensure all prerequisites are met (Node.js, PostgreSQL, environment variables)

---

Built with Next.js, Playwright, Claude, and GPT-4