Kira
b6e5413cbf
Cross-product integration map covering all Payfrit systems, APIs, databases, and external services. New developer guide with onboarding steps, architecture overview, repo access, and team workflow reference. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
338 lines
16 KiB
Markdown
338 lines
16 KiB
Markdown
# 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.*
|