---
name: build-sanctions-compliant-saas
description: Build sanctions-compliant SaaS platforms for restricted jurisdictions (Iran, Russia, etc.) — legal architecture, email-based integrations, and rapid MVP scaffolding.
trigger: User wants to build a system that interacts with sanctioned countries, or needs to navigate OFAC/EU sanctions while building a legitimate business.
---

# Build Sanctions-Compliant SaaS 🛡️

## Critical First Step: Legal Architecture

### ⚠️ RED LINES (never cross)

1. **NEVER handle payments** to sanctioned entities
   - You become a facilitation agent → secondary sanctions
   - Even non-US companies can be sanctioned

2. **NEVER claim to "guarantee approval"**
   - Implies influence → corruption risk

3. **NEVER use US infrastructure**
   - AWS, GCP, Stripe, US banks = violation risk

### ✅ SAFE POSITIONING

Position as **document workflow automation**, NOT payment facilitation:

```
❌ "We process Iran transit payments"
✅ "We automate transit declaration submissions"

❌ "We guarantee approval"
✅ "We format and submit your documents"

❌ "We have connections in Iran"
✅ "We follow official PGSA procedures"
```

---

## Market Research Phase

### 1. Identify the Official Body

| Country | Sector | Research Approach |
|---------|--------|-------------------|
| Iran | Maritime | PGSA.ir, IRISL, PMO Iran |
| Russia | Energy | Rosneft, Gazprom portals |
| Belarus | Logistics | State customs portals |

**Search queries:**
```
"[sector] authority [country] official"
"[country] [sector] transit requirements"
"vessel agent [country] contact"
```

### 2. Verify Integration Method

Most sanctioned countries have **NO API**:
- Email submissions only
- PDF forms
- Manual processing

**This is your opportunity** — automation where others see bureaucracy.

### 3. Identify Target Customers

| Segment | Decision Power | Willingness to Pay |
|---------|---------------|-------------------|
| Ship captains | Low | Low (not their budget) |
| Ship agents | HIGH | HIGH (their core business) |
| Fleet operators | HIGH | HIGH (volume = pain) |
| Charterers | Medium | Medium |

**Focus on agents first** — they feel the pain daily.

---

## Technical Architecture

### Core Pattern: Email-Based Integration

```
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Client    │────▶│  Your SaaS   │────▶│  Gov Email  │
│  (Dashboard)│     │  (FastAPI)   │     │  (manual)   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Status DB   │
                    │  + Tracking  │
                    └──────────────┘
```

### Key Components

1. **Form Layer** — 40-100 fields, validation
2. **Document Generator** — PDF formatting
3. **Email Service** — SMTP → official inbox
4. **Status Parser** — email responses → DB updates
5. **Dashboard** — client visibility

### Tech Stack (Sanctions-Safe)

| Component | Choice | Why |
|-----------|--------|-----|
| Hosting | Hetzner (DE) / OVH | Not US-based |
| Database | PostgreSQL | Self-hosted |
| Email | Self-hosted SMTP / EU provider | Avoid US providers |
| Payments | Crypto / Non-US processors | Avoid Stripe/PayPal |
| Domain | .com / .io / local TLD | Avoid .us |

---

## MVP Scaffolding (Fast Track)

### Database Schema (Essential Tables)

```sql
-- Companies (your customers)
companies (id, name, type, country, contact, email)

-- Assets (vessels, trucks, etc.)
assets (id, company_id, identifier, type, specs)

-- Requests (transit applications)
requests (id, asset_id, status, submitted_at, reference)

-- Documents (uploads)
documents (id, request_id, type, file_path, uploaded_at)

-- Email Log (audit trail)
email_log (id, request_id, direction, subject, status, sent_at)
```

### API Endpoints (Minimum)

```
POST   /api/v1/requests          # Create draft
POST   /api/v1/requests/:id/submit  # Submit to authority
GET    /api/v1/requests          # List with filters
GET    /api/v1/requests/:id      # Get details + status
POST   /api/v1/documents         # Upload
DELETE /api/v1/requests/:id      # Cancel (draft only)
```

### Email Template (Official Submission)

```
Subject: [Official Form Name] — [Asset ID] — ETA [Date]

Dear [Authority] Department,

Please find attached the [form type] for:

Asset: [Name/ID]
Identifier: [IMO/Registration]
ETA: [Date/Time]

Attached:
- [Document 1]
- [Document 2]
- [Document 3]

Tracking ID: [Your internal ID]

Awaiting your review.

Best regards,
[Your System Name]
```

---

## Revenue Model (Safe Structures)

### ✅ SAFE

1. **Subscription** — $X/month per company
2. **Per-Submission Fee** — $X per transit request
3. **Revenue Share with Agents** — % of their service fee
4. **Enterprise License** — flat rate for fleet operators

### ❌ UNSAFE

1. **% of Transit Fee** — looks like payment facilitation
2. **"Expedited Processing"** — implies influence
3. **"Guaranteed Approval"** — fraud risk
4. **Crypto Payments for Iran** — explicit sanctions violation

---

## Customer Acquisition

### Phase 1: Direct Outreach

```
Target: Ship agents in UAE, India, Singapore
Channel: LinkedIn + email
Message: "We automate Hormuz transit docs — save 4 hours per submission"
```

### Phase 2: Captain Network

```
Target: Tanker captains (Telegram groups, forums)
Value: Free tracking tool
Goal: Word-of-mouth to their companies
```

### Phase 3: Partnerships

```
Target: Maritime software (ship management platforms)
Deal: API integration, revenue share
```

---

## Risk Mitigation Checklist

- [ ] Legal review (sanctions attorney)
- [ ] Terms of Service explicitly disclaim payment handling
- [ ] No US infrastructure (verify all vendors)
- [ ] No US customers (geo-block if needed)
- [ ] Audit trail for all submissions
- [ ] No promises of approval/speed
- [ ] Clear separation: you = software, they = payment

---

## When to Walk Away

🚩 **Abort if:**

- Authority demands crypto payments
- No official contact/channel exists
- All competitors are sanctioned entities
- Your bank refuses to process related transactions
- Legal counsel advises against (get one!)

---

## Example: Hormuz Transit Gateway

**What we built:**
- FastAPI backend (document workflow)
- PostgreSQL (10 tables: companies, vessels, requests, documents, email_log)
- Email service → info@PGSA.ir
- Dashboard for status tracking
- Docker Compose deployment

**What we avoided:**
- Payment processing
- Claims of influence
- US infrastructure
- Direct API claims (none exists)

**Positioning:**
> "Maritime Transit Compliance Platform — automate your Hormuz transit declarations"

NOT:
> "Pay Iran transit fees through our platform"

---

## Reusable Templates

See: `hormuz-gateway/` project structure for:
- Database schema (10 tables)
- FastAPI endpoints (CRUD + submit)
- Email service (SMTP → authority)
- Docker Compose (dev + production)
- PGSA inquiry letter template

---

## Related Skills

- `api-integration` — REST API patterns
- `email` — SMTP configuration
- `deployment` — Docker, hosting
- `ecc-safety-guard` — Production safety checks