How mukul2345/linkedin-job-copilot works
1. Primary architecture is a Chrome extension with a Firebase backend
The active product is the extension/ tree: a Chrome Manifest V3 extension written in vanilla JavaScript. It depends on Firebase client SDKs bundled under extension/assets/lib/ for authentication and Firestore access. The backend lives in functions/ as Firebase Cloud Functions on Node.js 20.
2. The extension is split into clear runtime surfaces
There are three main extension execution contexts: the popup UI (extension/ui/), the content script injected into LinkedIn pages (extension/content/), and the background service worker (extension/background/service-worker.js). The popup is the user control plane; the content script is the page-integrated bridge; the service worker handles background orchestration and extension events.
3. Bot automation is the core domain subsystem
The automation logic is concentrated in extension/modules/bot/. bot-core.js coordinates the job-application loop, job-processor.js handles Easy Apply flows, form-filler.js fills fields, hr-outreach.js and recruiter-msg.js handle messaging, and safety.js enforces throttling and stop conditions. selectors.js centralizes LinkedIn DOM selectors, which is important because the bot is tightly coupled to LinkedIn’s page structure.
4. Application data and user state are persisted in Firestore
The extension/modules/database/ layer abstracts Firestore CRUD and sync. user-repository.js stores profile/settings, usage-repository.js tracks daily usage and limits, and sync-service.js bridges local state with cloud state. This repository layer is the boundary between UI/bot behavior and cloud persistence.
5. Authentication is Firebase Auth, not local-only state
extension/modules/auth/auth-service.js handles sign-up, login, logout, and typed user ID generation. User identity and role state are therefore centralized in Firebase, allowing plan enforcement and admin behavior to be decided server-side or repository-side rather than being hardcoded in the extension.
6. Subscription enforcement is a distinct subsystem
extension/modules/subscription/ contains plan definitions, plan validation, and payment entry points. plan-config.js defines free/pro tiers and pricing, plan-service.js evaluates access and admin bypass behavior, and payment-service.js integrates Cashfree checkout. This subsystem gates the bot’s capabilities, especially app/message quotas and AI features.
7. The backend functions are payment and policy authority
functions/index.js and supporting files in functions/lib/ implement the backend side of subscription and policy logic: payment session creation, webhook handling, verification, deduplication, normalization, scoring, search, tracker, and visa-related logic. This backend is the trusted boundary for payment events and any server-side plan activation or user state changes.
8. AI is optional and separated from the core bot loop
The extension’s modules/ai/ and modules/fit-score/ encapsulate AI-assisted responses and job-fit evaluation, while backend functions/lib/ai-client.js supports server-side AI-related logic. The README makes clear AI answers are optional and tied to Pro access, so AI is a feature gate rather than a prerequisite for automation.
9. The bot integrates safety and compliance controls
Safety is an explicit module, not just a UI warning. extension/modules/bot/safety.js implements adaptive delays, daily caps, and stop thresholds; extension/modules/shared/filters.js, validators.js, and hash.js support filtering and deduplication. These controls are important architectural boundaries because they constrain how aggressively the automation can interact with LinkedIn.
10. UI is a lightweight control dashboard
The popup (popup.html, popup.js, popup.css) is the primary operator interface for auth, settings, and status. upgrade-modal.js and pricing-screen.js render plan upsell and pricing views. tracker-ui.js and jobs-tracker-handlers.js add job tracking and user-facing workflow support inside the extension, but they remain thin over the underlying services.
11. External systems materially shape the architecture
The extension runs against LinkedIn DOM and workflows, so selectors and browser automation are central. Firebase Authentication, Cloud Firestore, and Cloud Functions provide identity, persistence, and trusted backend execution. Cashfree is the payment provider, and Chrome Web Store is the extension distribution channel. GitHub Pages hosts the marketing/privacy site in docs/.
12. The repository includes a separate set of serverless and admin utilities
scripts/ contains operational helpers like seeding users and checking Firestore state. Firebase config files (firebase.json, firestore.rules, firestore.indexes.json, storage.rules) define deployment and access boundaries. These files matter for the architecture diagram because they show the system’s trust and deployment edges.
13. There is a legacy Python automation stack, but it is not the main product path
The modules/, scraper/, runAiBot.py, and app.py tree represents an older Python-based automation/scraping system, with some deprecated code explicitly marked under modules/__deprecated__/. For an architecture diagram of the current product, this should be shown as legacy/deprecated and separated from the active Chrome extension + Firebase architecture.
14. Testing is broad and module-oriented
tests/ contains Jest/jsdom tests for background behavior, bot modules, subscription logic, safety, tracker UI, and repository layers. This indicates the codebase is organized as independently testable subsystems rather than one monolithic browser script, which is useful when mapping module boundaries in a diagram.
Main entry points: index.js Cloud Functions · firestore-service.js Firestore Layer · popup.html Popup UI · bot-core.js Bot Core
Components 25
Chrome Extension
Active Manifest V3 extension runtime and feature modules.
- Popup UI · Lightweight control dashboard for auth, settings, status, and upsell flows.
extension/ui/popup.html - Content Script · Injected LinkedIn page integration for DOM interaction and helper overlays.
extension/content/content.js - Service Worker · Background event handling and coordination across extension surfaces.
extension/background/service-worker.js - Bot Core · Coordinates the job-application loop and bot execution flow.
extension/modules/bot/bot-core.js - Apply Flows · Handles Easy Apply processing, form filling, and outreach message generation.
extension/modules/bot/job-processor.js - Safety Controls · Adaptive delays, daily caps, and stop conditions for compliant automation.
extension/modules/bot/safety.js - LinkedIn Selectors · Centralized LinkedIn DOM selectors and page structure coupling.
extension/modules/bot/selectors.js - Auth Service · Sign-up, login, logout, and typed user identity management.
extension/modules/auth/auth-service.js - Firestore Layer · Firestore CRUD, caching, sync, and user/usage persistence boundary.
extension/modules/database/firestore-service.js - Plan Service · Plan definitions, access checks, admin bypass, and payment entry points.
extension/modules/subscription/plan-service.js - AI Services · Optional response and fit-score features gated by higher plans.
extension/modules/ai/ai-service.js - Tracker · Job tracking, user-facing tracker UI, and status workflows.
extension/modules/tracker/tracker-service.js - Resume Service · Resume tailoring and upload support used by application flows.
extension/modules/resume/resume-service.js - Search Service · Search and discovery logic supporting job finding and filtering.
extension/modules/search/search-service.js - Visa Service · Visa-related logic that influences matching and application decisions.
extension/modules/visa/visa-service.js
Firebase Backend
Trusted cloud services for auth, persistence, and policy.
- Cloud Functions · Trusted backend entry points for payments, policy, search, scoring, and sync.
functions/index.js - Policy Helpers · Normalization, deduplication, schema, AI client, and sponsorship utilities.
functions/lib/schema.js - Payment Integration · Server-side payment processing and webhook-related flow support.
functions/payments-razorpay.js
Legacy Python Stack
Older automation/scraping path kept separate from the active product.
- Python Automation · Older scraping and automation codepath, including deprecated modules.
runAiBot.py
Ops & Deployment
Configuration, scripts, and repository-level operational assets.
- Admin Scripts · Seed, check, and rules-management utilities for Firestore operations.
scripts/seed-users.js - Firebase Config · Project rules, indexes, and deployment configuration boundaries.
firebase.json - Marketing Site · GitHub Pages-hosted docs and privacy site.
docs/index.html
External Systems
Third-party and platform dependencies that shape the architecture.
- LinkedIn · Primary target site whose DOM and workflows drive the bot.
- Firebase · Authentication, Firestore, and Cloud Functions platform.
- Cashfree · External checkout provider for subscription payments.
Connections 26
- Popup UI → Auth Service: sign in · Popup initiates user authentication and session state.
- Popup UI → Plan Service: upgrade · Popup surfaces plan gating and payment entry points.
- Popup UI → Tracker: manage jobs · Popup exposes tracking and workflow controls.
- Service Worker → Bot Core: orchestrate · Background worker coordinates bot execution and extension events.
- Content Script → LinkedIn: inject · Content script operates directly on LinkedIn pages.
- Bot Core → Apply Flows: drive · Core loop delegates to application and messaging actions.
- Bot Core → Safety Controls: throttle · Safety controls bound the bot loop and stop conditions.
- Apply Flows → LinkedIn Selectors: read dom · Action modules rely on centralized LinkedIn selectors.
- Apply Flows → Content Script: use bridge · Bot actions depend on the page-integrated content runtime.
- Auth Service → Firebase: auth · Identity is centralized in Firebase Auth.
- Firestore Layer → Firebase: store sync · Repository layer persists and syncs state through Firestore.
- Firestore Layer → Auth Service: user state · Repository state is keyed to authenticated users.
- Plan Service → Firebase: plan state · Subscription decisions depend on cloud-backed user and plan state.
- Plan Service → Cashfree: checkout · Payment flow delegates to Cashfree.
- AI Services → Cloud Functions: optional backend · AI features can be supported by server-side functions.
- Tracker → Firestore Layer: persist · Tracking data is stored and synced through Firestore.
- Resume Service → Firestore Layer: load/save · Resume state and uploads use the repository boundary.
- Search Service → Cloud Functions: query · Search logic can leverage server-side search helpers.
- Visa Service → Cloud Functions: policy check · Visa logic aligns with server-side policy and scoring helpers.
- Cloud Functions → Policy Helpers: reuse · Cloud Functions compose shared backend helpers.
- Cloud Functions → Firebase: trusted runtime · Serverless backend executes within Firebase infrastructure.
- Payment Integration → Cashfree: gateway · Payment integration boundary for checkout processing.
- Admin Scripts → Firebase: admin ops · Scripts manage seed data and Firestore admin actions.
- Firebase Config → Firebase: deploy · Repo config defines deployment and access rules.
- Marketing Site → LinkedIn: product context · Static docs explain the product that targets LinkedIn.
- Python Automation → LinkedIn: legacy automation · Older Python stack also targets LinkedIn workflows.