---
created: 2026-03-12
source: Growth-Engine
tags: [agent-archive, growth-engine]
---

# PHASE 1: TECHNICAL ARCHITECTURE ANALYSIS
**Date:** February 3, 2026  
**Location:** `/home/ccuser/rateright-main-site`

## 🎯 EXECUTIVE SUMMARY

**The RateRight marketplace is a PRODUCTION-READY Flask application with:**
- ✅ **Complete marketplace functionality** (jobs, applications, contracts)
- ✅ **Stripe integration** (payments, escrow, invoices)
- ✅ **Professional deployment** (Fly.io, Docker, CI/CD)
- ✅ **Australian compliance** (GST, ABN, WHS)
- ✅ **Modern tech stack** (Flask, SQLAlchemy, PostgreSQL)

**Current monetization:** **7% platform fee** (percentage-based, with 3% referral discount)
**Proposed monetization:** **£50 flat fee + £10/week insurance**

## 🔧 TECH STACK DETAILS

### **Core Framework**
- **Flask 2.3.3** (Python web framework)
- **SQLAlchemy 2.0** (ORM)
- **PostgreSQL** (database)
- **Alembic 1.16.4** (database migrations)

### **Key Extensions**
- `Flask-JWT-Extended 4.5.3` (authentication)
- `Flask-Login 0.6.3` (user sessions)
- `Flask-Cors 4.0.0` (CORS support)
- `Flask-Migrate 4.0.5` (database migrations)
- `Flask-SocketIO 5.3.4` (real-time features)
- `Flask-WTF 1.2.1` (forms)

### **Payment Integration**
- `stripe 12.4.0` (full Stripe API integration)
- **Features**: PaymentIntents, escrow, transfers, webhooks
- **Current model**: 7% platform fee (percentage of job value)

### **Hosting & Deployment**
- **Platform**: Fly.io (modern cloud platform)
- **Region**: Sydney (`syd`)
- **Container**: Docker multi-stage build
- **Web server**: Gunicorn with 4 workers
- **Health checks**: Automated (30s intervals)

### **Database**
- **PostgreSQL** via SQLAlchemy
- **Models**: 15+ tables (users, jobs, applications, contracts, payments, invoices)
- **Migrations**: Alembic with version control

## 📁 APPLICATION STRUCTURE

```
app/
├── blueprints/           # Modular Flask blueprints
│   ├── marketplace/     # Job listings, applications (CRITICAL)
│   ├── legal/          # Stripe webhooks, payment processing
│   ├── contracts/      # Contract management
│   ├── auth/           # Authentication
│   ├── notifications/  # Email/push notifications
│   └── 8 other modules
├── models/              # Database models
│   ├── user.py         # User profiles (contractors/workers)
│   ├── job.py          # Job listings
│   ├── contract.py     # Contracts, Payment, Invoice models
│   └── 12 other models
├── services/           # Business logic
│   ├── stripe_service.py      # Payment processing
│   └── notification_service.py
├── templates/          # HTML templates
│   ├── payments/       # Payment forms, history
│   ├── contracts/      # Contract views
│   └── 15 other sections
└── static/            # CSS, JS, images
```

## 💰 CURRENT PAYMENT SYSTEM ANALYSIS

### **Payment Model (Existing)**
```
1. Contractor posts job (free)
2. Worker applies (free)
3. Contractor accepts application → Creates contract
4. Contractor pays TOTAL amount to escrow (job value + 7% platform fee)
5. Work completed → Payment released to worker (minus 7% fee)
```

### **Payment Flow Details**
1. **PaymentIntent created** when contract is signed
2. **7% platform fee** deducted from worker's payment
3. **GST handling** (10% for GST-registered workers)
4. **Escrow system** (funds held until work completion)
5. **Stripe transfers** to worker's connected account

### **Database Models (Payment-related)**
1. **`Payment`** (`payments` table)
   - `stripe_payment_intent_id`
   - `platform_fee` (7% currently)
   - `gross_amount`, `net_to_worker`
   - Status: `pending`, `held_escrow`, `released`, etc.

2. **`Invoice`** (`invoices` table)
   - GST-compliant invoices
   - ABN validation
   - Australian tax compliance

3. **`Contract`** (`contracts` table)
   - Links contractor + worker + job
   - `agreed_rate` (hourly/daily rate)
   - Status: `draft`, `signed`, `active`, `completed`

## 🎯 KEY FINDINGS FOR £50+£10 MODEL

### **1. Current Fee Location**
**File**: `app/models/contract.py` (line ~350)
```python
platform_fee_rate = 0.07  # Default 7%
# If referral match: platform_fee_rate = 0.03  # 3% discount
self.platform_fee = base_amount * platform_fee_rate
```

### **2. Hiring Flow Location**
**File**: `app/blueprints/marketplace/routes.py` (line 534-555)
```python
if new_status == ApplicationStatus.ACCEPTED:
    # Contractor accepts worker → Creates contract
    # THIS IS WHERE £50 FEE SHOULD BE CHARGED
```

### **3. Stripe Integration Ready**
**File**: `app/services/stripe_service.py`
- Already has `create_payment_intent()`
- Already has `capture_payment()`
- Already has webhook handling
- **Just need to change amount from 7% to £50**

## 🔧 TECHNICAL IMPLICATIONS

### **Database Changes Needed**
1. **New column**: `hire_fee_paid` (boolean) in `contracts` table
2. **New column**: `hire_fee_amount` (decimal) in `payments` table
3. **New table**: `insurance_subscriptions` (for £10/week)
4. **New table**: `insurance_claims` (worker claims system)

### **Code Changes Needed**
1. **Modify** `app/blueprints/marketplace/routes.py`
   - Add £50 Stripe charge when application accepted
2. **Modify** `app/models/contract.py`
   - Change `platform_fee_rate` from 0.07 to flat £50 calculation
3. **Create** `app/blueprints/insurance/`
   - Subscription management
   - Claims processing
   - Fund tracking

### **UI Changes Needed**
1. **Worker dashboard**: "Buy insurance" button
2. **Contractor hiring**: Show £50 fee before accepting worker
3. **Claims portal**: "File claim if not paid" form

## ⚠️ RISK ASSESSMENT

### **Low Risk Changes**
- Changing 7% to £50 is simple arithmetic change
- Stripe integration already works
- Database schema changes are additive

### **Medium Risk Changes**
- Insurance subscription system (new feature)
- Claims processing (new business logic)
- Legal email automation (new integration)

### **High Risk Changes**
- Modifying existing payment flows
- Migrating existing contracts from % to flat fee
- Ensuring backward compatibility

## 🎯 NEXT STEPS FOR PHASE 2

### **Immediate Actions (Week 1)**
1. **Analyze current Stripe webhook flow**
2. **Test modifying platform fee to £50**
3. **Create database migration scripts**
4. **Update UI to show £50 fee**

### **Documentation Needed**
1. **Stripe webhook endpoints** (current setup)
2. **Payment flow diagrams** (current vs new)
3. **Database schema changes** (migration plan)
4. **Testing strategy** (before/after modifications)

---

**NEXT**: Phase 2 - Business Logic Analysis (User Journeys & Feature Mapping)