# sohamkhrt/opportunity-pulse- architecture

> Architecture diagram of the GitHub repository sohamkhrt/opportunity-pulse-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sohamkhrt/opportunity-pulse-
- Repository: https://github.com/sohamkhrt/opportunity-pulse-

## Overview

OpportunityPulse AI turns a candidate’s background into four career-pivot ideas, searches for matching ATS postings, extracts and validates job details, and streams results to an interactive browser UI. The main flow is visible across the API, pipeline, and frontend excerpts; Bright Data search and collector operations are represented as external services. The README documents optional ATS collectors, opt-in collector auto-heal, and additional-job pagination. Source excerpts omit parts of the pipeline, so unshown internal sequencing is not expanded.

Main entry points: [`backend/main.py`](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/main.py) (FastAPI service), [`pipeline.py`](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py) (Discovery stream), [`frontend/app.js`](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js) (Discovery UI), [`backend/pivot_engine.py`](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/pivot_engine.py) (Career pivot ideas)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and runtime"]
  node_server["FastAPI service<br/>[main.py]"]
  node_settings["Server settings<br/>[config.py]"]
end

subgraph group_discovery["Career discovery"]
  node_career_ideas["Career pivot ideas<br/>[pivot_engine.py]"]
  node_discovery_flow["Discovery stream<br/>[pipeline.py]"]
end

subgraph group_jobs["Job sourcing"]
  node_job_search["ATS job search<br/>[pipeline.py]"]
  node_job_extraction["Job extraction<br/>[pipeline.py]"]
end

subgraph group_experience["Browser experience"]
  node_frontend["Discovery UI<br/>[app.js]"]
  node_job_cards["Job cards<br/>[app.js]"]
  node_pagination["Find more<br/>[app.js]"]
end

node_candidate(("Candidate"))
node_browser(("Browser"))
node_bright_data{{"Bright Data"}}
node_gemini{{"Gemini"}}

node_candidate -->|"enters background"| node_frontend
node_browser -->|"requests discovery"| node_server
node_server -->|"streams discovery"| node_discovery_flow
node_server -->|"checks settings"| node_settings
node_discovery_flow -->|"requests pivots"| node_career_ideas
node_career_ideas -->|"generates pivots"| node_gemini
node_discovery_flow -->|"searches niches"| node_job_search
node_job_search -->|"searches postings"| node_bright_data
node_job_search -->|"extracts selected jobs"| node_job_extraction
node_job_extraction -->|"runs collector"| node_bright_data
node_job_extraction -.->|"repairs collector"| node_bright_data
node_discovery_flow -->|"yields events"| node_server
node_server -->|"sends SSE events"| node_frontend
node_frontend -->|"renders jobs"| node_job_cards
node_frontend -->|"requests more"| node_pagination
node_pagination -->|"posts next page"| node_server
node_server -->|"fetches more jobs"| node_job_search

click node_server "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/main.py"
click node_settings "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/config.py"
click node_career_ideas "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/pivot_engine.py"
click node_discovery_flow "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py"
click node_job_search "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py"
click node_job_extraction "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py"
click node_frontend "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js"
click node_job_cards "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js"
click node_pagination "https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js"

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_server,node_settings,node_browser toneBlue
class node_career_ideas,node_discovery_flow toneAmber
class node_job_search,node_job_extraction toneMint
class node_frontend,node_job_cards,node_pagination toneRose
class node_candidate,node_bright_data,node_gemini toneIndigo
```

## Components

### API and runtime

- [FastAPI service](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/main.py): `backend/main.py`
- [Server settings](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/config.py): `backend/config.py`

### Career discovery

- [Career pivot ideas](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/backend/pivot_engine.py): `backend/pivot_engine.py`
- [Discovery stream](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py): `pipeline.py`

### Job sourcing

- [ATS job search](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py): `pipeline.py`
- [Job extraction](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/pipeline.py): `pipeline.py`

### Browser experience

- [Discovery UI](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js): `frontend/app.js`
- [Job cards](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js): `frontend/app.js`
- [Find more](https://github.com/sohamkhrt/opportunity-pulse-/blob/main/frontend/app.js): `frontend/app.js`

### Other components

- **Candidate**
- **Browser**
- **Bright Data**
- **Gemini**

## Connections

- Candidate → Discovery UI: enters background (evidence: `frontend/app.js`)
- Browser → FastAPI service: requests discovery
- FastAPI service → Discovery stream: streams discovery (evidence: `backend/main.py`)
- FastAPI service → Server settings: checks settings (evidence: `backend/main.py`)
- Discovery stream → Career pivot ideas: requests pivots (evidence: `pipeline.py`)
- Career pivot ideas → Gemini: generates pivots (evidence: `backend/pivot_engine.py`)
- Discovery stream → ATS job search: searches niches (evidence: `pipeline.py`)
- ATS job search → Bright Data: searches postings (evidence: `pipeline.py`)
- ATS job search → Job extraction: extracts selected jobs (evidence: `pipeline.py`)
- Job extraction → Bright Data: runs collector (evidence: `pipeline.py`)
- Job extraction → Bright Data: repairs collector (evidence: `readme.md`)
- Discovery stream → FastAPI service: yields events (evidence: `backend/main.py`)
- FastAPI service → Discovery UI: sends SSE events (evidence: `frontend/app.js`)
- Discovery UI → Job cards: renders jobs (evidence: `frontend/app.js`)
- Discovery UI → Find more: requests more (evidence: `frontend/app.js`)
- Find more → FastAPI service: posts next page (evidence: `backend/main.py`)
- FastAPI service → ATS job search: fetches more jobs (evidence: `backend/main.py`)
