# thomasveit89/designsnack-lead-generator architecture

> Architecture diagram of the GitHub repository thomasveit89/designsnack-lead-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomasveit89/designsnack-lead-generator
- Repository: https://github.com/thomasveit89/designsnack-lead-generator

## Overview

##### Project type and purpose
- This is a full-stack lead generation web application (DESIGNSNACK Lead Generator).
- Frontend: Vue.js SPA served by Vite + Tailwind.
- Backend: Node.js + Express REST API.
- Core functionality: scrape job listings, score leads, discover contacts, generate AI emails, cache results on the filesystem.

##### File structure
- Root files:
- package.json / package-lock.json (dependency management & scripts)
- server.js (Express server & API routing)
- scraper.js (Puppeteer job-scraping logic)
- contact-service.js (Hunter.io & Google Search contact lookup)
- email-service.js (OpenAI GPT for email drafting)
- storage.js (JSON file read/write utilities)
- index.html, vite.config.js, tailwind.config.cjs, postcss.config.cjs (frontend build config)
- src/ directory: Vue 3 application (App.vue, main.js, style.css)
- data/ directory: file-system caches (search results, contact records, search history)

##### README for additional insights
- REST endpoints: /api/search, /api/search-history, /api/search/:id, /api/find-contacts, /api/generate-email
- External integrations: OpenAI, Hunter.io, Google Custom Search
- Caching strategy: 7-day contact cache, search history persisted as JSON

##### Components
a. Frontend (Vue.js SPA)
- User Interface (Search form, Results list, “Find Contact & Draft Email” buttons)
- Vite dev server / production hosting
b. API Layer (Express server)
- Route handlers
- Orchestrator glue between services
c. Scraper Service
- Puppeteer job scraper (jobs.ch pagination)
- Produces “search results” JSON
d. Contact Service
- Hunter.io API call
- Google Custom Search API call
- Caches contact data (storage.js → data/contacts)
e. Email Service
- OpenAI GPT-4o-mini call for personalized email templates
f. Storage Layer
- JSON files in data/ (searches, contacts, search-history)
- storage.js abstracts read/write operations
g. External Systems
- jobs.ch website
- Hunter.io
- Google Custom Search
- OpenAI API

##### Relationships and interactions
1. User → Frontend (Vue.js)
2. Frontend → HTTP request → Express API
3. /api/search → scraper.js → jobs.ch → returns job list → storage.js → data/searches → Express → Frontend
4. /api/find-contacts → contact-service.js → Hunter & Google Search → storage.js → data/contacts → Express → Frontend
5. /api/generate-email → email-service.js → OpenAI API → Express → Frontend
6. Frontend displays results, caches in local state, writes to search-history via GET /api/search-history

##### Architectural patterns and design principles
- Single-Page Application (SPA) for rich UI interactions
- RESTful API layer separating concerns
- Modular “service” classes for scraper, contact lookup, email generation
- File-based caching as a simple persistence layer (avoids database overhead)
- Configuration-driven integration via environment variables

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend Layer"
        direction TB
        UI["Vue.js SPA<br/>(Search Form, Results List)"]:::frontend
        Configs["Build Configs<br/>index.html, vite.config.js,<br/>tailwind.config.cjs, postcss.config.cjs"]:::frontend
        UI --> Configs
    end

    %% Backend Zone
    subgraph "Backend Layer"
        direction TB
        API["Express.js API<br/>(server.js)"]:::backend
        Scraper["Puppeteer Scraper<br/>(scraper.js)"]:::backend
        Contact["Contact Service<br/>(contact-service.js)"]:::backend
        Email["Email Service<br/>(email-service.js)"]:::backend
        StorageLayer["Storage Layer<br/>(storage.js)"]:::backend
    end

    %% Storage Data Store
    DataStore[(JSON File Store<br/>data/)]:::storage

    %% External Systems
    subgraph "External Services"
        direction TB
        jobs["jobs.ch"]:::external
        Hunter["Hunter.io API"]:::external
        Google["Google Custom Search API"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% User Interaction
    User["User"]:::external
    User --> UI
    UI -->|"POST /api/search"| API
    API -->|"invoke scraper.js"| Scraper
    Scraper -->|"HTTP fetch"| jobs
    jobs --> Scraper
    Scraper -->|"write → storage.js"| StorageLayer
    StorageLayer --> DataStore
    Scraper -->|"returns results"| API
    API -->|"response JSON"| UI

    UI -->|"POST /api/find-contacts"| API
    API -->|"invoke contact-service.js"| Contact
    Contact -->|"Hunter.io request"| Hunter
    Contact -->|"Google Search request"| Google
    Hunter --> Contact
    Google --> Contact
    Contact -->|"write → storage.js"| StorageLayer
    StorageLayer --> DataStore
    Contact -->|"returns contacts"| API
    API -->|"response JSON"| UI

    UI -->|"POST /api/generate-email"| API
    API -->|"invoke email-service.js"| Email
    Email -->|"OpenAI.generate()"| OpenAI
    OpenAI --> Email
    Email -->|"returns draft"| API
    API -->|"response JSON"| UI

    UI -->|"GET /api/search-history"| API
    API -->|"read → storage.js"| StorageLayer
    StorageLayer --> DataStore
    API -->|"response JSON"| UI

    %% Click Events
    click UI "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/src/App.vue"
    click API "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/server.js"
    click Scraper "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/scraper.js"
    click Contact "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/contact-service.js"
    click Email "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/email-service.js"
    click StorageLayer "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/storage.js"
    click DataStore "https://github.com/thomasveit89/designsnack-lead-generator/tree/main/data/"
    click Configs "https://github.com/thomasveit89/designsnack-lead-generator/blob/main/index.html"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0F7E4,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef storage fill:#ECECEC,stroke:#333,stroke-width:1px
```
