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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
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.*