🛡️ Freelance Shield

A risk-aware toolkit for freelancers

Freelancers often get ghosted, underpaid, or manipulated. Freelance Shield helps freelancers identify risky clients before damage happens.

---

🎯 Problem Statement

Freelancing comes with inherent risks:

• Clients who avoid payment discussions
• Unrealistic timelines and scope creep
• Requests for unpaid work disguised as "opportunities"
• Vague contracts that favor clients

Freelance Shield provides practical tools to assess, document, and mitigate these risks.

---

✨ Features

1. Contract Generator

Generate professional service agreements tailored to your project:

• Project type selection (design, development, writing, etc.)
• Pricing model (fixed or hourly)
• Payment schedule (upfront, milestones, on delivery)
• Revision limits
• Clean, sectioned contract output

2. Client Risk Scoring 🔥

Rule-based risk assessment system:

• Score clients from 0-100 based on observable signals
• Weighted risk factors (unpaid work requests, payment avoidance, etc.)
• Clear explanations for each risk factor
• Visual risk badges (🟢 Low / 🟡 Medium / 🔴 High)

3. Invoice + Reminder Tracker

Track invoices and generate payment reminders:

• Create and manage invoices
• Track payment status
• Generate polite → firm reminder messages
• Copy-friendly reminder text for WhatsApp/email

4. Red Flag Detector

Detect risky language in client communications:

• Keyword and phrase pattern matching
• Severity classification (high/medium/low)
• Explanations for each detected flag
• Highlighted text preview

---

🛠️ Tech Stack

Frontend:

• React 18
• Tailwind CSS
• React Router
• Axios

Backend:

• Node.js + Express
• SQLite (MVP) - easily migratable to PostgreSQL
• RESTful API

Architecture:

• Rule-based systems (no ML hype, just explainable logic)
• Clean separation of concerns
• RESTful endpoints

---

🚀 Getting Started

Prerequisites

• Node.js 18+
• npm or yarn

Installation

1. Install dependencies:

npm install

2. Start development server:

npm run dev

This will start:

• Backend API on http://localhost:3001
• Frontend on http://localhost:3000

---

🚀 Quick Start

For setup and running instructions, see QUICKSTART.md.

📁 Project Structure

freelance-shield/
├── backend/
│   ├── db/
│   │   └── database.js          # SQLite setup & schema
│   ├── routes/
│   │   ├── contracts.js         # Contract generation endpoints
│   │   ├── clients.js           # Client risk scoring endpoints
│   │   ├── invoices.js          # Invoice tracking endpoints
│   │   └── risk.js              # Red flag detection endpoints
│   ├── services/
│   │   ├── contractGenerator.js # Contract template logic
│   │   ├── riskScoring.js       # Risk calculation engine
│   │   └── redFlagDetector.js   # Pattern matching for red flags
│   └── server.js                # Express app setup
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   └── Layout.jsx       # Main layout with navigation
│   │   ├── pages/
│   │   │   ├── Dashboard.jsx
│   │   │   ├── ContractGenerator.jsx
│   │   │   ├── ClientRiskScoring.jsx
│   │   │   ├── InvoiceTracker.jsx
│   │   │   └── RedFlagDetector.jsx
│   │   ├── App.jsx
│   │   └── main.jsx
│   └── package.json
└── README.md

---

🎨 Design Philosophy

Product Thinking:

• Solves real pain points
• Clear trade-offs (no over-engineering)
• Explainable logic (no black boxes)
• Restraint (MVP scope, not feature bloat)

Portfolio Quality:

• Demonstrates systems thinking
• Shows understanding of rule-based systems
• Clean, maintainable code
• Professional UI/UX

---

📊 Data Models

Users          - Basic user info (optional auth for v1)
Clients        - Client info + risk_score, risk_level
Contracts      - Generated contracts with parameters
Invoices       - Invoice tracking with status
RiskSignals    - Individual risk factors per client

---

🔮 Future Enhancements (Out of Scope for MVP)

• PDF export for contracts
• Email integration for reminders
• Simple NLP scoring for red flags (optional)
• User authentication
• Multi-currency support
• Export/import functionality

---

📝 License

MIT

---

🙏 Acknowledgments

Built with product engineering principles: useful, demonstrable, explainable, finishable.

---

Generated by Freelance Shield - A risk-aware toolkit for freelancers