LeadForge OS is a desktop application designed for B2B lead generation, website crawling, contact enrichment, and automated cold email campaigns. Instead of relying on expensive seat-based cloud platforms that charge high infrastructure markups and upload your database to third parties, LeadForge OS executes scrapers, headless browsers, data-mining operations, and local LLMs directly on your local hardware.
Commercial outbound platforms (e.g. Apollo, Lemlist, Instantly) operate on centralized cloud environments. This model introduces three major drawbacks:
- High Infrastructure markups: Web crawling and scraping Google Maps at scale consumes heavy proxy and bandwidth resources, leading to expensive subscription tiers.
- Data Privacy Risks: Uploading customer lists, prospect profiles, and private SMTP/IMAP credentials to third-party databases exposes your sales pipeline to security leaks.
- Crawl & Send Throttling: Centralized platforms limit crawling rates and email check frequencies to manage their own cloud costs.
LeadForge OS solves this by executing high-concurrency scraping (via Playwright), crawler parsers (via Cheerio), local databases (via SQLite WAL-mode), local LLM inference (via Ollama), and local OS-native credentials encryption (via safeStorage) directly on the client machine. Networks are treated as synchronization transport layers rather than the primary application hosts.
- Google Maps Scraper (
scraper:maps): Runs headless Playwright browsers, performs infinite scrolls on business listings, resolves domain redirects, and extracts addresses. - Website Crawler (
crawler:website): Runs BFS Cheerio crawlers on discovered domains, parsing emails, phone numbers, and identifying tracking/spam traps. - LinkedIn Voyager Enricher (
enrich:linkedin): Leverages active session cookies to query LinkedIn APIs and locate matching CEO, Founder, or VP decision-maker profiles. - Sequence Drip Engine (
automation:workflow): Maps multi-step sequences (IF,WAIT,SEND_EMAIL,HTTP_REQUEST) executing inside a sandboxed worker child process. - IMAP Reply Poller (
outreach:imap-poll): Scans inbox replies, correlating conversations viaIn-Reply-To/Referencesheaders to automatically pause outbound campaigns. - SRE Cockpit & Diagnostics: Measures database latency, pings network sockets, checks SMTP/IMAP ports, runs SQLite integrity checks, and queries system logs.
- OS Keychain safeStorage: Encrypts sensitive keys, tokens, and passwords in the database using OS-level credential managers (Electron
safeStorage).
- Desktop Shell: Electron (Main process Node, Preload context bridge, Renderer Chromium)
- UI Framework: React 19, Vite, TailwindCSS 4
- Monorepo Orchestrator: Turborepo & pnpm Workspaces
- Primary Datastore: SQLite (WAL mode, workspace physical isolation)
- Cloud Backend API: Hono Server on Node, MongoDB via Mongoose
- AI Orchestration: OpenRouter API (Cloud) & Ollama (Local Llama/Gemini)
- Automation / Scraping: Playwright & Cheerio
- Email Sending: Nodemailer (SMTP client) & ImapFlow (IMAP client)
LeadForge OS separates intensive automation workflows and scrapers from the React user interface. Long-running scrapers or workflows are spawned as isolated Node.js child processes to prevent blocking the UI thread or crashing the desktop application.
graph TD
UI[React UI Renderer] <-->|ipcRenderer.invoke| PL[Preload ContextBridge]
PL <-->|IPC Channels| MP[Main Process Orchestrator]
MP <-->|safeStorage| KC[OS Keychain / Credential API]
MP <-->|better-sqlite3| DB[(Workspace SQLite DB)]
MP -->|fork child process| WH[Worker Host - worker-host.ts]
WH -->|execute plugin| WP[Worker Plugins - Playwright, Cheerio, SMTP]
WP -->|write mutations| DB
MP <-->|SyncEngine SdkClient| CN[Cloud Hono Server - MongoDB]
For a detailed breakdown of process lifecycles, data flows, and schemas, view the System Architecture Guide.
├── apps/
│ ├── api/ # Node.js Hono REST API server (Mongoose/MongoDB)
│ ├── desktop/ # Electron application (Main, Preload, React Renderer)
│ └── web/ # (Planned) Next.js cloud portal
├── packages/
│ ├── agent-core/ # LLM orchestrator (agents, tools, memory, tracing)
│ ├── agent-runtime/ # Dynamic agent session runtime & tool executors
│ ├── ai/ # Prompt compilers & LLM providers (Ollama / OpenRouter)
│ ├── auth/ # better-auth configurations & Middlewares
│ ├── core/ # Shared constants, validations, and environment schemas
│ ├── logger/ # Workspace-scoped rotating files logger
│ ├── schema/ # TypeScript Interfaces, IPC contracts, and DTOs
│ ├── sdk/ # HTTP Client Wrapper for sync communication
│ └── workflow-engine/ # Sequential drip execution runners
└── docs/ # Repository Documentation System
- Node.js:
v18.0.0or higher - pnpm:
v8.0.0or higher - Git: Installed and configured
- Ollama (Optional): For running local qualification models offline
-
Clone the repository:
git clone https://github.com/kjxcodez/leadforge-os.git cd leadforge-os -
Install dependencies:
pnpm install
-
Build all workspace packages:
pnpm build
To start development runtimes for both the Hono API server and the Electron application:
# Run all apps in development mode (API & Desktop UI)
pnpm dev
# Run only the Hono REST API server
pnpm dev --filter=api
# Run only the Electron Desktop application
pnpm dev --filter=@leadforge/desktoppnpm build: Compiles all packages and application bundles.pnpm check-types: Compiles TypeScript with--noEmitacross all workspace targets.pnpm lint: Lints the monorepo codebase using ESLint.pnpm test: Executes unit and integration test suites.pnpm test:ai: Validates AI connections and LLM providers.pnpm doctor: Runs the 11-step SRE local diagnostic tool.pnpm release:check: Validates the 10-step release gates before bundling.
Explore the sub-guides for deep-dive technical and operational details:
- Getting Started / Setup: Node configurations, workspace creation, and Electron Builder packaging.
- System Architecture: Process boundaries, event buses, SQLite schemas, and AI prompts caching.
- Development Guides: Code guidelines for adding tools, workers, repositories, or IPC channels.
- Testing & QA: Automated tests, mock setups, SRE diagnostics, and CI checklists.
- Release & Packaging: Electron-Builder settings, release gates, version changesets, and update manager hooks.
- Security Policy: safeStorage decryption rules, masking logs, and privacy boundaries.
- Troubleshooting Guides: Mismatched sqlite builds, DLL failures, task timeouts, and backups.
- Architectural Decision Records (ADRs): Historical index of system design decisions (001-013).
- Historical Archive: Archived forensic audits, old specs, and sprint planning logs.
See the detailed ROADMAP.md file for a full schedule of completed milestones and upcoming implementations.
We welcome contributions from the community! Please read the CONTRIBUTING.md file for coding standards, pull request policies, and git branching styles.
LeadForge OS is licensed under the MIT License.
- Turborepo & pnpm: For making monorepo dependency tracking effortless.
- Electron Toolkit: For simplifying Main-to-Renderer IPC bindings.
- Nodemailer / ImapFlow: For providing stable offline email integrations.