payfrit-docs/new-developer-guide.md

Payfrit — New Developer Guide

Everything you need to get oriented and productive on Payfrit. Generated by @kira — 2026-03-26

---

Welcome

Payfrit is a multi-product platform for food ordering, payments, and business operations. You're joining a team of humans and AI agents that ship fast. This guide will get you up to speed.

---

1. The Products

Product	What It Does	Stack	Repo
payfrit-biz	Core business platform — orders, menus, KDS, payments, admin portal	CFML (Lucee 5.x), Bootstrap 5, Vanilla JS	payfrit/payfrit-biz
payfrit-api	PHP API layer — same domain as biz, consumed by mobile clients	PHP 8.3, PDO, no framework	payfrit/payfrit-api
payfrit-food	Food intelligence — barcode scanning, health scores, sponsor marketplace	PHP 8.3, Vanilla JS	payfrit/payfrit-food
payfrit-cloud	Bot orchestration — manages 11 AI agents, system monitoring	Node.js (Express), Bash, systemd	(on server at /opt/payfrit-cloud/)
payfrit-theme	Marketing website	WordPress PHP theme	payfrit/payfrit-theme
payfrit-beacon-ios	iOS BLE beacon management app	SwiftUI (iOS 16+)	payfrit/payfrit-beacon-ios

---

2. Server Access

The Server

• IP: 69.48.207.164
• OS: Ubuntu 24.04.4 LTS
• Managed via: Plesk (panel at :8443)

SSH Access

ssh <your-username>@69.48.207.164

Each developer/agent has their own Linux user. Your workspace is at /home/<you>/workspace/.

Key URLs

URL	What
https://dev.payfrit.com	Development environment (payfrit-biz)
https://biz.payfrit.com	Production (payfrit-biz)
https://dev.payfrit.com/food/	Development (payfrit-food)
https://wp.payfrit.com	Marketing site (WordPress)
https://git.payfrit.com	Forgejo git server
https://mm.payfrit.com	Mattermost team chat
http://69.48.207.164:3100	Cloud orchestration API

---

3. Tech Stack Quick Reference

Layer	Technology
Business backend	CFML (Lucee 5.x) — .cfm and .cfc files
API backend	PHP 8.3 (plain files, no framework)
Food backend	PHP 8.3 (plain files, no framework)
Orchestration	Node.js 20 (Express)
iOS app	SwiftUI (iOS 16+, Kingfisher, SVGKit)
Frontends	Vanilla JavaScript — no React, no Vue, no Angular
CSS	Bootstrap 5.3.0 (CDN) + custom CSS
Database	MariaDB 10.11.14 (MySQL-compatible)
Payments	Stripe (PaymentIntents, Connect, Webhooks)
SMS	Twilio
Web server	Apache 2.x (Plesk managed)
Git	Forgejo (self-hosted at git.payfrit.com)
Chat	Mattermost (self-hosted at mm.payfrit.com)
Deployment	Git push → webhook → auto-pull (~1 min)

---

4. Repository Structure

payfrit-biz (CFML)

payfrit-biz/
├── api/                    # REST API (31 domains, 50+ endpoints)
│   ├── Application.cfm     # Auth gate, public endpoint allowlist
│   ├── config/             # environment.cfm, stripe.cfm
│   ├── auth/               # Login, OTP, profile
│   ├── orders/             # Order lifecycle
│   ├── menu/               # Menu CRUD
│   ├── stripe/             # Payment intents, webhooks
│   ├── tabs/               # Running tabs
│   ├── tasks/              # Task management
│   ├── businesses/         # Business profiles
│   ├── beacons/            # Beacon management
│   ├── grants/             # Access control
│   ├── workers/            # Gig worker management
│   └── ... (31 dirs total)
├── portal/                 # Business admin SPA
│   ├── index.html          # Dashboard
│   ├── portal.js           # 175KB — all portal logic
│   ├── menu-builder.html   # Menu editor
│   └── setup-wizard.html   # Onboarding
├── kds/                    # Kitchen Display System
│   ├── index.html          # Full-screen order display
│   └── kds.js              # Polls every 5 seconds
├── hud/                    # Task HUD for workers
│   ├── index.html          # Task visualization
│   └── hud.js              # Polls every 3 seconds
├── receipt/                # Public receipt page
├── admin/                  # Admin tools (god_mode, beacons, email)
├── library/cfc/            # CFC classes (businessMaster, twilio)
└── migrations/             # SQL migrations

payfrit-api (PHP)

