# Payfrit Integration Map

> Cross-product architecture reference showing how all Payfrit systems connect.
> Generated by @kira — 2026-03-26

---

## System Overview

Payfrit is a multi-product platform with 6 major components, 11 active bot agents, and integrations with Stripe, Twilio, Open Food Facts, and Mattermost.

```
┌─────────────────────────────────────────────────────────────────────┐
│                        EXTERNAL SERVICES                            │
│  ┌─────────┐  ┌─────────┐  ┌────────────────┐  ┌──────────────┐   │
│  │ Stripe   │  │ Twilio  │  │ Open Food Facts│  │ Mattermost   │   │
│  │ Payments │  │ SMS/OTP │  │ Product Data   │  │ Team Chat    │   │
│  └────┬─────┘  └────┬────┘  └───────┬────────┘  └──────┬───────┘   │
└───────┼──────────────┼───────────────┼───────────────────┼──────────┘
        │              │               │                   │
┌───────┼──────────────┼───────────────┼───────────────────┼──────────┐
│       ▼              ▼               ▼                   ▼          │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    PAYFRIT SERVER (69.48.207.164)           │    │
│  │                    Ubuntu 24.04 · Plesk Managed             │    │
│  │                                                             │    │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐  │    │
│  │  │payfrit-  │  │payfrit-  │  │payfrit-  │  │payfrit-   │  │    │
│  │  │biz       │  │api       │  │food      │  │cloud      │  │    │
│  │  │(CFML)    │  │(PHP)     │  │(PHP)     │  │(Node.js)  │  │    │
│  │  │Port 443  │  │Port 443  │  │Port 443  │  │Port 3100  │  │    │
│  │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │    │
│  │       │              │             │              │         │    │
│  │       ▼              ▼             ▼              │         │    │
│  │  ┌──────────────────────────────────────┐         │         │    │
│  │  │         MariaDB 10.11.14             │         │         │    │
│  │  │  ┌──────────┐  ┌──────────────┐      │         │         │    │
│  │  │  │ payfrit  │  │ payfrit_food │      │         │         │    │
│  │  │  │(main DB) │  │ (food DB)    │      │         │         │    │
│  │  │  └──────────┘  └──────────────┘      │         │         │    │
│  │  └──────────────────────────────────────┘         │         │    │
│  │                                                   │         │    │
│  │  ┌────────────────────────────────────────────────┘         │    │
│  │  │  Bot Fleet (11 agents)                                   │    │
│  │  │  systemd services → Claude CLI → Mattermost              │    │
│  │  └──────────────────────────────────────────────────────────┘    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌──────────────────────┐  ┌──────────────────────┐                │
│  │ payfrit-theme        │  │ payfrit-beacon-ios   │                │
│  │ WordPress @ wp.      │  │ iOS BLE beacon mgmt  │                │
│  │ payfrit.com          │  │ app (SwiftUI)        │                │
│  └──────────────────────┘  └──────────────────────┘                │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Products & Their Roles

### 1. payfrit-biz (Core Business Platform)
| Field | Value |
|-------|-------|
| **Stack** | CFML (Lucee 5.x), Bootstrap 5.3, Vanilla JS |
| **Hosts** | `dev.payfrit.com` (dev), `biz.payfrit.com` (prod) |
| **Database** | `payfrit` / `payfrit_dev` (MySQL via ODBC) |
| **Git** | `https://git.payfrit.com/payfrit/payfrit-biz` |
| **Endpoints** | ~50+ REST API endpoints across 31 domains |

**What it does:** The main business management platform. Handles restaurant/venue onboarding, menu management, order processing, kitchen display (KDS), task management (HUD), payment processing, worker management, beacon/service-point configuration, and the business admin portal.

**Sub-applications:**
- `/portal/` — Business admin SPA (dashboard, menu builder, onboarding wizard)
- `/kds/` — Kitchen Display System (polls orders every 5s)
- `/hud/` — Task HUD for workers (visual task bars, 3s polling)
- `/receipt/` — Public receipt page (UUID-secured, no auth)
- `/admin/` — God mode, beacon management, email tools

---

### 2. payfrit-api (PHP API Layer)
| Field | Value |
|-------|-------|
| **Stack** | PHP 8.3, PDO, no framework |
| **Database** | `payfrit` / `payfrit_dev` (MySQL at 10.10.0.1) |
| **Endpoints** | 182 REST endpoints across 26 modules |

**What it does:** A comprehensive PHP API covering the same domain as payfrit-biz but in PHP. Handles orders, payments, auth, tabs, tasks, chat, beacons, grants, workers, menus, and more. This is the API consumed by mobile clients.

**Key modules:** auth (12), orders (17), stripe (5), tabs (13), tasks (19), menu (13), businesses (9), chat (5), grants (9), beacons (18), workers (6), portal (8)

