# mukul2345/linkedin-job-copilot architecture

> Architecture diagram of the GitHub repository mukul2345/linkedin-job-copilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mukul2345/linkedin-job-copilot
- Repository: https://github.com/mukul2345/linkedin-job-copilot

## Overview

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: [`functions/index.js`](https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/index.js) (Cloud Functions), [`extension/modules/database/firestore-service.js`](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/database/firestore-service.js) (Firestore Layer), [`extension/ui/popup.html`](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/ui/popup.html) (Popup UI), [`extension/modules/bot/bot-core.js`](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/bot-core.js) (Bot Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_extension["Chrome Extension"]
  node_n_popup["Popup UI<br/>extension-ui<br/>[popup.html]"]
  node_n_content["Content Script<br/>page bridge<br/>[content.js]"]
  node_n_background["Service Worker<br/>orchestrator<br/>[service-worker.js]"]
  node_n_bot_core["Bot Core<br/>automation engine<br/>[bot-core.js]"]
  node_n_bot_actions["Apply Flows<br/>bot actions<br/>[job-processor.js]"]
  node_n_bot_safety["Safety Controls<br/>rate limits<br/>[safety.js]"]
  node_n_selectors["LinkedIn Selectors<br/>dom map<br/>[selectors.js]"]
  node_n_auth["Auth Service<br/>firebase auth<br/>[auth-service.js]"]
  node_n_db[("Firestore Layer")]
  node_n_subscription["Plan Service<br/>subscription gate<br/>[plan-service.js]"]
  node_n_ai["AI Services<br/>optional ai<br/>[ai-service.js]"]
  node_n_tracker["Tracker<br/>workflow tracking<br/>[tracker-service.js]"]
  node_n_resume["Resume Service<br/>resume workflow<br/>[resume-service.js]"]
  node_n_search["Search Service<br/>discovery<br/>[search-service.js]"]
  node_n_visa["Visa Service<br/>eligibility<br/>[visa-service.js]"]
end

subgraph group_g_backend["Firebase Backend"]
  node_n_functions["Cloud Functions<br/>serverless api<br/>[index.js]"]
  node_n_backend_lib["Policy Helpers<br/>backend lib<br/>[schema.js]"]
  node_n_razorpay["Payment Integration<br/>payment gateway"]
end

subgraph group_g_legacy["Legacy Python Stack"]
  node_n_python_legacy["Python Automation<br/>legacy stack<br/>[runAiBot.py]"]
end

subgraph group_g_ops["Ops & Deployment"]
  node_n_scripts["Admin Scripts<br/>ops tools<br/>[seed-users.js]"]
  node_n_firebase_config["Firebase Config<br/>deployment config<br/>[firebase.json]"]
  node_n_docs["Marketing Site<br/>static site<br/>[index.html]"]
end

subgraph group_g_external["External Systems"]
  node_n_linkedin(("LinkedIn<br/>external platform"))
  node_n_firebase(("Firebase<br/>external cloud"))
  node_n_cashfree(("Cashfree<br/>payment provider"))
end

node_n_popup -->|"sign in"| node_n_auth
node_n_popup -->|"upgrade"| node_n_subscription
node_n_popup -->|"manage jobs"| node_n_tracker
node_n_background -->|"orchestrate"| node_n_bot_core
node_n_content -->|"inject"| node_n_linkedin
node_n_bot_core -->|"drive"| node_n_bot_actions
node_n_bot_core -->|"throttle"| node_n_bot_safety
node_n_bot_actions -->|"read dom"| node_n_selectors
node_n_bot_actions -->|"use bridge"| node_n_content
node_n_auth -->|"auth"| node_n_firebase
node_n_db -->|"store sync"| node_n_firebase
node_n_db -->|"user state"| node_n_auth
node_n_subscription -->|"plan state"| node_n_firebase
node_n_subscription -->|"checkout"| node_n_cashfree
node_n_ai -->|"optional backend"| node_n_functions
node_n_tracker -->|"persist"| node_n_db
node_n_resume -->|"load/save"| node_n_db
node_n_search -->|"query"| node_n_functions
node_n_visa -->|"policy check"| node_n_functions
node_n_functions -->|"reuse"| node_n_backend_lib
node_n_functions -->|"trusted runtime"| node_n_firebase
node_n_razorpay -->|"gateway"| node_n_cashfree
node_n_scripts -->|"admin ops"| node_n_firebase
node_n_firebase_config -->|"deploy"| node_n_firebase
node_n_docs -.->|"product context"| node_n_linkedin
node_n_python_legacy -.->|"legacy automation"| node_n_linkedin

click node_n_popup "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/ui/popup.html"
click node_n_content "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/content/content.js"
click node_n_background "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/background/service-worker.js"
click node_n_bot_core "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/bot-core.js"
click node_n_bot_actions "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/job-processor.js"
click node_n_bot_safety "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/safety.js"
click node_n_selectors "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/selectors.js"
click node_n_auth "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/auth/auth-service.js"
click node_n_db "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/database/firestore-service.js"
click node_n_subscription "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/subscription/plan-service.js"
click node_n_ai "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/ai/ai-service.js"
click node_n_tracker "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/tracker/tracker-service.js"
click node_n_resume "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/resume/resume-service.js"
click node_n_search "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/search/search-service.js"
click node_n_visa "https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/visa/visa-service.js"
click node_n_functions "https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/index.js"
click node_n_backend_lib "https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/lib/schema.js"
click node_n_razorpay "https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/payments-razorpay.js"
click node_n_python_legacy "https://github.com/mukul2345/linkedin-job-copilot/blob/main/runAiBot.py"
click node_n_scripts "https://github.com/mukul2345/linkedin-job-copilot/blob/main/scripts/seed-users.js"
click node_n_firebase_config "https://github.com/mukul2345/linkedin-job-copilot/blob/main/firebase.json"
click node_n_docs "https://github.com/mukul2345/linkedin-job-copilot/blob/main/docs/index.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_popup,node_n_content,node_n_background,node_n_bot_core,node_n_bot_actions,node_n_bot_safety,node_n_selectors,node_n_auth,node_n_db,node_n_subscription,node_n_ai,node_n_tracker,node_n_resume,node_n_search,node_n_visa toneBlue
class node_n_functions,node_n_backend_lib,node_n_razorpay toneAmber
class node_n_python_legacy toneMint
class node_n_scripts,node_n_firebase_config,node_n_docs toneRose
class node_n_linkedin,node_n_firebase,node_n_cashfree toneIndigo
```

## Components

### Chrome Extension

Active Manifest V3 extension runtime and feature modules.

- [Popup UI](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/ui/popup.html): extension-ui · Lightweight control dashboard for auth, settings, status, and upsell flows. · `extension/ui/popup.html`
- [Content Script](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/content/content.js): page bridge · Injected LinkedIn page integration for DOM interaction and helper overlays. · `extension/content/content.js`
- [Service Worker](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/background/service-worker.js): orchestrator · Background event handling and coordination across extension surfaces. · `extension/background/service-worker.js`
- [Bot Core](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/bot-core.js): automation engine · Coordinates the job-application loop and bot execution flow. · `extension/modules/bot/bot-core.js`
- [Apply Flows](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/job-processor.js): bot actions · Handles Easy Apply processing, form filling, and outreach message generation. · `extension/modules/bot/job-processor.js`
- [Safety Controls](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/safety.js): rate limits · Adaptive delays, daily caps, and stop conditions for compliant automation. · `extension/modules/bot/safety.js`
- [LinkedIn Selectors](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/bot/selectors.js): dom map · Centralized LinkedIn DOM selectors and page structure coupling. · `extension/modules/bot/selectors.js`
- [Auth Service](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/auth/auth-service.js): firebase auth · Sign-up, login, logout, and typed user identity management. · `extension/modules/auth/auth-service.js`
- [Firestore Layer](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/database/firestore-service.js): repository · Firestore CRUD, caching, sync, and user/usage persistence boundary. · `extension/modules/database/firestore-service.js`
- [Plan Service](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/subscription/plan-service.js): subscription gate · Plan definitions, access checks, admin bypass, and payment entry points. · `extension/modules/subscription/plan-service.js`
- [AI Services](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/ai/ai-service.js): optional ai · Optional response and fit-score features gated by higher plans. · `extension/modules/ai/ai-service.js`
- [Tracker](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/tracker/tracker-service.js): workflow tracking · Job tracking, user-facing tracker UI, and status workflows. · `extension/modules/tracker/tracker-service.js`
- [Resume Service](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/resume/resume-service.js): resume workflow · Resume tailoring and upload support used by application flows. · `extension/modules/resume/resume-service.js`
- [Search Service](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/search/search-service.js): discovery · Search and discovery logic supporting job finding and filtering. · `extension/modules/search/search-service.js`
- [Visa Service](https://github.com/mukul2345/linkedin-job-copilot/blob/main/extension/modules/visa/visa-service.js): eligibility · 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](https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/index.js): serverless api · Trusted backend entry points for payments, policy, search, scoring, and sync. · `functions/index.js`
- [Policy Helpers](https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/lib/schema.js): backend lib · Normalization, deduplication, schema, AI client, and sponsorship utilities. · `functions/lib/schema.js`
- [Payment Integration](https://github.com/mukul2345/linkedin-job-copilot/blob/main/functions/payments-razorpay.js): payment gateway · 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](https://github.com/mukul2345/linkedin-job-copilot/blob/main/runAiBot.py): legacy stack · Older scraping and automation codepath, including deprecated modules. · `runAiBot.py`

### Ops & Deployment

Configuration, scripts, and repository-level operational assets.

- [Admin Scripts](https://github.com/mukul2345/linkedin-job-copilot/blob/main/scripts/seed-users.js): ops tools · Seed, check, and rules-management utilities for Firestore operations. · `scripts/seed-users.js`
- [Firebase Config](https://github.com/mukul2345/linkedin-job-copilot/blob/main/firebase.json): deployment config · Project rules, indexes, and deployment configuration boundaries. · `firebase.json`
- [Marketing Site](https://github.com/mukul2345/linkedin-job-copilot/blob/main/docs/index.html): static site · GitHub Pages-hosted docs and privacy site. · `docs/index.html`

### External Systems

Third-party and platform dependencies that shape the architecture.

- **LinkedIn**: external platform · Primary target site whose DOM and workflows drive the bot.
- **Firebase**: external cloud · Authentication, Firestore, and Cloud Functions platform.
- **Cashfree**: payment provider · External checkout provider for subscription payments.

## Connections

- 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.