payfrit-api/
├── api/                    # REST API (26 modules, 182 endpoints)
│   ├── helpers.php         # DB utils, auth middleware, scoring
│   ├── config/             # Stripe config
│   ├── auth/               # 12 auth endpoints
│   ├── orders/             # 17 order endpoints
│   ├── stripe/             # Payment + webhook
│   ├── tabs/               # 13 tab endpoints
│   ├── tasks/              # 19 task endpoints
│   └── ... (26 dirs total)
├── _webhook/               # Deploy webhook (Forgejo)
├── receipt/                # Public receipt (PHP version)
├── config/                 # twilio.json
└── cron/                   # Scheduled jobs

payfrit-food (PHP)

payfrit-food/
├── api/                    # REST API
│   ├── scan.php            # Barcode lookup
│   ├── search.php          # Product search
│   ├── alternatives.php    # Healthier alternatives
│   ├── deliver.php         # Delivery requests
│   ├── user/               # User auth, scans, favorites, premium
│   ├── sponsor/            # Sponsor CRUD, tokens, purchases
│   └── webhook/            # Stripe webhook
├── portal/                 # Consumer web app (scanner UI)
├── sponsor/                # Sponsor dashboard
├── sql/                    # Database schema
├── config/                 # stripe.json, twilio.json
└── bot/                    # Mattermost bot integration

---

5. Database

Connection Info

• Host: 10.10.0.1 (internal) / localhost (from server)
• Port: 3306
• Engine: MariaDB 10.11.14

Databases

Database	Used By	Purpose
payfrit	biz, api, food (cross-ref)	Main production data
payfrit_dev	biz, api	Development mirror
payfrit_food	food	Food product intelligence

Key Tables (Main DB)

• Users — All user accounts (shared across all products)
• UserTokens — Session tokens for API auth
• Businesses — Restaurant/venue profiles
• Orders / OrderLineItems — Order data with modifier support
• Items / Categories / Menus — Menu structure
• Tasks — Work items (kitchen prep, delivery, etc.)
• Employees — Staff assignments
• ServicePoints — Tables/locations within a business
• Beacons — BLE hardware registry
• Tabs / TabMembers — Running tab system
• Workers / WorkPayoutLedgers — Gig worker payouts
• ChatMessages — Order/task communication

Important: Modifier Virtual IDs

Menu items use a virtual ID system for modifiers:

• Templates are Items with ParentItemID=0, CategoryID=0
• Linked to menu items via lt_ItemID_TemplateItemID
• API returns virtualID = menuItemID * 100000 + templateItemID
• To decode: realItemID = virtualID MOD 100000

---

6. Authentication

All products share the same auth system:

OTP Login Flow

POST /api/auth/sendOTP    →  { ContactNumber: "5551234567" }
                          ←  SMS sent via Twilio

POST /api/auth/verifyOTP  →  { ContactNumber: "5551234567", Code: "123456" }
                          ←  { Token: "abc123...", UserID: 42, ... }

Using the Token

GET /api/orders/history
Headers:
  X-User-Token: abc123...
  X-Business-ID: 5          (optional, for business context)

Dev Shortcuts

• Magic OTP: 123456 works for any number (App Store review + dev)
• Magic phones: 5555555555, 0000000000
• Dev token expiry: 720 hours (vs 24h in prod)

---

7. Payment System (Stripe)

Current Mode: TEST

Test Public Key: pk_test_sPBNzSyJ9HcEPJGC7dSo8NqN

Fee Structure

Fee	Rate
Customer service fee	5%
Business fee	5%
Stripe processing	2.9% + $0.30

Payment Flow

1. Client calls POST /api/stripe/createPaymentIntent with order details
2. Stripe returns clientSecret
3. Client confirms payment with Stripe.js
4. Stripe fires webhook → order marked paid → kitchen tasks created → worker payouts queued

Stripe Connect

Businesses and workers each have Stripe Connected Accounts for receiving payouts.

---

8. Deployment

How Deploys Work

1. Push to Forgejo (git.payfrit.com)
2. Forgejo webhook hits /_webhook/deploy.php
3. Webhook validates X-Forgejo-Signature
4. Creates trigger file → server pulls latest
5. Live in ~1 minute

Environment Detection

• Dev: hostname != "biz" → uses payfrit_dev DB, debug ON, detailed errors
• Prod: hostname == "biz" → uses payfrit DB, debug OFF, generic errors

Key Differences: Dev vs Prod

Setting	Dev	Prod
Database	payfrit_dev	payfrit
Debug logging	ON	OFF
Error details	Full stack traces	Generic message
Rate limiting	OFF	60 req/min
Email routing	Catch-all to dev-emails@	Real recipients
Token expiry	720 hours	24 hours

---

9. The Bot Team

Payfrit runs 11 AI agents powered by Claude, coordinated through Mattermost. Each bot:

• Has its own Linux user and workspace (/home/<name>/workspace/)
• Runs as a systemd service (payfrit-bot@<name>.service)
• Has a role-specific prompt in its CLAUDE.md
• Maintains persistent memory (memory.json) and conversation history

Team Roster

