# omarhussien2/open-freelance-agent architecture

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

- Interactive diagram: https://gitdiagram.com/omarhussien2/open-freelance-agent
- Repository: https://github.com/omarhussien2/open-freelance-agent

## Overview

Open Freelance Agent monitors freelance listings, filters them for fit, drafts proposals from approved facts, and pauses for human approval in Telegram before browser-based submission. Google Sheets and Apps Script provide memory and approval-email support; daily reporting is another documented capability. The sampled code shows the browser-agent loop and Telegram send, watch, and collect scripts. Monitoring, filtering, drafting, humanization, submission orchestration, and reporting are documented but not implemented in the excerpts, so their links are based on the README rather than inspected source.

Main entry points: [`agent`](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent) (Offer submission), [`agent/agent_loop.py`](https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/agent_loop.py) (Browser agent loop), [`apps-script/Code.gs`](https://github.com/omarhussien2/open-freelance-agent/blob/main/apps-script/Code.gs) (Apps Script), [`agent/send_proposal_tg.py`](https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/send_proposal_tg.py) (Send proposal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Opportunity discovery"]
  node_monitor["Listing monitor"]
  node_fit_filter["Fit filter"]
end

subgraph group_proposal["Proposal preparation"]
  node_facts["Approved facts"]
  node_drafting["Proposal drafting"]
  node_humanizer["Humanizer"]
end

subgraph group_approval["Human approval"]
  node_telegram_send["Send proposal"]
  node_watcher["Approval watcher<br/>[watch_approval.py]"]
  node_collector["Decision collector"]
end

subgraph group_operations["Submission and memory"]
  node_submission["Offer submission"]
  node_browser_agent["Browser agent loop<br/>[agent_loop.py]"]
  node_sheets[("Google Sheet")]
  node_apps_script["Apps Script<br/>[Code.gs]"]
  node_daily_report["Daily report"]
end

node_freelancer(("Freelancer"))
node_platforms["Job platforms"]
node_telegram["Telegram bot"]
node_cua["Cua Driver"]
node_openrouter["OpenRouter models"]

node_platforms -->|"listings"| node_monitor
node_monitor -->|"filters listings"| node_fit_filter
node_fit_filter -->|"matched projects"| node_drafting
node_facts -->|"informs drafts"| node_drafting
node_drafting -->|"humanizes draft"| node_humanizer
node_humanizer -->|"sends draft"| node_telegram_send
node_telegram_send -->|"sends proposal"| node_telegram
node_telegram -->|"requests review"| node_freelancer
node_telegram -->|"updates"| node_watcher
node_telegram -->|"decisions"| node_collector
node_collector -->|"approved text"| node_submission
node_submission -->|"runs submission"| node_browser_agent
node_browser_agent -->|"requests tool calls"| node_openrouter
node_browser_agent -->|"drives browser"| node_cua
node_submission -->|"logs offer"| node_sheets
node_apps_script -->|"records approvals"| node_sheets
node_apps_script -->|"emails approvals"| node_freelancer
node_sheets -.->|"supports report"| node_daily_report
node_daily_report -->|"reports actions"| node_freelancer

click node_monitor "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"
click node_fit_filter "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"
click node_facts "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"
click node_drafting "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"
click node_humanizer "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"
click node_telegram_send "https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/send_proposal_tg.py"
click node_watcher "https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/watch_approval.py"
click node_collector "https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/collect_approval.py"
click node_submission "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"
click node_browser_agent "https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/agent_loop.py"
click node_apps_script "https://github.com/omarhussien2/open-freelance-agent/blob/main/apps-script/Code.gs"
click node_daily_report "https://github.com/omarhussien2/open-freelance-agent/tree/main/agent"

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_monitor,node_fit_filter toneBlue
class node_facts,node_drafting,node_humanizer toneAmber
class node_telegram_send,node_watcher,node_collector,node_openrouter toneMint
class node_submission,node_browser_agent,node_sheets,node_apps_script,node_daily_report toneRose
class node_freelancer,node_platforms,node_telegram,node_cua toneIndigo
```

## Components

### Opportunity discovery

- [Listing monitor](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`
- [Fit filter](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`

### Proposal preparation

- [Approved facts](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`
- [Proposal drafting](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`
- [Humanizer](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`

### Human approval

- [Send proposal](https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/send_proposal_tg.py): `agent/send_proposal_tg.py`
- [Approval watcher](https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/watch_approval.py): `agent/watch_approval.py`
- [Decision collector](https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/collect_approval.py): `agent/collect_approval.py`

### Submission and memory

- [Offer submission](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`
- [Browser agent loop](https://github.com/omarhussien2/open-freelance-agent/blob/main/agent/agent_loop.py): `agent/agent_loop.py`
- **Google Sheet**
- [Apps Script](https://github.com/omarhussien2/open-freelance-agent/blob/main/apps-script/Code.gs): `apps-script/Code.gs`
- [Daily report](https://github.com/omarhussien2/open-freelance-agent/tree/main/agent): `agent`

### Other components

- **Freelancer**
- **Job platforms**
- **Telegram bot**
- **Cua Driver**
- **OpenRouter models**

## Connections

- Job platforms → Listing monitor: listings (evidence: `README.md`)
- Listing monitor → Fit filter: filters listings (evidence: `README.md`)
- Fit filter → Proposal drafting: matched projects (evidence: `README.md`)
- Approved facts → Proposal drafting: informs drafts (evidence: `README.md`)
- Proposal drafting → Humanizer: humanizes draft (evidence: `README.md`)
- Humanizer → Send proposal: sends draft (evidence: `README.md`)
- Send proposal → Telegram bot: sends proposal (evidence: `agent/send_proposal_tg.py`)
- Telegram bot → Freelancer: requests review (evidence: `README.md`)
- Telegram bot → Approval watcher: updates (evidence: `agent/watch_approval.py`)
- Telegram bot → Decision collector: decisions (evidence: `agent/collect_approval.py`)
- Decision collector → Offer submission: approved text (evidence: `README.md`)
- Offer submission → Browser agent loop: runs submission (evidence: `README.md`)
- Browser agent loop → OpenRouter models: requests tool calls (evidence: `agent/agent_loop.py`)
- Browser agent loop → Cua Driver: drives browser (evidence: `agent/agent_loop.py`)
- Offer submission → Google Sheet: logs offer (evidence: `README.md`)
- Apps Script → Google Sheet: records approvals (evidence: `README.md`)
- Apps Script → Freelancer: emails approvals (evidence: `README.md`)
- Google Sheet → Daily report: supports report
- Daily report → Freelancer: reports actions (evidence: `README.md`)