payfrit-docs/integration-map.md

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.