# hxrjt/reachhr architecture

> Architecture diagram of the GitHub repository hxrjt/reachhr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hxrjt/reachhr
- Repository: https://github.com/hxrjt/reachhr

## Overview

##### Project Type and Purpose
- ReachHR is a lightweight, full-stack web application built with Streamlit (Python) that lets users input a company name and location, scrapes relevant LinkedIn recruiter/HR profiles via Google Custom Search, and then generates personalized cold messages using the Cohere API.
- It is not a multi-service microservices architecture: it’s a single Streamlit “app server” process that handles both UI rendering and core business logic.

##### File Structure
- Top-level:
- app.py         → Streamlit entry point, UI + orchestration
- google_search.py   → Encapsulates calls to Google CSE API, parses search results
- message_generator.py → Encapsulates calls to Cohere API to generate messages
- requirements.txt   → Lists dependencies (streamlit, cohere, google-api-python-client, etc.)
- .devcontainer/devcontainer.json → Configuration for VSCode dev container
- venv/        → Local virtual environment
- .gitignore   → Excludes venv, .env, __pycache__
- There is no database or persistent storage layer: all data flows in memory per request.
- External dependencies are strictly two HTTP-based APIs (Google CSE, Cohere).

##### README
- Confirms single‐page Streamlit UI, no separate frontend (React/Angular) or backend (Flask/Django) services.
- Highlights two external services: Google CSE for web/LinkedIn scraping & Cohere for AI message generation.
- Deployment is on Streamlit Cloud, environment variables stored as secrets.

a. Main Components:
- User’s Browser
- Streamlit App Server (app.py)
– UI Layer (widgets, forms, results view)
– Controller/Orchestration Logic
– Business-logic Modules:
· google_search.py
· message_generator.py
- External Services:
– Google Custom Search API
– Cohere API
b. Relationships & Interactions:
1. User submits company & location in browser.
2. Browser → HTTP POST to Streamlit Server.
3. Streamlit Server invokes google_search.py:
→ HTTP GET to Google CSE → parses response → returns list of LinkedIn profiles.
4. Streamlit Server renders profiles, prompts user for purpose.
5. User submits purpose → Streamlit Server invokes message_generator.py:
→ HTTP POST to Cohere API with prompt → receives AI-generated message.
6. Streamlit Server displays final message to user.
c. Architectural Patterns & Principles:
- Single process, thin-client model: Streamlit handles UI and routing.
- Separation of concerns:
· UI orchestration in app.py
· External API wrappers in dedicated modules
- Dependency injection of API keys via environment variables (.env / Streamlit secrets).
d. Key Technologies & Libraries:
- Python 3.10+
- Streamlit for UI
- google-api-python-client or custom HTTP code in google_search.py
- Cohere Python SDK or HTTP client in message_generator.py

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    Browser["User Browser"]:::client

    %% Application Tier
    subgraph "Streamlit App Server" 
        direction TB
        App_py["Streamlit UI & Orchestration\n(app.py)"]:::internal
        Controller["Controller Logic"]:::internal
        Google_search_py["Google CSE Wrapper\n(google_search.py)"]:::internal
        Message_generator_py["Cohere Message Generator\n(message_generator.py)"]:::internal
        Env["Env Variables / Secrets"]:::config
    end

    %% External Services
    Ext_GoogleCSE["Google Custom Search API"]:::external
    Ext_Cohere["Cohere API"]:::external

    %% Config & Dev
    Req["requirements.txt"]:::config
    Devcontainer[".devcontainer/devcontainer.json"]:::config
    Gitignore[".gitignore"]:::config

    %% Data Flows
    Browser -->|HTTP POST: company & location| App_py
    App_py -->|invoke| Controller
    Controller -->|calls| Google_search_py
    Google_search_py -->|HTTP GET: search query| Ext_GoogleCSE
    Ext_GoogleCSE -->|response: profiles list| Google_search_py
    Google_search_py -->|profiles list| Controller
    Controller -->|render profiles & prompt| App_py
    App_py -->|HTTP POST: purpose| Controller
    Controller -->|calls| Message_generator_py
    Message_generator_py -->|HTTP POST: AI prompt| Ext_Cohere
    Ext_Cohere -->|response: generated message| Message_generator_py
    Message_generator_py -->|message| Controller
    Controller -->|render message| App_py
    App_py -->|HTTP RESPONSE| Browser

    %% Env Injection
    Env --> App_py

    %% Dev & Dependencies
    Req --> App_py
    Devcontainer --> App_py
    Gitignore --> Env

    %% Click Events
    click App_py "https://github.com/hxrjt/reachhr/blob/main/app.py"
    click Google_search_py "https://github.com/hxrjt/reachhr/blob/main/google_search.py"
    click Message_generator_py "https://github.com/hxrjt/reachhr/blob/main/message_generator.py"
    click Req "https://github.com/hxrjt/reachhr/blob/main/requirements.txt"
    click Devcontainer "https://github.com/hxrjt/reachhr/blob/main/.devcontainer/devcontainer.json"
    click Gitignore "https://github.com/hxrjt/reachhr/blob/main/.gitignore"

    %% Styles
    classDef client fill:#CAE8FF,stroke:#0366d6,color:#0366d6;
    classDef internal fill:#CFFECB,stroke:#2E7D32,color:#2E7D32;
    classDef external fill:#FFE0B2,stroke:#EF6C00,color:#E65100;
    classDef config fill:#E0E0E0,stroke:#616161,color:#424242
```
