portfolio

FreelanceOS - AI-Powered Upwork Automation System

Production System Built: January 2025 Timeline: 2 weeks Role: Solo Developer

n8n Claude API ClickUp Telegram

🎯 Overview

The Problem: As a freelance developer on Upwork, I was spending 8-10 hours per week on repetitive tasks:

This created two major issues:

  1. Opportunity cost - Time spent on admin work meant less time for billable client work
  2. Response time - Manual processes resulted in 2-3 hour delays, causing me to lose opportunities to faster competitors

The Solution: FreelanceOS is an end-to-end automation system that handles the complete freelance workflow from job discovery through project completion. Built using n8n workflow automation, Claude AI for proposal generation, and Telegram for mobile-first approvals, it transforms hours of manual work into minutes of strategic decision-making.

The Impact:

📊 Before vs After Comparison

Metric Before Automation After Automation Improvement
Job Screening 3-4 hours/week 30 minutes/week 87% reduction
Proposal Writing 30-45 min each 60 seconds each 98% reduction
Response Time 2-3 hours 10 minutes 12-18× faster
Mobile Operation 0% (desktop only) 95% (phone) New capability
Proposal Quality Variable (fatigue) Consistent (AI) Standardized
Weekly Admin Time 8-10 hours 1-2 hours 80% time savings
Monthly Value -$800 (lost time) +$2,200 (saved time) $3,000 swing

🏗️ Architecture

graph TB
    subgraph "Input Sources"
        A[Email Job Alerts]
        B[Manual Telegram Trigger]
    end

    subgraph "Core Automation Engine"
        C[n8n Workflow Orchestration]
        D[PostgreSQL State Store]
    end

    subgraph "AI & Services"
        E[Claude API<br/>Proposal Generation]
        F[ClickUp<br/>Project Tracking]
        G[Toggl<br/>Time Tracking]
    end

    subgraph "Mobile Interface"
        H[Telegram Bot<br/>Approvals & Notifications]
    end

    A --> C
    B --> C
    C <--> D
    C <--> E
    C <--> F
    C <--> G
    C <--> H
    H --> User[📱 User Mobile]

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#fff4e1
    style E fill:#f0e1ff
    style H fill:#e1ffe1
    style User fill:#ffe1e1

Key Components:

Data Flow:

  1. Job alerts arrive via email → n8n parses and scores based on criteria
  2. High-scoring jobs trigger Claude API for proposal generation
  3. Proposal sent to Telegram for mobile approval
  4. Approved proposals logged in ClickUp for pipeline tracking
  5. Project lifecycle managed through automated workflows

🛠️ Tech Stack

Category Technology Why Chosen
Workflow Engine n8n Open-source, visual workflow builder, extensive integrations, self-hostable for data privacy
AI Engine Claude API (Sonnet 4.5) Superior writing quality for proposals, 200K context window, precise instruction following
Project Management ClickUp Robust API, flexible structure, mobile app, unlimited plan at $9/month
Mobile Interface Telegram Bot Universal platform, rich bot API, instant delivery, no custom app development needed
Time Tracking Toggl Simple API, widely used, Upwork integration available
Database PostgreSQL n8n workflow state, job history, performance metrics
Infrastructure Docker + DigitalOcean VPS Reproducible deployments, 4GB RAM server ($40/month), complete control

Cost Analysis:

💡 Key Technical Decisions

Challenge 1: Telegram’s Single Webhook Limitation

Problem: Telegram bots can only register ONE webhook URL globally. I needed to handle multiple workflow types (approvals, commands, notifications) but couldn’t create separate webhooks per workflow.

Options Considered:

Solution Chosen: Master router workflow with cascading IF nodes

Why:

Result: Single webhook routes to 12+ different workflow types with <100ms routing overhead

Technical Pattern (Conceptual):

// Telegram webhook receives update
// Master router examines:
// - update.message.text (for commands like /approve)
// - update.callback_query.data (for inline button presses)
// - update type (message, callback, etc.)
// Routes to appropriate sub-workflow via webhook trigger

Challenge 2: State Management in Stateless Workflows

Problem: n8n workflows are stateless by default. I needed to maintain context across multiple executions:

Options Considered:

Solution Chosen: workflow.staticData with PostgreSQL fallback

Why:

Result: Sub-second state retrieval, zero infrastructure additions

Challenge 3: Mobile-First Workflow Design

Problem: As a homeschool parent, my work happens in fragmented 10-15 minute blocks throughout the day. Desktop-based approval systems don’t work for this schedule.

Options Considered:

Solution Chosen: Telegram bot with inline keyboards

Why:

Result: 95% of system operations (screening, approvals, tracking) performed entirely from mobile device

Challenge 4: Job Discovery Without Official API

Problem: Upwork doesn’t provide official RSS feeds or job discovery API. Previous workarounds:

Options Considered:

Solution Chosen: Hybrid email parsing + Telegram manual trigger

Why:

Implementation:

  1. Configure Upwork job alerts → dedicated email address
  2. n8n Email Trigger monitors inbox via IMAP every 5 minutes
  3. Parse email to extract job details and URL
  4. Fetch full job page for additional context
  5. Telegram /submit_job <url> command for manual high-priority jobs

Result: Real-time job discovery (1-2 minute email lag) with 100% ToS compliance

📊 Results & Impact

Performance Metrics

Time Savings

Business Impact

System Reliability

🔍 Code Examples & Patterns

This repository contains conceptual examples and pseudocode to demonstrate architectural thinking. Full implementation contains proprietary business logic.

Pattern 1: Scoring Algorithm (8-Stage Matrix)

See: examples/scoring-algorithm.md

Concept: Multi-factor scoring system evaluates job opportunities across 8 dimensions (budget, client history, skills match, red flags, etc.). High-scoring jobs (≥70/100) proceed to proposal generation.

Pattern 2: State Management in n8n

See: examples/state-management.js

Concept: Using workflow.staticData for cross-execution persistence without external dependencies.

Pattern 3: Telegram Webhook Router

See: examples/webhook-router.md

Concept: Single webhook endpoint routes to multiple workflow types using pattern matching.

Pattern 4: Error Handling & Graceful Degradation

See: examples/error-handling.js

Concept: Fail-safe design where service failures trigger Telegram alerts rather than blocking workflows.

📚 Documentation

🎓 Skills Demonstrated

Technical Skills:

Architecture Patterns:

Problem-Solving:

⚠️ Note on Code Availability

This portfolio piece showcases architectural thinking and problem-solving approach. The full implementation contains proprietary business logic and is not publicly available.

What’s included in this repository:

What’s not included:

Why this approach?

This system represents significant competitive advantage in the freelance marketplace. The specific scoring criteria, prompt engineering, and workflow orchestration are the result of extensive testing and refinement. Sharing these would eliminate the advantage while the high-level architecture demonstrates technical capability.

🚀 Technical Highlights

What makes this system notable:

  1. Zero Custom Code: Entire system built with low-code tools (n8n) + AI API, demonstrating effective tool selection over reinventing wheels

  2. Mobile-First Philosophy: 95% mobile operation proves automation can work for non-desk workflows (important for parents, digital nomads, etc.)

  3. Telegram Single Webhook Solution: Novel approach to Telegram’s webhook limitation using master router pattern

  4. ToS Compliance: Email parsing approach respects platform rules while achieving automation goals

  5. Cost-Effectiveness: $67/month operating cost with multi-thousand dollar monthly ROI

  6. AI Prompt Engineering: Claude prompts refined to generate high-quality, personalized proposals (not generic templates)

💼 Project Context

Timeline: 2 weeks (initial build) + ongoing refinements Role: Solo developer - architecture, implementation, deployment Status: Production system running since January 2025 Scale: Processing 30-40 jobs/day, managing 5-10 concurrent projects

Technologies Mastered:

📧 Contact

Interested in discussing this project or similar automation challenges?

📧 Email: cbosman@praxisprotocol.io 💼 LinkedIn: linkedin.com/in/csbosman 🐙 GitHub: github.com/bozzdev

This project demonstrates capabilities in:

Available for consulting on similar automation projects, AI integration, or technical architecture.

📄 License

Documentation: MIT License Code Examples: MIT License (pseudocode/concepts only)

Portfolio piece created February 2025. Project built January 2025.

Note: This is a portfolio demonstration. For full details on implementation approach, technical deep-dives, or to discuss similar projects, please reach out directly.

This site is open source. Improve this page.