payfrit/payfrit-docs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add integration map and new developer guide

Browse source 
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>
This commit is contained in:
Kira 2026-03-26 05:53:31 +00:00
parent fbb38ae0a7
commit b6e5413cbf
2 changed files with 774 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

338
integration-map.md Normal file
View file

@ -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/<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.*

436
new-developer-guide.md Normal file
View file

@ -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 <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.*