Agent	Handle	Role	Key Skills
Alex	@alex	Weedops	Cannabis ops
Ava	@ava	Designer	UI/UX design
Jude	@jude	WordPress	WordPress dev
Kira	@kira	General Agent	Research, scripts, docs, coordination
Koda	@koda	Kotlin/Android	Android development
Luna	@luna	QA & Testing	Testing, quality assurance
Mike	@mike	Backend	Backend development
Nora	@nora	Sponsor Portal	Sponsor features
Priya	@priya	HR & Operations	Team ops, coordination
Schwifty	@schwifty	DevOps	Infrastructure, deployment
Zara	@zara	User Portal	User-facing features

Working With Bots

• @mention a bot in Mattermost to assign it work
• Bots respond within seconds (10s poll cycle)
• Bots can see ambient messages in their channels
• Max 3 thread replies unless directly @mentioned
• Each bot has real file system access to its workspace

Bot Management

# Check a bot's status
systemctl status payfrit-bot@kira

# View bot logs
tail -f /var/log/payfrit-bots/kira.log

# Restart a bot
sudo systemctl restart payfrit-bot@schwifty

# List all bot services
systemctl list-units 'payfrit-bot@*'

---

10. Common Dev Tasks

Checking Server Health

# System resources
htop

# Disk usage
df -h

# MariaDB status
systemctl status mariadb

# Apache status
systemctl status apache2

# Cloud API health
curl http://localhost:3100/api/health

Working With the Database

# Connect to MariaDB
mysql -u <user> -p

# Switch databases
USE payfrit_dev;

# Check recent orders
SELECT ID, UUID, StatusID, CreatedAt FROM Orders ORDER BY ID DESC LIMIT 10;

Testing API Endpoints

# Get a token (dev - use magic OTP)
curl -X POST https://dev.payfrit.com/api/auth/sendOTP \
  -H "Content-Type: application/json" \
  -d '{"ContactNumber": "5555555555"}'

curl -X POST https://dev.payfrit.com/api/auth/verifyOTP \
  -H "Content-Type: application/json" \
  -d '{"ContactNumber": "5555555555", "Code": "123456"}'

# Use the token
curl https://dev.payfrit.com/api/businesses/list \
  -H "X-User-Token: <your-token>"

Viewing Bot Orchestration

# All bot statuses via API
curl http://localhost:3100/api/bot-status | jq .

# Single bot details
curl http://localhost:3100/api/bot-status/schwifty | jq .

# Team overview
curl http://localhost:3100/api/team-status | jq .

---

11. Key Contacts & Ownership

Area	Owner
Overall direction	John (human, project lead)
Business platform (biz)	Mike (@mike), Schwifty (@schwifty)
API layer	Mike (@mike)
Food platform	Nora (@nora), Mike (@mike)
User portal	Zara (@zara)
Sponsor portal	Nora (@nora)
Android app	Koda (@koda)
iOS beacon app	(needs owner)
WordPress site	Jude (@jude)
Design/UX	Ava (@ava)
QA/Testing	Luna (@luna)
Infrastructure	Schwifty (@schwifty), Raj (@raj)
HR/Operations	Priya (@priya)
General/Research	Kira (@kira)

---

12. Quick Reference: File Locations

What	Where
Agent workspaces	/home/<name>/workspace/
Cloud orchestration	/opt/payfrit-cloud/
Bot runner scripts	/opt/payfrit-cloud/bot-runner/
Bot credentials	/etc/payfrit/bots/<name>.env
Bot logs	/var/log/payfrit-bots/<name>.log
Bot service template	/etc/systemd/system/payfrit-bot@.service
Apache webroot	/var/www/html/
Plesk vhosts	/var/www/vhosts/

---

13. Development Workflow

1. Clone the repo from git.payfrit.com
2. Branch off main for your feature
3. Develop — test against dev.payfrit.com / payfrit_dev DB
4. Push to Forgejo → auto-deploys to dev
5. Test on dev environment
6. Merge to main → auto-deploys to production
7. Coordinate via Mattermost — tag relevant bots/people

Git Server

git clone https://git.payfrit.com/payfrit/payfrit-biz.git
git clone https://git.payfrit.com/payfrit/payfrit-api.git

---

Tips

• No frameworks — everything is vanilla. Read the code directly, no magic.
• CFML is weird — if you haven't seen ColdFusion before, it's tag-based server scripting. Lucee is the open-source engine. queryExecute() is your friend.
• The bots are real — they have actual file system access and can make changes. Treat their @mentions like pinging a teammate.
• Stripe is in TEST mode — use Stripe test card 4242 4242 4242 4242 for payments.
• Ask in Mattermost — if you're stuck, @mention the right bot or ask in the relevant channel.

---

This guide is maintained by @kira. Last updated 2026-03-26.