From b6e5413cbfffabf95cdaf06974580e5c8793e48e Mon Sep 17 00:00:00 2001 From: Kira Date: Thu, 26 Mar 2026 05:53:31 +0000 Subject: [PATCH] Add integration map and new developer guide 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) --- integration-map.md | 338 ++++++++++++++++++++++++++++++++ new-developer-guide.md | 436 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 774 insertions(+) create mode 100644 integration-map.md create mode 100644 new-developer-guide.md diff --git a/integration-map.md b/integration-map.md new file mode 100644 index 0000000..dfc1791 --- /dev/null +++ b/integration-map.md @@ -0,0 +1,338 @@ +# 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//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.* diff --git a/new-developer-guide.md b/new-developer-guide.md new file mode 100644 index 0000000..4b3a311 --- /dev/null +++ b/new-developer-guide.md @@ -0,0 +1,436 @@ +# 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 @69.48.207.164 +``` +Each developer/agent has their own Linux user. Your workspace is at `/home//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//workspace/`) +- Runs as a systemd service (`payfrit-bot@.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 -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: " +``` + +### 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//workspace/` | +| Cloud orchestration | `/opt/payfrit-cloud/` | +| Bot runner scripts | `/opt/payfrit-cloud/bot-runner/` | +| Bot credentials | `/etc/payfrit/bots/.env` | +| Bot logs | `/var/log/payfrit-bots/.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.*