**Webhook handlers:**
- `/_webhook/deploy.php` — Git push auto-deploy (Forgejo signature validation)
- `/api/stripe/webhook.php` — Stripe events (payment success/failure, refunds, disputes, Connect updates, tip transfers)

---

### 3. payfrit-food (Food Intelligence Platform)
| Field | Value |
|-------|-------|
| **Stack** | PHP 8.3, Vanilla HTML/CSS/JS |
| **Database** | `payfrit_food` (own DB) + cross-refs to `payfrit.Users` |
| **Hosts** | `dev.payfrit.com/food/` |

**What it does:** Product intelligence and health discovery. Consumers scan barcodes to get independent health scores. Sponsors (brands/retailers) buy tokens to list products with pricing/delivery. Zero user tracking philosophy.

**Sub-applications:**
- `/portal/` — Consumer mobile app (scanner, product cards, alternatives)
- `/sponsor/` — Sponsor dashboard (token management, Stripe checkout)

**Unique features:**
- Independent scoring algorithm (nutrition 45% + ingredients 35% + NOVA 20%)
- Token-based monetization ($5/token base, bulk discounts to $2/token)
- Delivery requests create Tasks in main `payfrit.Tasks` table

---

### 4. payfrit-cloud (Orchestration API + Bot Fleet)
| Field | Value |
|-------|-------|
| **Stack** | Node.js (Express), systemd, Bash |
| **Port** | 3100 |
| **Location** | `/opt/payfrit-cloud/` |

**What it does:** Central control plane for the entire bot infrastructure. Manages bot lifecycle (start/stop/restart), system monitoring, workspace file access, Docker dev environments, and deployment tracking.

**Bot execution modes:**
1. **Per-bot bash loop** (`bot-runner.sh`) — Polls Mattermost every 10s, spawns Claude CLI
2. **Centralized dispatcher** (`dispatcher.js`) — Single daemon routes messages to bots

**Bot fleet (11 active):**
| Bot | Role |
|-----|------|
| alex | Weedops |
| ava | Designer |
| jude | WordPress |
| kira | General Agent |
| koda | Kotlin/Android |
| luna | QA & Testing |
| mike | Backend |
| nora | Sponsor Portal |
| priya | HR & Operations |
| schwifty | DevOps |
| zara | User Portal |

---

### 5. payfrit-theme (Marketing Website)
| Field | Value |
|-------|-------|
| **Stack** | WordPress (PHP), custom theme |
| **Host** | `wp.payfrit.com` |

**What it does:** Corporate marketing site. Multi-page theme with home, how-it-works, restaurants, large-venues, and about pages. Links to App Store downloads and the business portal.

---

### 6. payfrit-beacon-ios (iOS Beacon Manager)
| Field | Value |
|-------|-------|
| **Stack** | SwiftUI, iOS 16.0+ |
| **Dependencies** | Kingfisher, SVGKit |

**What it does:** iOS app for managing BLE beacons at business locations. Phone OTP login, business selection, beacon CRUD, service point assignment, and a BLE scanner showing signal strength.

---

## Database Architecture

### Shared Database: `payfrit` (main)
Used by: **payfrit-biz**, **payfrit-api**, **payfrit-food** (cross-DB refs)

| Table | Used By | Purpose |
|-------|---------|---------|
| Users | all | User accounts, auth, Stripe customer IDs |
| UserTokens | all | Session tokens (X-User-Token auth) |
| OTPCodes | biz, api, food | OTP verification |
| Orders | biz, api | Order lifecycle |
| OrderLineItems | biz, api | Cart items with modifiers |
| Items | biz, api | Menu items |
| Categories | biz, api | Menu categories |
| Menus | biz, api | Menu containers |
| Businesses | biz, api, food | Business profiles |
| Employees | biz, api | Staff assignments |
| ServicePoints | biz, api | Tables/locations |
| Beacons | biz, api, ios | BLE beacon registry |
| Tasks | biz, api, food | Work items (kitchen, delivery) |
| ChatMessages | biz, api | Order/task communication |
| Tabs | biz, api | Running tabs (split pay) |
| TabMembers | biz, api | Tab participants |
| Workers | biz, api | Gig worker accounts |
| WorkPayoutLedgers | biz, api | Stripe Connect payouts |
| ServicePointGrants | biz, api | Access control |
| PaymentAudit | biz, api | Payment event log |
| ApiPerfLogs | biz | API performance profiling |

### Separate Database: `payfrit_food`
Used by: **payfrit-food** only

| Table | Purpose |
|-------|---------|
| Products | Food products (OFF data + sponsor submissions) |
| Categories | Food categories (hierarchical) |
| Sponsors | Brands/retailers paying for listings |
| SponsorProducts | Active product listings (token-based) |
| TokenPurchases | Payment history |
| TokenPricing | Bulk discount tiers |
| UserScans | Scan history (refs payfrit.Users.ID) |
| UserFavorites | Saved products |
| Additives | E-number reference for scoring |

---

## Integration Points

### Cross-Service Data Flows

```
payfrit-food ──── delivery request ────→ payfrit.Tasks table
     │                                        ↑
     │                                        │
     └──── user auth ─────→ payfrit.Users ←───┤
                            payfrit.UserTokens │
                                        ↑     │
payfrit-biz ────────────────────────────┘     │
payfrit-api ──────────────────────────────────┘
payfrit-beacon-ios ── X-User-Token ──→ payfrit-api endpoints
```

### Authentication Flow (Shared Across All Products)
1. User sends phone number → `sendOTP` endpoint
2. SMS sent via Twilio
3. User verifies OTP → token issued (SHA-256, 64-char hex)
4. Token stored in `payfrit.UserTokens`
5. All subsequent requests include `X-User-Token` header
6. Magic OTP `123456` enabled for App Store review

### Payment Flow (Stripe)
```
Customer places order
    → payfrit-api creates Stripe PaymentIntent
    → Customer pays (card)
    → Stripe webhook fires
    → payfrit-api/biz processes:
        ├── Order marked as paid
        ├── Kitchen tasks created
        ├── Worker payouts queued (Stripe Connect)
        ├── Grant owner fees transferred
        └── PaymentAudit record logged
```

### Stripe Configuration
| Setting | Value |
|---------|-------|
| Customer fee | 5% |
| Business fee | 5% |
| Stripe processing | 2.9% + $0.30 |
| Activation cap | $25 default |
| Mode | TEST (currently) |

---

## External Service Dependencies

| Service | Used By | Purpose |
|---------|---------|---------|
| **Stripe** | biz, api, food | Card payments, Connect payouts, subscriptions |
| **Twilio** | biz, api, food | SMS OTP, notifications |
| **Open Food Facts** | food | Barcode → product data lookup |
| **Mattermost** | cloud (bots) | Team chat, bot command routing |
| **Forgejo** | biz, api | Git hosting, deploy webhooks |

---

## Server Infrastructure

| Component | Details |
|-----------|---------|
| **Server** | 69.48.207.164, Ubuntu 24.04, 2 vCPU, 3.8GB RAM |
| **Web server** | Apache 2.x (Plesk managed) |
| **App server** | Lucee 5.x (CFML), PHP 8.3-fpm, Node.js 20 |
| **Database** | MariaDB 10.11.14 (localhost 3306) |
| **Containers** | Docker CE 29.3.0 (available, not actively used) |
| **Bot services** | systemd template `payfrit-bot@.service` |
| **Orchestration** | payfrit-cloud.service on port 3100 |
| **Monitoring** | Heartbeat every 5min, health alerts to #dev |
| **Logs** | `/var/log/payfrit-bots/` per bot |

### Key Ports
| Port | Service |
|------|---------|
| 22 | SSH |
| 80/443 | Apache (HTTP/HTTPS) |
| 3100 | Payfrit Cloud API |
| 3306 | MariaDB (localhost) |
| 8443 | Plesk panel |

### Key Filesystem Paths
| Path | Contents |
|------|----------|
| `/opt/payfrit-cloud/` | Orchestration API + bot runner |
| `/home/<agent>/workspace/` | Per-agent workspaces |
| `/var/log/payfrit-bots/` | Bot logs |
| `/etc/payfrit/bots/` | Bot credentials (.env files) |
| `/etc/systemd/system/payfrit-bot@.service` | Bot service template |

---

## Deployment

### Git Repos (Forgejo @ git.payfrit.com)
| Repo | Deploy Target |
|------|---------------|
| `payfrit/payfrit-biz` | `dev.payfrit.com` / `biz.payfrit.com` |
| `payfrit/payfrit-api` | API server (webhook auto-deploy) |
| `payfrit/payfrit-food` | `dev.payfrit.com/food/` |

### Deploy Flow
1. `git push` to Forgejo
2. Forgejo fires webhook to `/_webhook/deploy.php`
3. Webhook validates signature, creates trigger file
4. Server pulls latest code
5. Live within ~1 minute

---

## Cron Jobs

| Job | Frequency | Service | Purpose |
|-----|-----------|---------|---------|
| Tab expiry | Every 5 min | payfrit-api | Expire idle tabs, cleanup Stripe PIs |
| Chat expiry | Periodic | biz, api | Close stale chat sessions |
| Heartbeat | Every 5 min | cloud | Bot health, token expiry, crash detection |
| Bot polling | Every 10s | cloud | Check Mattermost for messages |

---

*This document is a living reference. Update it as new services, integrations, or products are added.*