justin/new-site
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit — Performance West telecom compliance platform

Browse source 
Includes: API (Express/TypeScript), Astro site, Python workers,
document generators, FCC compliance tools, Canada CRTC formation,
Ansible infrastructure, and deployment scripts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
justin 2026-04-27 06:54:22 -05:00
commit f8cd37ac8c
1823 changed files with 145167 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

88
docs/annual-report-fees-by-state.md Normal file
View file

@ -0,0 +1,88 @@
# LLC Annual Report / Renewal Fees by State
> Source: LLC University (llcuniversity.com), updated July 2025 for 2026 fees.
> Cross-referenced against individual state SOS websites.
>
> Format: `STATE_CODE | ANNUAL_FEE_CENTS | NOTES`
> - Fees in US cents (e.g., 5000 = $50.00)
> - For biennial states, the ANNUAL_FEE_CENTS is the biennial fee divided by 2
> - For states with no annual report, fee is 0
```
AL | 5000 | $50/yr minimum Business Privilege Tax; actual tax is based on net worth (min $50, max $15,000)
AK | 5000 | $100 biennial report ($50/yr equivalent); due January 2 of even years
AZ | 0 | No annual report fee and no report required for LLCs
AR | 15000 | $150/yr franchise tax report; due May 1
CA | 82000 | $800/yr franchise tax + $20 biennial Statement of Information ($10/yr equiv) = $820/yr total; franchise tax due April 15, SOI due every 2 years
CO | 2500 | $25/yr periodic report; due within 5-month window around anniversary month
CT | 8000 | $80/yr annual report; due March 31
DC | 15000 | $300 biennial report ($150/yr equivalent); due April 1
DE | 30000 | $300/yr annual franchise tax; due June 1
FL | 13875 | $138.75/yr annual report; due May 1
GA | 6000 | $60/yr annual registration fee; due April 1 (called "Annual Registration" not "Annual Report")
HI | 1500 | $15/yr annual report; due during quarter of anniversary date
ID | 0 | $0 annual report (must file information report but no fee); due anniversary month
IL | 7500 | $75/yr annual report; due anniversary month
IN | 1500 | $30 biennial report ($15/yr equivalent); due anniversary month of even/odd year based on formation
IA | 1500 | $30 biennial report ($15/yr equivalent); due April 1 of odd years
KS | 5000 | $50/yr annual report; due April 15
KY | 1500 | $15/yr annual report; due June 30
LA | 3500 | $35/yr annual report; due anniversary month
ME | 8500 | $85/yr annual report; due June 1
MD | 30000 | $300/yr personal property tax return (functions as annual report); due April 15
MA | 50000 | $500/yr annual report; due anniversary month
MI | 2500 | $25/yr annual report; due February 15
MN | 0 | $0 annual renewal (must file information report but no fee); due December 31
MS | 0 | $0 annual report (must file but no fee); due April 15
MO | 0 | No annual report fee and no report required for LLCs
MT | 2000 | $20/yr annual report; due April 15
NE | 650 | $13 biennial report ($6.50/yr equivalent); due April 1 of odd years
NV | 35000 | $350/yr total ($150 Annual List of Members + $200 State Business License); due anniversary month
NH | 10000 | $100/yr annual report; due April 1
NJ | 7500 | $75/yr annual report; due anniversary month
NM | 0 | No annual report fee and no report required for LLCs
NY | 450 | $9 biennial statement ($4.50/yr equivalent); due anniversary month
NC | 20000 | $200/yr annual report; due April 15
ND | 5000 | $50/yr annual report; due November 15
OH | 0 | No annual report fee and no report required for LLCs
OK | 2500 | $25/yr annual certificate; due anniversary month
OR | 10000 | $100/yr annual report; due anniversary month
PA | 700 | $7/yr annual report; due September 30 (new requirement starting 2025)
RI | 5000 | $50/yr annual report; due between February 1 and May 1
SC | 0 | No annual report for standard LLCs; only required if LLC elects S-Corp tax status
SD | 5500 | $55/yr annual report; due anniversary month
TN | 30000 | $300/yr minimum annual report; fee is $300 per member (min $300, max $3,000)
TX | 0 | $0 for most LLCs (must file Public Information Report but no tax if revenue < $2.47M); franchise tax due May 15
UT | 1800 | $18/yr annual report (called "Annual Renewal"); due anniversary month
VT | 4500 | $45/yr annual report; due March 15
VA | 5000 | $50/yr annual registration fee; due anniversary month
WA | 6000 | $60/yr annual report; due anniversary month
WV | 2500 | $25/yr annual report; due July 1
WI | 2500 | $25/yr annual report; due anniversary quarter
WY | 6000 | $60/yr minimum annual report; fee is based on assets in WY ($60 for assets < $300k)
```
## Summary Statistics
| Metric | Value |
|--------|-------|
| States with $0 annual fee | 9 (AZ, ID, MN, MS, MO, NM, OH, SC, TX) |
| States with biennial (not annual) reports | 6 (AK, DC, IA, IN, NE, NY) |
| Cheapest annual fee (non-zero) | NY at $4.50/yr equivalent ($9 biennial) |
| Most expensive | CA at $820/yr ($800 franchise tax + $20 SOI) |
| Average annual fee (all 51) | ~$91 |
| Median annual fee (all 51) | ~$25 |
## States with Variable/Minimum Fees
- **AL**: $50 minimum, scales with net worth up to $15,000
- **CA**: $800 minimum franchise tax; additional fee-based tax if gross revenue > $250k
- **NV**: $350 is the combined Annual List ($150) + Business License ($200)
- **TN**: $300 per member, minimum $300, maximum $3,000
- **WY**: $60 minimum; scales based on assets located in Wyoming
## Notes for PW Pricing
Our Annual Reports service is priced at **$99/yr per state**. The actual state fees listed
above are pass-through costs charged on top of our service fee. For the 9 states with $0
state fee, the client only pays our $99 service fee.

48
docs/anytime-mailbox-manual-runbook.md Normal file
View file

@ -0,0 +1,48 @@
## Anytime Mailbox Manual Signup Runbook
Provider confirmation: Anytime Mailbox does not currently offer a bulk API. Each client mailbox must be created as a separate manual application.
### Recommended operating policy
1. Use the client's real name, phone, and service address details during signup.
2. Use a temporary operations email controlled by us only for initial provisioning if the client is not yet available for OTP.
3. Complete payment with company card.
4. After mailbox activation and verification checklist is complete, rotate login email/password to the client and record transfer in ERPNext notes.
### Manual flow (per mailbox)
1. Go to `https://www.anytimemailbox.com` and select location.
2. Select service plan and review inclusions with customer.
3. Pick mailbox number, enter legal name exactly as ID.
4. Enter customer home address, contact details, and password.
5. Complete 6-digit email OTP verification.
6. Review plan and fees.
7. Enter payment card and complete recurring subscription checkout.
8. Log in and complete verification workflow immediately.
### Required controls
- Record mailbox center, plan tier, recurring price, and renewal date in ERPNext.
- Confirm customer consent preference for SMS/calls is explicit (optional toggle in form).
- Add a handoff checklist item before delivery: credentials transferred, recovery email/phone updated, and customer can log in.
### Playwright-assisted mode
The BC adapter now automates location/plan/account steps with Playwright and pauses at OTP unless an OTP value is provided.
- `ANYTIME_MAILBOX_SIGNUP_EMAIL` - mailbox signup email (optional; fallback uses `mailbox+{order_id}@performancewest.net`)
- `ANYTIME_MAILBOX_SIGNUP_PHONE` - contact phone for signup form (optional)
- `ANYTIME_MAILBOX_DEFAULT_PASSWORD` - deterministic password for provisioning (optional)
- `ANYTIME_MAILBOX_OTP_CODE` - six-digit OTP sent by Anytime Mailbox (required to complete non-interactively)
OTP can now be fetched automatically from your Carbonio/IMAP inbox if these are set:
- `ANYTIME_MAILBOX_IMAP_HOST` - IMAP host (example: `mail.performancewest.net`)
- `ANYTIME_MAILBOX_IMAP_PORT` - IMAP port (default `993`)
- `ANYTIME_MAILBOX_IMAP_SSL` - `true`/`false` (default `true`)
- `ANYTIME_MAILBOX_IMAP_USER` - inbox username used for Anytime signup emails
- `ANYTIME_MAILBOX_IMAP_PASS` - inbox password
- `ANYTIME_MAILBOX_IMAP_FOLDER` - mailbox folder (default `INBOX`)
- `ANYTIME_MAILBOX_OTP_SENDER_HINT` - sender filter hint (default `anytimemailbox`)
- `ANYTIME_MAILBOX_OTP_TIMEOUT_SECONDS` - max wait for OTP (default `180`)
- `ANYTIME_MAILBOX_OTP_POLL_SECONDS` - poll interval (default `6`)

378
docs/architecture.md Normal file
View file

@ -0,0 +1,378 @@
# System Architecture
**Last updated:** 2026-04-17 (15 Docker containers + k3s SHKeeper pods + Windows DocServer VM + dev stack + crypto treasury + foreign qualification + compliance check tool)
## Overview
Performance West runs as a multi-service stack on a Debian 13 VM (207.174.124.71):
- **Astro static site** — marketing pages, service descriptions, CRTC order form, crypto payment page
- **Express API** — order creation, Stripe/PayPal/SHKeeper checkout, identity verification, webhook receiver, portal setup API
- **ERPNext** — CRM, orders, invoicing, ticketing, customer portal (v15 + MariaDB, custom image with 4 Frappe apps). Portal at `portal.performancewest.net`
- **Listmonk** — email marketing at `lists.performancewest.net` (Go binary, PostgreSQL-backed). 22 campaigns across 4 lists. Bounce processing via POP3 from Carbonio.
- **MinIO** — S3-compatible document storage (formation docs, compliance reports, binder PDFs)
- **Ollama** — local LLM for document generation and email drafting (qwen2.5:7b)
- **Workers** — Python automation: Anytime Mailbox signup (Playwright + IMAP OTP), BC incorporation, Flowroute DID provisioning, document generation, AMB location scraping, payment reminders, GCKey provisioning (Playwright), compliance calendar renewal lifecycle, client email processing
- **SHKeeper** — self-hosted crypto payment processor via k3s (BTC, LTC, DOGE, ETH, BNB, MATIC, TRX). TRX uses nginx proxy at :5555 → TronGrid with API key injection. ETH uses proxy at :5556 → publicnode.
- **Crypto Treasury** — post-payment pipeline: SHKeeper → Bridge (Stripe) offramp → RelayFi bank → Relay debit card → vendor payments. Manual mode until Bridge approval.
- **Umami** — self-hosted web analytics at `analytics.performancewest.net`
- **PostgreSQL** — API state, orders, identity verifications, AMB locations, sessions, jurisdictions, foreign qualifications, crypto ledger (api-postgres; also hosts Listmonk DB). 67 migrations applied.
- **Dev stack** — separate environment at `dev.performancewest.net` / `api.dev.performancewest.net` (port 4323/3002, own PG on 5433). Systemd unit: `performancewest-dev.service`.
## Payment Gateway Architecture
**Active gateways:** Stripe (card/ACH/Klarna), PayPal Direct (Orders API v2), SHKeeper (crypto).
| Gateway | Status | Methods | Surcharge |
|---------|--------|---------|-----------|
| Stripe | **Active** | Card (+3%), ACH (0%), Klarna (+6%) | Via Stripe Checkout Sessions |
| PayPal | **Active** | PayPal Direct (+3%) | Orders API v2 with capture/tracking/refund |
| SHKeeper | **Active** | Crypto (0%) — BTC/LTC/DOGE + EVM chains | Branded `/order/crypto-pay` page with coin selector |
| Adyen | Future | Card/ACH/Klarna/CashApp/AmazonPay (frappe_adyen installed, not configured) |
**Payment card routing for vendor expenses:**
| Customer paid with | Filing card | ERPNext SID | Funds timing |
|---|---|---|---|
| Card/ACH/Klarna | Stripe Issuing virtual card | SID-0002 | T+2 card, T+4 ACH |
| PayPal | PayPal Mastercard | SID-0001 | Instant |
| Crypto | crypto-filing-card | crypto-filing-card | Manual |
**Fund availability detection:** Stripe `balance.available` webhook checks settlement timing (T+2 card/Klarna, T+4 ACH). PayPal is instant. Crypto is manual. When funds clear: Stripe Issuing topup → advance to "Client Selection" → email client portal setup link.
ERPNext custom Frappe apps (baked into `performancewest-erpnext:latest`):
| App | Purpose |
|-----|---------|
| `frappe_crypto` | SHKeeper crypto gateway |
| `frappe_adyen` | Adyen gateway (future) |
| `frappe_ca_registry` | BC Corporate Online incorporation automation |
| `performancewest_erpnext` | Surcharge hooks, identity gate, custom DocTypes |
## Service Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Proxmox Host │
│ │
│ ┌── Linux VM (Debian 13) — 207.174.124.71 ───────────────┐ │
│ │ │ │
│ │ Docker Compose (15 containers) │ │
│ │ ├── site (Astro → nginx:alpine) :4322 │ │
│ │ ├── api (Express/TypeScript) :3001 │ │
│ │ ├── api-postgres (app data) :5432 │ │
│ │ ├── erpnext (custom image + 4 apps) :8080 │ │
│ │ ├── erpnext-worker-default │ │
│ │ ├── erpnext-worker-short │ │
│ │ ├── erpnext-scheduler │ │
│ │ ├── erpnext-mariadb :3306 │ │
│ │ ├── erpnext-redis :6379 │ │
│ │ ├── listmonk (email marketing) :9100 │ │
│ │ ├── minio (document storage) :9000/:9001 │ │
│ │ ├── workers (Python automation) :8090 │ │
│ │ ├── ollama (local LLM) :11434 │ │
│ │ ├── umami (analytics) :3100 │ │
│ │ └── umami-postgres │ │
│ │ │ │
│ │ Dev Stack (docker compose at /opt/performancewest-dev) │ │
│ │ ├── dev-site (Astro → nginx:alpine) :4323 │ │
│ │ ├── dev-api (Express/TypeScript) :3002 │ │
│ │ ├── dev-api-postgres :5433 │ │
│ │ └── dev-workers (Python automation) │ │
│ │ │ │
│ │ k3s / Kubernetes (SHKeeper crypto payments) │ │
│ │ ├── shkeeper-deployment (Flask API) NodePort :30723 │ │
│ │ ├── bitcoin-shkeeper (3 containers) │ │
│ │ ├── ethereum-shkeeper (3 containers) via :5556 proxy │ │
│ │ ├── polygon-shkeeper (3 containers) │ │
│ │ ├── bnb-shkeeper (3 containers) │ │
│ │ ├── tron-shkeeper (3 containers) via :5555 proxy │ │
│ │ ├── litecoin-shkeeper (3 containers) │ │
│ │ ├── dogecoin-shkeeper (3 containers) │ │
│ │ └── mariadb (SHKeeper database) │ │
│ │ │ │
│ │ nginx RPC Proxies (inject API keys, strip basic auth) │ │
│ │ ├── :5555 → api.trongrid.io + TRON-PRO-API-KEY │ │
│ │ └── :5556 → ethereum-rpc.publicnode.com │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ ┌── Windows VM (DocServer) — 108.181.102.34 ─────────────┐ │
│ │ SSH: port 22422 (key auth) │ │
│ │ Office 365 Word (COM automation) │ │
│ │ Python 3.13 + pywin32 + minio SDK │ │
│ │ docserver_worker.py (MinIO poller, 12s interval) │ │
│ │ Task Scheduler: PW-DocserverWorker (AtLogOn) │ │
│ │ Auto-logon configured (requires RDP after cold reboot) │ │
│ │ Private network: 10.4.20.247 → MinIO via nginx │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## DNS
| Domain | Target |
|--------|--------|
| `performancewest.net` | site (:4322) |
| `api.performancewest.net` | api (:3001) |
| `crm.performancewest.net` | ERPNext (:8080) |
| `lists.performancewest.net` | Listmonk (:9100) — email marketing |
| `portal.performancewest.net` | ERPNext (:8080) — client portal |
| `analytics.performancewest.net` | Umami (:3100) |
| `pay.performancewest.net` | SHKeeper API (:5000 via k3s NodePort :30723) |
| `crypto.performancewest.net` | SHKeeper admin UI (:30723 via nginx) |
| `dev.performancewest.net` | Dev site (:4323) |
| `api.dev.performancewest.net` | Dev API (:3002) |
| `minio.performancewest.net` | MinIO S3 API (:9000) |
| `minio-console.performancewest.net` | MinIO Console (:9001) |
All A records point to `207.174.124.71`. TLS via Let's Encrypt (certbot, 8 certs). Mail records unchanged (HestiaCP at `207.174.124.15`).
**External panels:**
| Domain | Service |
|--------|---------|
| `cp.carrierone.com` | HestiaCP — DNS, .ca domain/email provisioning |
## Data Flow
```
Browser
│
├── performancewest.net ──────> nginx ──> site (static pages)
│
├── api.performancewest.net ──> nginx ──> Express API
│ ├── api-postgres (state fees, API keys)
│ ├── ERPNext REST API (CRM, orders, tickets)
│ ├── Listmonk API (email marketing)
│ └── Workers HTTP API (job dispatch)
│
├── crm.performancewest.net ──> nginx ──> ERPNext
│ ├── erpnext-mariadb
│ └── erpnext-redis
│
├── pay.performancewest.net ──> nginx ──> SHKeeper (k3s :5000)
│
├── lists.performancewest.net ──> nginx ──> Listmonk (:9100)
│
├── portal.performancewest.net ──> nginx ──> ERPNext (:8080)
│
├── minio.performancewest.net ──> nginx ──> MinIO S3 (:9000)
└── minio-console.performancewest.net ──> nginx ──> MinIO Console (:9001)
```
## Order Flow (ERPNext BPM)
```
Customer places order → Express API → ERPNext Sales Invoice + Payment Request
→ ERPNext payment gateway (Adyen or SHKeeper) → Customer pays
→ ERPNext webhook → Express API → Workers job server
→ Workers execute: name search → filing → EIN → doc gen
→ Documents uploaded to MinIO
→ ERPNext status → Review → Admin approves → Delivered
```
## Key Integration Points
| From | To | Method | Purpose |
|------|----|--------|---------|
| Website | Express API | HTTPS | Forms, orders, name search |
| Express API | ERPNext | REST API | CRM, orders, invoicing, tickets |
| Express API | Workers | HTTP :8090 | Job dispatch (via webhooks) |
| Express API | Listmonk | REST API | Subscriber onboarding, email campaigns |
| ERPNext | Express API | Webhooks | Workflow state change notifications |
| ERPNext | Adyen | Sessions API v71 | Card/ACH/Klarna/CashApp/AmazonPay (via frappe_adyen) |
| ERPNext | SHKeeper | REST API :5000 | Crypto payment requests (via frappe_crypto) |
| Workers | ERPNext | REST API | Status updates, workflow advances |
| Workers | MinIO | S3 API | Document upload/download |
| Workers | Ollama | HTTP :11434 | LLM doc generation, email drafting |
| Workers | DocServer | MinIO transport | DOCX-to-PDF conversion (MinIO poller: to-convert/ → converted/) |
| Workers | State portals | Playwright | Name search, entity filing |
| Workers | IRS | Playwright | EIN obtainment |
| ERPNext | Email | SMTP | Invoices, notifications, ticket replies |
| Relay debit card | State portals | Playwright | Filing fee payment |
| Workers | HestiaCP | SSH | .ca domain/email provisioning (cp.carrierone.com) |
| Workers | Flowroute | REST API | Canadian DID provisioning |
| Workers | Porkbun | REST API | .ca domain registration |
| Workers | Client mailboxes | IMAP | Monitor/process client .ca email |
| Website | Anytime Mailbox | External | Vancouver mailbox for Canadian carrier clients |
| ERPNext | Venn.ca | Referral | Canadian business banking referral |
| AI Agents | MCP Server | stdio | Service lookup, pricing, tools (npm package) |
## Worker Processes (Python)
The `workers` container runs a job server (`job_server.py` on port 8090) that dispatches jobs
to specialized worker modules. Jobs are triggered by ERPNext webhooks via the Express API.
| Worker | File | Trigger | Purpose |
|--------|------|---------|---------|
| Job Server | `job_server.py` | HTTP POST :8090 | Central dispatcher — 22 job handlers |
| CRTC Pipeline | `services/canada_crtc.py` | Webhook | 14-step CRTC carrier registration pipeline |
| GCKey Provisioner | `gckey_provisioner.py` | Called by CRTC Step 11 | Playwright-based GCKey account creation (5-step wizard, hCaptcha) |
| Renewal Worker | `renewal_worker.py` | Daily cron (7 AM) | Compliance calendar lifecycle: upcoming → due soon → invoice → paid → completed → re-calendar |
| Formation Worker | `formation_worker.py` | Webhook | US state LLC/Corp filing via Playwright |
| Binder Compiler | `binder_compiler.py` | Called by pipeline | PDF merge: certificate + articles + CRTC letter + OA |
| Document Gen | `document_gen/` | Called by pipeline | DOCX template fill → MinIO → DocServer PDF conversion |
| HestiaCP Provisioner | `hestia_provisioner.py` | Called by pipeline | .ca domain + 14 mailboxes via SSH to cp.carrierone.com |
| Client Email Processor | `client_email_processor.py` | Cron (15 min) | IMAP monitor for client .ca mailboxes |
| AMB Scraper | `amb_location_scraper.py` | Daily cron | Anytime Mailbox location pricing + sold-out detection |
| Payment Reminder | `payment_reminder.py` | Cron (5 min) | Abandoned cart recovery (15min/1d/2d intervals) |
| Commission Worker | `commission_worker.py` | Cron (daily 02:00) | Agent commission eligibility check (14-day holdback) |
| Crypto Payment Worker | `crypto_payment_worker.py` | Cron (60s) | Treasury state machine: received → sizing → offramping → funds_at_relay → settled |
| Cold Wallet Sweeper | `cold_wallet_sweeper.py` | Cron (30 min) | Sweep SHKeeper hot wallet excess to cold storage |
| Relay Deposit Monitor | `relay_deposit_monitor.py` | Cron (5 min) | IMAP parser for Relay bank deposit alerts |
| USF Factor Monitor | `usf_factor_monitor.py` | Cron (daily 09:00 CT) | Scrape USAC quarterly USF factor, email all FCC carriers |
| De Minimis Check | `deminimis_factor_check.py` | Cron (daily 03:00) | Alert if fcc_deminimis_factors missing for current/next year |
| CDR Retention Sweeper | `cdr_retention_sweeper.py` | Cron (daily 05:00) | Purge CDR data past retention window |
| CDR Unlock Nudge | `cdr_unlock_nudge.py` | Cron (daily 10:00 CT) | Email customers with locked CDR studies behind paywall |
| FCC RMD Scraper | `fcc_rmd_removed_scraper.py` | Cron (weekly Wed) | Track FCC RMD carrier removals |
| Foreign Qual Handler | `services/foreign_qualification.py` | Webhook | Multi-state Certificate of Authority filings |
| New Carrier Bundle | `services/new_carrier_bundle.py` | Webhook | 6-handler chain: CORES → DC Agent → 499 Init → RMD → CPNI → CALEA |
### CRTC Pipeline Steps (14 total)
| Step | Name | Key Actions |
|------|------|-------------|
| 1 | Order Received | Validate, create ERPNext Sales Order |
| 2 | Payment Confirmed | Create Sales Invoice + Payment Entry |
| 3 | Client Selection | Client picks mailbox unit, DID, domain |
| 4 | BC Incorporation | Playwright → BC Corporate Online |
| 5 | Domain Registration | Porkbun .ca + HestiaCP provisioning |
| 6a | CRTC Letter Generation | DOCX template → MinIO → DocServer PDF |
| 6b | eSign | Email JWT link → client signs → resume pipeline |
| 7 | CRTC Submission | Mail signed letter to Secretary General |
| 8 | Anytime Mailbox | Playwright signup + IMAP OTP |
| 9 | Binder Compilation | PDF merge of all documents |
| 10 | Delivery | Email binder + admin print/ship email |
| 11 | BITS Registration | GCKey provisioning + admin ToDo for BITS filing |
| 12 | CCTS Membership | Admin ToDo + client obligations email |
| 13 | Compliance Calendar | Create 17 compliance entries (regulatory + tax + ATS) |
| 14 | Ready for Review | Final admin review before marking Delivered |
### Compliance Calendar Renewal Lifecycle
The `renewal_worker.py` runs daily at 7 AM and manages the full lifecycle of recurring
compliance obligations for all carriers:
```
Upcoming → Due Soon (30 days out) → Invoice Sent → Paid → Completed → auto-re-calendar next year
```
- **17 entries per carrier:** BC annual report, CRTC annual maintenance, mailbox renewal,
domain renewal, DID renewal, CCTS renewal, T2 tax return, corporate tax payment,
GST/HST return, T4/T4A slips, BC PST, WorkSafeBC, CRTC registration update,
plus ATS survey forms (REP-T/T1 mandatory for all carriers)
- **Billable items** generate ERPNext Sales Invoice; entry cannot be completed until paid
- **On payment:** entry marked Completed, admin ToDo created, next-year entry auto-created
- **Webhook-triggered:** `handle_renewal_payment` in job_server for immediate processing
### DocServer (Windows VM)
MinIO-based transport — no direct HTTP connection between Linux and Windows VMs.
```
Workers: upload DOCX to minio://performancewest/to-convert/{uuid}.docx
→ DocServer polls to-convert/ bucket every 12 seconds
→ Word COM converts DOCX → PDF
→ DocServer uploads PDF to minio://performancewest/converted/{uuid}.pdf
→ Workers poll converted/ bucket for result
```
- **Heartbeat:** DocServer writes `docserver-heartbeat.json` to MinIO every 60 seconds
- **Fallback:** If heartbeat is stale (>5 min), workers auto-switch to LibreOffice headless
## Boot Sequence
All services auto-start on reboot via systemd:
| Unit | What it starts | Depends on |
|------|----------------|------------|
| `docker.service` | Docker daemon | network |
| `k3s.service` | k3s + all SHKeeper pods | docker |
| `nginx.service` | Reverse proxy + TLS + RPC proxies (:5555/:5556) | network |
| `performancewest.service` | Prod docker compose (15 containers) | docker |
| `performancewest-dev.service` | Dev docker compose (4 containers) | docker, performancewest |
All containers use `restart: unless-stopped`. k3s manages pod restarts via deployment specs. The nginx RPC proxy configs for TronGrid (:5555) and ETH (:5556) are in `/etc/nginx/conf.d/` and load automatically. UFW rules for ports 5555/5556 are persistent (allow from 10.42.0.0/16 only).
## Scheduled Workers (systemd timers)
Deployed via `infra/ansible/roles/worker-crons/`. Each timer runs `docker compose exec -T workers python -m <module>`.
| Timer | Cadence | Module |
|---|---|---|
| `pw-usf-factor-monitor` | daily 09:00 CT | `scripts.workers.usf_factor_monitor` |
| `pw-deminimis-factor-check` | daily 03:00 UTC | `scripts.workers.deminimis_factor_check` |
| `pw-cold-wallet-sweep` | every 30 min | `scripts.workers.cold_wallet_sweeper` |
| `pw-crypto-payment-worker` | every 60s | `scripts.workers.crypto_payment_worker` |
| `pw-relay-deposit-monitor` | every 5 min | `scripts.workers.relay_deposit_monitor` |
| `pw-commission-worker` | daily 02:00 UTC | `scripts.workers.commission_worker` |
| `pw-renewal-worker` | daily 04:00 UTC | `scripts.workers.renewal_worker` |
| `pw-cdr-retention` | daily 05:00 UTC | `scripts.workers.cdr_retention_sweeper` |
| `pw-cdr-unlock-nudge` | daily 10:00 CT | `scripts.workers.cdr_unlock_nudge` |
| `pw-payment-reminder` | daily 11:00 CT | `scripts.workers.payment_reminder` |
| `pw-fcc-rmd-removed` | weekly Wed 08:00 CT | `scripts.workers.fcc_rmd_removed_scraper` |
| `pw-client-email-processor` | every 15 min | `scripts.workers.client_email_processor` |
| `pw-amb-location-scraper` | daily 06:00 UTC | `scripts.workers.amb_location_scraper` |
## Database Schema (67 migrations)
Key tables added in this cycle:
| Table | Migration | Purpose |
|---|---|---|
| `jurisdictions` | 066 | Unified US states + CA provinces (55 rows) |
| `foreign_qualification_registrations` | 066 | Per-state COA filings |
| `state_compliance_obligations` | 067 | Annual report fees/dates for all 51 US jurisdictions |
| `crypto_payment_ledger` | 062 | Immutable append-only money movement ledger |
| `crypto_payment_jobs` | 065 | Treasury state machine (received → settled) |
| `vendor_obligations` | 063 | Sizer: filing fees + commission reserves |
| `cold_wallet_config` / `cold_wallet_sweeps` | 064 | Cold wallet management |
## FCC Compliance Check Tool
Public at `/tools/fcc-compliance-check`. Queries FRN against CORES, RMD, 499 Filer DB, and CPNI records. Displays:
- CORES registration status (red-light check)
- RMD filing + certification date
- STIR/SHAKEN implementation (self-reported from RMD, hidden until STI-PA API access)
- CPNI annual certification (past-due detection with correct deadline logic)
- Form 499-A annual filing (CY-year-aware)
- Form 499-Q quarterly (de minimis trade-off explanation)
- BDC broadband/voice interactive toggle (two-step questionnaire)
Remediation CTA links to `/order/fcc-compliance?services=cpni,499a,...` for bundled ordering with 15% discount.
## Compliance Service Catalog (34 handlers)
| Slug | Handler | Price |
|---|---|---|
| `new-carrier-bundle` | NewCarrierBundleHandler (6 sub-handlers) | $1,799 |
| `fcc-full-compliance` | FullComplianceHandler | $1,499 |
| `fcc-499a` | Form499AHandler | $499 |
| `fcc-499a-499q` | Form499ABundleHandler | $599 |
| `cpni-certification` | CPNIFilingHandler (9 category variants) | $149 |
| `rmd-filing` | RMDFilingHandler | $219 |
| `calea-ssi` | CALEASSIHandler (6 category variants) | $299 |
| `bdc-filing` / `bdc-broadband` / `bdc-voice` | BDCFilingHandler | $299/$199/$149 |
| `foreign-qualification-single` | ForeignQualificationHandler | $149 + state fees |
| `foreign-qualification-multi` | ForeignQualificationHandler | $99/state + fees |
| `dc-agent` | DCAgentHandler (NWRA wholesale) | $99/yr |
| `cores-frn-registration` | CORESFRNRegistrationHandler | $99 |
| `fcc-499-initial` | Form499InitialHandler | $299 |
| `ocn-registration` | OCNRegistrationHandler | $799 |
## State Formation Adapters
10 states with real adapters (name search via Playwright + portal config):
WY (237 lines), CO (177), DE (119), FL (118), TX (SOSDirect), NV (SilverFlume), UT (DCC), NM, OH, MT.
~40 remaining states have stub adapters that create admin todos for manual filing.
JurisdictionConfig abstraction at `scripts/formation/jurisdictions/` reads from the `jurisdictions` DB table (migration 066) and provides per-state fees, portal URLs, NWRA addresses, and entity type catalogs.
## Deployment
**Production:** `ansible-playbook infra/ansible/playbooks/deploy.yml -i infra/ansible/inventory/hosts.yml`
**Dev:** `bash scripts/deploy-dev.sh` — rsyncs source files + rebuilds Docker containers. Static pages (tools, services, homepage) are in `site/public/` and survive Astro rebuilds.
**nginx cache policy:** `_astro/` = immutable (1 year). HTML = no-cache. Images = 30 days.
- **Atomic uploads:** `.tmp_` prefix + `copy_object` rename prevents partial reads

231
docs/architecture.svg Normal file
View file

@ -0,0 +1,231 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 680" font-family="system-ui, -apple-system, sans-serif" font-size="11">
<defs>
<marker id="arrow" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
<path d="M0,0 L8,3 L0,6 Z" fill="#64748b"/>
</marker>
</defs>
<rect width="1200" height="680" fill="#f8fafc" rx="8"/>
<text x="600" y="28" text-anchor="middle" font-size="16" font-weight="700" fill="#1a2744">Performance West Inc. -- System Architecture</text>
<text x="600" y="44" text-anchor="middle" font-size="10" fill="#64748b">207.174.124.71 | Debian 13 | 62GB RAM | 8 vCPU | Updated 2026-04-17</text>
<!-- Browser -->
<rect x="490" y="55" width="220" height="28" rx="6" fill="#dbeafe" stroke="#3b82f6"/>
<text x="600" y="73" text-anchor="middle" font-weight="600" fill="#1e40af">Browser / Customer</text>
<!-- nginx -->
<rect x="420" y="95" width="360" height="24" rx="4" fill="#059669" opacity="0.15" stroke="#059669"/>
<text x="600" y="111" text-anchor="middle" font-weight="600" fill="#047857">nginx (TLS, reverse proxy, RPC proxies :5555/:5556)</text>
<line x1="600" y1="83" x2="600" y2="95" stroke="#64748b" stroke-width="1.5" marker-end="url(#arrow)"/>
<!-- Docker Compose Prod -->
<rect x="15" y="130" width="380" height="340" rx="6" fill="#fff" stroke="#e2e8f0" stroke-width="1.5"/>
<text x="205" y="148" text-anchor="middle" font-weight="700" font-size="12" fill="#1a2744">Docker Compose -- Production (15 containers)</text>
<rect x="25" y="158" width="175" height="22" rx="3" fill="#eff6ff" stroke="#93c5fd"/>
<text x="112" y="173" text-anchor="middle" font-size="10" fill="#1e40af">Site (Astro) :4322</text>
<rect x="210" y="158" width="175" height="22" rx="3" fill="#fef3c7" stroke="#f59e0b"/>
<text x="297" y="173" text-anchor="middle" font-size="10" fill="#92400e">Express API :3001</text>
<rect x="25" y="186" width="115" height="20" rx="3" fill="#f0fdf4" stroke="#86efac"/>
<text x="82" y="200" text-anchor="middle" font-size="9" fill="#166534">api-postgres</text>
<rect x="148" y="186" width="100" height="20" rx="3" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="198" y="200" text-anchor="middle" font-size="9" fill="#9d174d">ERPNext :8080</text>
<rect x="256" y="186" width="130" height="20" rx="3" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="321" y="200" text-anchor="middle" font-size="9" fill="#9d174d">ERP workers+sched</text>
<rect x="25" y="214" width="360" height="44" rx="4" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="205" y="230" text-anchor="middle" font-weight="600" font-size="10" fill="#5b21b6">Python Workers :8090 -- 34 service handlers</text>
<text x="205" y="244" text-anchor="middle" font-size="8" fill="#7c3aed">FCC (499-A, CPNI, RMD, CALEA, BDC, STIR/SHAKEN) | Formation | CRTC | Treasury | Renewal | CDR | ICC</text>
<text x="205" y="254" text-anchor="middle" font-size="8" fill="#7c3aed">13 systemd timers | New Carrier Bundle (6-handler chain) | Foreign Qualification</text>
<rect x="25" y="264" width="85" height="18" rx="3" fill="#ecfdf5" stroke="#6ee7b7"/>
<text x="67" y="277" text-anchor="middle" font-size="9" fill="#065f46">MinIO</text>
<rect x="116" y="264" width="85" height="18" rx="3" fill="#fef9c3" stroke="#fde047"/>
<text x="158" y="277" text-anchor="middle" font-size="9" fill="#854d0e">Ollama LLM</text>
<rect x="207" y="264" width="85" height="18" rx="3" fill="#e0f2fe" stroke="#7dd3fc"/>
<text x="249" y="277" text-anchor="middle" font-size="9" fill="#0c4a6e">Listmonk</text>
<rect x="298" y="264" width="85" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="340" y="277" text-anchor="middle" font-size="9" fill="#475569">Umami</text>
<!-- Crypto Treasury -->
<rect x="25" y="290" width="360" height="36" rx="4" fill="#fefce8" stroke="#facc15"/>
<text x="205" y="306" text-anchor="middle" font-weight="600" font-size="10" fill="#854d0e">Crypto Treasury Pipeline</text>
<text x="205" y="318" text-anchor="middle" font-size="8" fill="#a16207">SHKeeper -> Bridge (Stripe) -> RelayFi -> Relay Card -> Vendors | Cold wallet sweep | FIFO cost basis</text>
<!-- Compliance Check -->
<rect x="25" y="332" width="175" height="36" rx="4" fill="#eff6ff" stroke="#3b82f6"/>
<text x="112" y="348" text-anchor="middle" font-weight="600" font-size="9" fill="#1e40af">FCC Compliance Check</text>
<text x="112" y="360" text-anchor="middle" font-size="8" fill="#2563eb">CORES|RMD|CPNI|499|BDC</text>
<!-- Formation -->
<rect x="208" y="332" width="175" height="36" rx="4" fill="#f0fdf4" stroke="#4ade80"/>
<text x="295" y="348" text-anchor="middle" font-weight="600" font-size="9" fill="#166534">Formation + Foreign Qual</text>
<text x="295" y="360" text-anchor="middle" font-size="8" fill="#166534">51 jurisdictions | 10 adapters</text>
<!-- New Carrier + DC Agent -->
<rect x="25" y="374" width="175" height="30" rx="4" fill="#fef3c7" stroke="#f59e0b"/>
<text x="112" y="390" text-anchor="middle" font-size="9" font-weight="600" fill="#92400e">New Carrier $1,799</text>
<text x="112" y="400" text-anchor="middle" font-size="7" fill="#92400e">CORES->DC->499->RMD->CPNI->CALEA</text>
<rect x="208" y="374" width="175" height="30" rx="4" fill="#fed7aa" stroke="#f97316"/>
<text x="295" y="390" text-anchor="middle" font-size="9" font-weight="600" fill="#9a3412">CRTC Package $3,899</text>
<text x="295" y="400" text-anchor="middle" font-size="7" fill="#9a3412">Incorp+BITS+CCTS+DID+domain+binder</text>
<!-- Compliance batch -->
<rect x="25" y="412" width="360" height="24" rx="4" fill="#dbeafe" stroke="#60a5fa"/>
<text x="205" y="428" text-anchor="middle" font-size="9" fill="#1d4ed8">Batch Compliance Orders | 15% bundle discount | 5 payment methods</text>
<rect x="25" y="442" width="360" height="20" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="205" y="456" text-anchor="middle" font-size="9" fill="#475569">67 migrations | MariaDB | Redis | umami-postgres</text>
<!-- k3s -->
<rect x="410" y="130" width="350" height="140" rx="6" fill="#fff" stroke="#e2e8f0" stroke-width="1.5"/>
<text x="585" y="148" text-anchor="middle" font-weight="700" font-size="12" fill="#1a2744">k3s -- SHKeeper (7 coin daemons)</text>
<rect x="420" y="158" width="150" height="20" rx="3" fill="#fed7aa" stroke="#f97316"/>
<text x="495" y="172" text-anchor="middle" font-size="9" fill="#9a3412">SHKeeper API :30723</text>
<rect x="580" y="158" width="170" height="20" rx="3" fill="#f0f9ff" stroke="#38bdf8"/>
<text x="665" y="172" text-anchor="middle" font-size="9" fill="#0369a1">RPC Proxies :5555/:5556</text>
<rect x="420" y="184" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="447" y="196" text-anchor="middle" font-size="8" fill="#c2410c">BTC</text>
<rect x="480" y="184" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="507" y="196" text-anchor="middle" font-size="8" fill="#c2410c">ETH</text>
<rect x="540" y="184" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="567" y="196" text-anchor="middle" font-size="8" fill="#c2410c">TRX</text>
<rect x="600" y="184" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="627" y="196" text-anchor="middle" font-size="8" fill="#c2410c">BNB</text>
<rect x="660" y="184" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="687" y="196" text-anchor="middle" font-size="8" fill="#c2410c">MATIC</text>
<rect x="420" y="204" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="447" y="216" text-anchor="middle" font-size="8" fill="#c2410c">LTC</text>
<rect x="480" y="204" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="507" y="216" text-anchor="middle" font-size="8" fill="#c2410c">DOGE</text>
<rect x="540" y="204" width="55" height="16" rx="2" fill="#fff7ed" stroke="#fdba74"/>
<text x="567" y="216" text-anchor="middle" font-size="8" fill="#c2410c">MariaDB</text>
<rect x="420" y="228" width="330" height="32" rx="3" fill="#fefce8" stroke="#facc15"/>
<text x="585" y="244" text-anchor="middle" font-size="9" fill="#854d0e">SHKeeper Webhook -> crypto_payment_jobs -> Bridge offramp -> RelayFi</text>
<text x="585" y="256" text-anchor="middle" font-size="8" fill="#a16207">Manual mode (TREASURY_MODE=manual) until Bridge approval</text>
<!-- Dev Stack -->
<rect x="410" y="280" width="350" height="56" rx="6" fill="#fff" stroke="#e2e8f0" stroke-width="1.5"/>
<text x="585" y="298" text-anchor="middle" font-weight="700" font-size="11" fill="#1a2744">Dev Stack (performancewest-dev.service)</text>
<rect x="420" y="306" width="80" height="16" rx="2" fill="#eff6ff" stroke="#93c5fd"/>
<text x="460" y="318" text-anchor="middle" font-size="8" fill="#1e40af">site :4323</text>
<rect x="505" y="306" width="80" height="16" rx="2" fill="#fef3c7" stroke="#f59e0b"/>
<text x="545" y="318" text-anchor="middle" font-size="8" fill="#92400e">api :3002</text>
<rect x="590" y="306" width="80" height="16" rx="2" fill="#f0fdf4" stroke="#86efac"/>
<text x="630" y="318" text-anchor="middle" font-size="8" fill="#166534">postgres</text>
<rect x="675" y="306" width="80" height="16" rx="2" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="715" y="318" text-anchor="middle" font-size="8" fill="#5b21b6">workers</text>
<!-- DocServer -->
<rect x="410" y="346" width="350" height="40" rx="6" fill="#fff" stroke="#e2e8f0" stroke-width="1.5"/>
<text x="585" y="362" text-anchor="middle" font-weight="700" font-size="10" fill="#1a2744">Windows DocServer (108.181.102.34)</text>
<text x="585" y="378" text-anchor="middle" font-size="8" fill="#64748b">Word COM | MinIO poller (12s) | SSH:22422 | LibreOffice fallback</text>
<!-- External Services -->
<rect x="15" y="475" width="745" height="100" rx="6" fill="#fff" stroke="#e2e8f0" stroke-width="1.5"/>
<text x="387" y="493" text-anchor="middle" font-weight="700" font-size="12" fill="#1a2744">External Services and Portals</text>
<rect x="25" y="500" width="72" height="18" rx="3" fill="#eff6ff" stroke="#93c5fd"/>
<text x="61" y="513" text-anchor="middle" font-size="8" fill="#1e40af">Stripe</text>
<rect x="102" y="500" width="72" height="18" rx="3" fill="#eff6ff" stroke="#93c5fd"/>
<text x="138" y="513" text-anchor="middle" font-size="8" fill="#1e40af">PayPal</text>
<rect x="179" y="500" width="72" height="18" rx="3" fill="#ecfdf5" stroke="#6ee7b7"/>
<text x="215" y="513" text-anchor="middle" font-size="8" fill="#065f46">RelayFi</text>
<rect x="256" y="500" width="72" height="18" rx="3" fill="#fefce8" stroke="#facc15"/>
<text x="292" y="513" text-anchor="middle" font-size="8" fill="#854d0e">Bridge</text>
<rect x="333" y="500" width="72" height="18" rx="3" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="369" y="513" text-anchor="middle" font-size="8" fill="#5b21b6">USAC</text>
<rect x="410" y="500" width="72" height="18" rx="3" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="446" y="513" text-anchor="middle" font-size="8" fill="#5b21b6">FCC ECFS</text>
<rect x="487" y="500" width="72" height="18" rx="3" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="523" y="513" text-anchor="middle" font-size="8" fill="#5b21b6">FCC CORES</text>
<rect x="564" y="500" width="72" height="18" rx="3" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="600" y="513" text-anchor="middle" font-size="8" fill="#5b21b6">FCC RMD</text>
<rect x="641" y="500" width="72" height="18" rx="3" fill="#fee2e2" stroke="#fca5a5"/>
<text x="677" y="513" text-anchor="middle" font-size="8" fill="#991b1b">State SOS</text>
<rect x="25" y="524" width="72" height="18" rx="3" fill="#fee2e2" stroke="#fca5a5"/>
<text x="61" y="537" text-anchor="middle" font-size="8" fill="#991b1b">IRS (EIN)</text>
<rect x="102" y="524" width="72" height="18" rx="3" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="138" y="537" text-anchor="middle" font-size="8" fill="#9d174d">BC COLIN</text>
<rect x="179" y="524" width="72" height="18" rx="3" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="215" y="537" text-anchor="middle" font-size="8" fill="#9d174d">Porkbun</text>
<rect x="256" y="524" width="72" height="18" rx="3" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="292" y="537" text-anchor="middle" font-size="8" fill="#9d174d">Flowroute</text>
<rect x="333" y="524" width="72" height="18" rx="3" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="369" y="537" text-anchor="middle" font-size="8" fill="#9d174d">HestiaCP</text>
<rect x="410" y="524" width="72" height="18" rx="3" fill="#fed7aa" stroke="#f97316"/>
<text x="446" y="537" text-anchor="middle" font-size="8" fill="#9a3412">NWRA (RA)</text>
<rect x="487" y="524" width="72" height="18" rx="3" fill="#fed7aa" stroke="#f97316"/>
<text x="523" y="537" text-anchor="middle" font-size="8" fill="#9a3412">Anytime MB</text>
<rect x="564" y="524" width="72" height="18" rx="3" fill="#e0f2fe" stroke="#7dd3fc"/>
<text x="600" y="537" text-anchor="middle" font-size="8" fill="#0c4a6e">SMTP2GO</text>
<rect x="641" y="524" width="72" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="677" y="537" text-anchor="middle" font-size="8" fill="#475569">TronGrid</text>
<rect x="25" y="548" width="72" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="61" y="561" text-anchor="middle" font-size="8" fill="#475569">publicnode</text>
<rect x="102" y="548" width="72" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="138" y="561" text-anchor="middle" font-size="8" fill="#475569">iConectiv</text>
<rect x="179" y="548" width="72" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="215" y="561" text-anchor="middle" font-size="8" fill="#475569">Tawk.to</text>
<rect x="256" y="548" width="72" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="292" y="561" text-anchor="middle" font-size="8" fill="#475569">Stripe ID</text>
<rect x="333" y="548" width="72" height="18" rx="3" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="369" y="561" text-anchor="middle" font-size="8" fill="#475569">CoinGecko</text>
<!-- Legend -->
<rect x="790" y="130" width="185" height="210" rx="6" fill="#fff" stroke="#e2e8f0"/>
<text x="882" y="148" text-anchor="middle" font-weight="700" font-size="11" fill="#1a2744">Legend</text>
<rect x="800" y="156" width="10" height="10" rx="2" fill="#eff6ff" stroke="#93c5fd"/>
<text x="818" y="165" font-size="9" fill="#475569">Frontend / Static</text>
<rect x="800" y="172" width="10" height="10" rx="2" fill="#fef3c7" stroke="#f59e0b"/>
<text x="818" y="181" font-size="9" fill="#475569">API / Backend</text>
<rect x="800" y="188" width="10" height="10" rx="2" fill="#f5f3ff" stroke="#a78bfa"/>
<text x="818" y="197" font-size="9" fill="#475569">Workers / Automation</text>
<rect x="800" y="204" width="10" height="10" rx="2" fill="#f0fdf4" stroke="#86efac"/>
<text x="818" y="213" font-size="9" fill="#475569">Database</text>
<rect x="800" y="220" width="10" height="10" rx="2" fill="#fed7aa" stroke="#f97316"/>
<text x="818" y="229" font-size="9" fill="#475569">Crypto / SHKeeper</text>
<rect x="800" y="236" width="10" height="10" rx="2" fill="#fce7f3" stroke="#f9a8d4"/>
<text x="818" y="245" font-size="9" fill="#475569">CRM / ERPNext</text>
<rect x="800" y="252" width="10" height="10" rx="2" fill="#fefce8" stroke="#facc15"/>
<text x="818" y="261" font-size="9" fill="#475569">Treasury / Payments</text>
<rect x="800" y="268" width="10" height="10" rx="2" fill="#e0f2fe" stroke="#7dd3fc"/>
<text x="818" y="277" font-size="9" fill="#475569">Email / Marketing</text>
<rect x="800" y="284" width="10" height="10" rx="2" fill="#fee2e2" stroke="#fca5a5"/>
<text x="818" y="293" font-size="9" fill="#475569">Government Portals</text>
<rect x="800" y="300" width="10" height="10" rx="2" fill="#f1f5f9" stroke="#cbd5e1"/>
<text x="818" y="309" font-size="9" fill="#475569">Third-party APIs</text>
<rect x="800" y="316" width="10" height="10" rx="2" fill="#dbeafe" stroke="#60a5fa"/>
<text x="818" y="325" font-size="9" fill="#475569">Batch/Ordering</text>
<!-- Stats -->
<rect x="790" y="350" width="185" height="130" rx="6" fill="#fff" stroke="#e2e8f0"/>
<text x="882" y="368" text-anchor="middle" font-weight="700" font-size="11" fill="#1a2744">System Stats</text>
<text x="800" y="385" font-size="9" fill="#475569">Containers: 19 (prod+dev)</text>
<text x="800" y="399" font-size="9" fill="#475569">k3s pods: 9 (SHKeeper)</text>
<text x="800" y="413" font-size="9" fill="#475569">Service handlers: 34</text>
<text x="800" y="427" font-size="9" fill="#475569">DB migrations: 67</text>
<text x="800" y="441" font-size="9" fill="#475569">Systemd timers: 13</text>
<text x="800" y="455" font-size="9" fill="#475569">Jurisdictions: 55 (51 US + 4 CA)</text>
<text x="800" y="469" font-size="9" fill="#475569">State adapters: 52 (10 real)</text>
<!-- Boot sequence -->
<rect x="790" y="490" width="185" height="84" rx="6" fill="#fff" stroke="#e2e8f0"/>
<text x="882" y="508" text-anchor="middle" font-weight="700" font-size="11" fill="#1a2744">Boot Sequence</text>
<text x="800" y="524" font-size="8" fill="#475569">1. docker.service (systemd)</text>
<text x="800" y="536" font-size="8" fill="#475569">2. k3s.service (SHKeeper pods)</text>
<text x="800" y="548" font-size="8" fill="#475569">3. performancewest.service (prod)</text>
<text x="800" y="560" font-size="8" fill="#475569">4. performancewest-dev.service</text>
<text x="800" y="572" font-size="8" fill="#475569">5. nginx.service (TLS + proxies)</text>
<!-- Footer -->
<text x="600" y="670" text-anchor="middle" font-size="9" fill="#94a3b8">All services auto-restart on reboot. Containers: restart=unless-stopped. k3s manages pod lifecycle. nginx configs in /etc/nginx/conf.d/ persist.</text>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 18 KiB

378
docs/billing.md Normal file
View file

@ -0,0 +1,378 @@
# Billing & Payments Architecture
**Last updated:** 2026-04-05
## Principle: ERPNext Owns All Billing
All payment processing, invoicing, and financial record-keeping flows through
ERPNext. Our Express API and website are the storefront — ERPNext is the
back office. Payment gateways are Frappe apps installed inside ERPNext.
## Payment Methods
| Method | Gateway | Provider App | Integration |
|--------|---------|--------------|-------------|
| Credit/Debit (Visa, MC, Amex) + Apple Pay + Google Pay | Adyen | `frappe_adyen` | ERPNext Payment Request → Adyen Sessions API v71 |
| ACH Direct Debit | Adyen | `frappe_adyen` | ERPNext Payment Request → Adyen ACH |
| Klarna (Pay in 4) | Adyen | `frappe_adyen` | ERPNext Payment Request → Adyen Klarna |
| Cash App Pay | Adyen | `frappe_adyen` | ERPNext Payment Request → Adyen CashApp |
| Amazon Pay | Adyen | `frappe_adyen` | ERPNext Payment Request → Adyen AmazonPay |
| Cryptocurrency (BTC/ETH/USDC/USDT/MATIC/TRX/BNB/LTC/DOGE) | SHKeeper | `frappe_crypto` | ERPNext Payment Request → SHKeeper API (k3s) |
| Stripe Identity | Stripe | Direct (API only) | Identity verification for CRTC orders — NOT used for payments |
**Note:** Adyen account approval is pending. SHKeeper is deployed and running in k3s.
## Payment Surcharges
We pass processor costs through as surcharges on select payment methods:
| Method | Customer Surcharge | Our Gateway Cost | Notes |
|--------|-------------------|-----------------|-------|
| ACH Direct Debit | 0% | $0.40 flat | Recommended — lowest cost |
| Credit/Debit Card | 3% | ~2.2% (IC++) | Visa/MC/Amex + Apple Pay + Google Pay |
| Klarna | 5% | 4.29% + $0.30 | Adyen Klarna rate |
| Cash App Pay | 3% | 2.90% + $0.30 | |
| Amazon Pay | 3% | ~2.9-3.4% | Negotiated rate |
| Cryptocurrency | 0% | $0 | Self-hosted SHKeeper — zero fees |
**Surcharge injection** is handled by `performancewest_erpnext` via a `Payment Request.before_insert` hook that reads the surcharge rate from the payment gateway and adds it to the invoice total.
**Legal notes:**
- Surcharges are prohibited in **CT, MA, and PR** — residents of these
jurisdictions are not charged surcharges.
- Surcharges apply to **service fees only**, not state filing fees.
### SHKeeper (Crypto Payments)
Self-hosted in k3s (Kubernetes) at `pay.performancewest.net`. Zero processing
fees — fully non-custodial. Supports BTC, ETH, USDC, USDT, MATIC, TRX, BNB,
LTC, DOGE, and any ERC-20/TRC-20/BEP-20 token.
Installed via Helm chart `vsys-host/shkeeper`. k3s runs with `--docker --disable=traefik`
to avoid port conflicts with host nginx.
```
Customer chooses crypto payment
→ ERPNext creates Payment Request (gateway: Crypto)
→ frappe_crypto calls SHKeeper POST /api/v1/<crypto>/payment_request
→ Customer sees wallet address + QR code on crypto_checkout page
→ SHKeeper webhook fires (must return HTTP 202, not 200)
→ frappe_crypto.api.crypto_webhook verifies X-Shkeeper-Api-Key header
→ ERPNext marks Payment Request as Paid
→ ERPNext workflow webhook → Express API → Workers
```
### Adyen (Card/ACH/Klarna/CashApp/AmazonPay)
Pending Adyen account approval. When live, 5 gateway instances will be configured:
| Instance | Payment Methods | Adyen Type |
|----------|----------------|------------|
| Card | Visa, MC, Amex, Apple Pay, Google Pay | scheme, applepay, googlepay |
| ACH | US bank account direct debit | ach |
| Klarna | Pay in 4 installments | klarna |
| CashApp | Cash App Pay | cashapp |
| AmazonPay | Amazon Pay | amazonpay |
`frappe_adyen` uses Adyen Sessions API v71 with HMAC-SHA256 webhook verification
using Adyen's field concatenation algorithm. 74 unit tests passing.
## Payment Flow
```
┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌──────────────┐
│ Website │───►│ Express │───►│ ERPNext │───►│ Adyen │
│ (Astro) │ │ API │ │ │ │ (Card/ACH/ │
│ │ │ │ │ Sales Invoice│ │ Klarna/ │
│ Customer │ │ Validate │ │ Payment Req │ │ CashApp/ │
│ fills │ │ + create │ │ │ │ AmazonPay) │
│ order │ │ in ERPNext│ │ │ ├──────────────┤
└──────────┘ └──────────┘ └──────┬───────┘ │ SHKeeper │
│ │ (Crypto) │
┌────────▼────────┐ └──────────────┘
│ Customer is │
│ redirected to │
│ payment page │
│ │
│ Adyen checkout │
│ or crypto QR │
└────────┬────────┘
│
┌────────▼────────┐
│ Gateway webhook │
│ → ERPNext marks │
│ Invoice Paid │
│ │
│ ERPNext webhook │
│ → Express API │
│ → Workers │
└─────────────────┘
```
## Invoice Types
### Formation Orders
```
Sales Invoice:
Customer: Sarah Chen
Items:
- LLC Formation (Basic): $179.00
- State Filing Fee (Wyoming): $100.00
- EIN Obtainment: $49.00
- Operating Agreement: $99.00
Discount: -$37.25 (LAUNCH25 — 25% off service fee)
Total: $360.75
Payment Gateway: Adyen-Card
Status: Paid
```
### Compliance Services
```
Sales Invoice:
Customer: Marcus Johnson
Items:
- FLSA Wage & Hour Audit (up to 50 employees): $1,499.00
Total: $1,499.00
Payment Gateway: Adyen-ACH
Status: Unpaid → Payment Request Sent
```
### Recurring Services (Subscriptions)
ERPNext Subscription DocType handles:
- Registered Agent: $99/year per state (Wyoming: $49/year)
- Annual Report Filing: $99/year per state
- Canada CRTC Annual Maintenance: $349/year
- US Formation Maintenance Bundle: $179/year (annual report + RA renewal)
- CA Formation Maintenance Bundle: $179/year (annual return + AMB/RA renewal)
Subscriptions auto-generate invoices. Payment collected via Adyen (saved payment method) or manual payment link.
### Formation Maintenance Bundles
| Bundle | Price | Includes | Savings |
|--------|-------|---------|---------|
| US Formation Maintenance | $179/yr | Annual Report filing ($99) + RA renewal ($99) | $19/yr vs separate |
| CA Formation Maintenance | $179/yr | Annual Return filing ($99) + compliance monitoring ($99). AMB mailbox renewal billed separately at cost. | N/A |
| CRTC Maintenance (existing) | $349/yr | All of CA maintenance + CRTC + CCTS + domain/email + DID | N/A |
Formation maintenance bundles are offered to Complete tier customers. Basic tier customers
can purchase individual services (Annual Report $99/yr, RA $99/yr) separately.
### Canadian Formation Pricing (Standalone — Not CRTC)
| Item | Price | Notes |
|------|-------|-------|
| Canadian Formation | C$449 | Includes: incorporation, org minutes, corporate binder, compliance calendar. AMB mailbox billed separately. |
| Government fees | Passed through | BC ~C$350, ON ~C$360 (BoC rate + 10% buffer) |
| Add-on: CRA BN | $49 | Business Number registration with CRA |
| Add-on: Named company | +gov fee | Name reservation (province-specific) |
| Free DID | Included | With formation + RA renewal (stub — not yet active) |
## Service Bundles
Customers receive **20% off** when purchasing all services in a category
(e.g., all formation add-ons, all compliance services for a given tier).
- Discount applies to **service fees only** — state filing fees and
registered agent fees included in bundles are not discounted.
- RA fees are NOT discountable in bundles, but YES with discount codes.
- Bundle discount is calculated in ERPNext via Pricing Rules and applied
automatically when all qualifying items are in the Sales Order.
## Canada CRTC Package Pricing
| Item | Price |
|------|-------|
| CRTC Telecom Registration (one-time) | $3,899 USD |
| Annual Maintenance & Compliance | $349/yr |
| Consulting (regulatory, technical) | $75/hr |
| Accounting Support | 3 hrs free included, then $75/hr |
The CRTC package is a single Sales Order in ERPNext with all line items.
Annual maintenance is handled via ERPNext Subscription (auto-renew via
Adyen saved payment method).
Payment flexibility: ~$975/mo x 4 via Klarna Pay in 4 (5% surcharge applies).
## Sales Agent Commissions
Sales agents earn commissions on referred sales:
| Detail | Value |
|--------|-------|
| Canada CRTC sale | $300 per sale |
| Formation sale | $50 per sale |
| Bundle sale | $100 per sale |
| Payment timing | 14 days after order delivery |
| Payment method | Relay ACH transfer |
| Tracking | ERPNext Commission Ledger DocType + PostgreSQL backup |
Commission workflow:
1. Customer purchases using agent's REF-XXXXX referral code
2. Client gets 5% off service fee
3. Order is fulfilled and delivered
4. 14-day holdback period begins
5. After holdback, commission becomes eligible
6. Admin approves and pays via Relay ACH
7. Commission Ledger record updated with payment details
## Refunds
Refunds flow through ERPNext's Credit Note system:
1. Admin creates a Credit Note against the original Sales Invoice
2. ERPNext processes the refund via the original gateway (Adyen automatic refund, or manual ACH via Relay)
3. Credit Note tracks: amount, reason, linked invoice, approval
4. Our `refunds` table in PostgreSQL is a backup/audit — ERPNext is the source of truth
For state filing fees specifically:
- State fee refunds require contacting the state directly (most states don't refund filing fees)
- Our service fee is always refundable if the failure was our fault
- ERPNext tracks whether state fee is recoverable separately
## Express API Changes
Our API routes no longer handle payment directly:
| Before | After |
|--------|-------|
| API collects payment info | API creates Sales Invoice + Payment Request in ERPNext |
| API charges gateway | ERPNext gateway (Adyen/SHKeeper) handles payment |
| API stores payment records | ERPNext manages invoices |
| API handles refunds | ERPNext issues Credit Notes |
The checkout flow:
1. Customer fills order on Astro site → submits to Express API
2. Express API creates ERPNext Sales Invoice + Payment Request
3. Customer is redirected to ERPNext payment page (Adyen checkout or crypto QR)
4. Payment gateway webhook → ERPNext marks as Paid
5. ERPNext workflow webhook → Express API → Workers start fulfillment
Old `providers/` directory (stripe.ts, btcpay.ts, adyen.ts) and `webhooks-stripe.ts` have been deleted.
## ERPNext Setup Status
Completed:
- [x] Install Payments app (`bench get-app payments`)
- [x] Install `frappe_crypto` (SHKeeper gateway) — v1.0.0
- [x] Install `frappe_adyen` (Adyen gateway) — v1.0.0
- [x] Install `performancewest_erpnext` (surcharge hooks, identity gate) — v1.0.0
- [x] Create 16 Item records for all services (formation, compliance, add-ons, CRTC)
- [ ] Update Subscription Plans to new pricing (RA $99/yr ($49 WY), Annual Report $99/yr, CRTC Maintenance $349/yr)
- [x] Import 7 custom DocTypes
- [x] Import 3 workflows (Formation, CRTC, Renewal)
- [x] Configure custom fields on Sales Order, Sales Invoice, Payment Request
Remaining:
- [ ] Configure Crypto Payment Settings in ERPNext UI (point to `https://pay.performancewest.net` with SHKeeper API key)
- [ ] Create Payment Gateway Account for `Crypto-Crypto`
- [ ] Configure 5 Adyen Settings instances when account is approved
- [ ] Create Payment Gateway Accounts for each Adyen instance
- [ ] Configure email templates for invoice/payment notifications
- [ ] Test end-to-end payment flows
## Subscription Management
ERPNext Subscription handles recurring billing:
| Service | Frequency | Auto-Renew |
|---------|-----------|------------|
| Registered Agent | Annual | Yes (Adyen saved payment method) |
| Annual Report Filing | Annual | Yes (Adyen saved payment method) |
| CRTC Annual Maintenance | Annual | Yes (Adyen saved payment method) |
Subscription lifecycle:
1. Customer purchases RA service during formation
2. ERPNext creates Subscription (start date = formation date)
3. 11 months later: ERPNext sends renewal reminder email
4. On anniversary: ERPNext auto-generates invoice + Payment Request
5. Adyen charges saved payment method (or customer pays via link)
6. If payment fails: ERPNext sends dunning emails
7. After grace period: service paused, customer notified
## Compliance Calendar Renewal Billing
The `renewal_worker.py` (daily cron at 7 AM) manages billing for compliance calendar entries.
This is separate from ERPNext Subscriptions — it handles the 17 per-carrier compliance
obligations that have varying due dates and amounts.
### Lifecycle
```
Upcoming → Due Soon (30 days out) → Invoice Sent → Paid → Completed → re-calendar next year
```
1. **Upcoming:** Entry exists with future due date
2. **Due Soon:** 30 days before deadline — renewal worker sends reminder email
3. **Invoice Sent:** Worker creates ERPNext Sales Invoice for billable items
4. **Paid:** ERPNext webhook fires on invoice payment → `handle_renewal_payment` job
5. **Completed:** Entry marked done, admin ToDo created for the actual filing/action
6. **Re-calendar:** New entry auto-created for next period (annual/quarterly/monthly)
### Billable vs Non-Billable Entries
| Type | Billable | Amount | ERPNext Item |
|------|----------|--------|--------------|
| CRTC Annual Maintenance | Yes | $349 USD | `CRTC-MAINT-ANNUAL` |
| Mailbox Renewal | Yes | ~$199 USD | `MAILBOX-RENEWAL` |
| BC Annual Report | Yes | ~$50 CAD | `BC-ANNUAL-REPORT` |
| Domain + Hosting Renewal | Yes | ~$25 USD | `DOMAIN-RENEWAL-CA` |
| DID Renewal | Yes | ~$10 USD | (included in CRTC maintenance) |
| CCTS Renewal | No | $0 | — |
| T2 Tax Return | No | $0 (client's accountant) | — |
| GST/HST Return | No | $0 (client's accountant) | — |
| CRTC Registration Update | No | $0 | — |
| ATS Surveys | No | $0 (we prepare, client files) | — |
### ERPNext Items Needed for Renewal Invoicing
These ERPNext Items must be created for the renewal worker to generate invoices:
| Item Code | Item Name | Rate (USD) |
|-----------|-----------|-----------|
| `CRTC-MAINT-ANNUAL` | CRTC Annual Maintenance & Compliance | $349 |
| `MAILBOX-RENEWAL` | Vancouver Mailbox Renewal (Annual) | $199 |
| `BC-ANNUAL-REPORT` | BC Annual Report Filing | $50 |
| `DOMAIN-RENEWAL-CA` | .ca Domain + Hosting + Email Renewal | $25 |
| `COMPLIANCE-OTHER` | Compliance Service (Miscellaneous) | Variable |
### Compliance Calendar DocType Fields
The Compliance Calendar ERPNext DocType includes these billing-related fields:
| Field | Type | Purpose |
|-------|------|---------|
| `amount_usd` | Currency | Billable amount in USD |
| `amount_cad` | Currency | Billable amount in CAD (for Canadian gov fees) |
| `invoice` | Link (Sales Invoice) | ERPNext invoice reference |
| `recurring` | Check | Whether entry recurs annually |
| `recurrence_period` | Select | Annual / Quarterly / Monthly |
| `renewal_of` | Link (Compliance Calendar) | Previous entry this renews |
| `compliance_type` | Select | Regulatory / Tax / Survey |
| `entity_name` | Data | Carrier/company name |
| `order_reference` | Link (Sales Order) | Original CRTC order |
| `reminder_date` | Date | When to send reminder (30 days before due) |
## Environment Variables
```
# ERPNext API (set in Express API .env)
ERPNEXT_URL=https://crm.performancewest.net
ERPNEXT_API_KEY=<key>
ERPNEXT_API_SECRET=<secret>
# SHKeeper (set in server .env)
SHKEEPER_API_KEY=<key> # NEEDS TO BE SET
SHKEEPER_URL=https://pay.performancewest.net
# Stripe Identity only (NOT for payments)
STRIPE_IDENTITY_WEBHOOK_SECRET=<secret> # NEEDS TO BE SET
# SMTP
SMTP_PASS=<password> # NEEDS TO BE SET
# Customer Portal
CUSTOMER_JWT_SECRET=<secret> # NEEDS TO BE GENERATED: openssl rand -base64 32
```
All Adyen keys are configured inside ERPNext's Adyen Settings DocType, not in the Express API `.env`.

315
docs/competitive-pricing.md Normal file
View file

@ -0,0 +1,315 @@
# Competitive Pricing Analysis — US Formation, Canadian Formation & Registered Agents
**Last updated:** 2026-04-05
**Sources:** Direct website fetches (LegalZoom, ZenBusiness, Tailor Brands, Harbor Compliance) + industry research
**Purpose:** Inform Performance West pricing strategy for US formations, Canadian formations, and registered agent services
---
## US LLC Formation — Competitor Pricing
### The "$0 + State Fees" Race
Most major competitors now offer a $0 base-tier formation. The real revenue comes from
recurring subscriptions (RA, compliance), upsells (EIN, OA, rush processing), and
auto-renewing annual plans that customers forget to cancel.
### Competitor Breakdown
#### ZenBusiness (verified from website)
| Tier | Price | Renews At | Includes |
|------|-------|-----------|----------|
| Starter | $0 + state fees | Does not renew | Articles filing, name search, 7-10 day processing, 50% off 1st yr compliance |
| Pro | $199 + state fees | $199/yr | Starter + OA template + EIN + 1-day processing + logo builder |
| Premium | $399 + state fees | $399/yr | Pro + RA + advanced compliance + business advisor consult |
**Add-ons:** EIN $99, rush processing $79, Worry-Free Compliance $199/yr, Advanced Compliance $299/yr, business document templates $99
**Key insight:** ZenBusiness's Pro at $199/yr auto-renews. Year 1 customer pays $199; year 2 they pay another $199 even if they don't need anything. The $0 Starter is a lead-gen funnel — most upsell to Pro during checkout.
#### LegalZoom (verified from website)
| Tier | Price | Includes |
|------|-------|----------|
| Basic | $0 + state fees | Articles only, name check, tax consult |
| Pro | $249 + state fees | Basic + OA + EIN + 30-day attorney access (auto-renews at $49/mo) |
| Premium | $299 + state fees | Pro + RA (1yr) + eSignatures (1yr) + Wix website + compliance alerts |
**Key insight:** LegalZoom is the premium brand but their $249 Pro tier includes a $49/mo attorney subscription that auto-renews. Many customers don't realize they're signing up for a recurring charge. Their Premium at $299 is actually reasonable given it includes RA.
#### Tailor Brands (verified from website)
| Tier | Price | Renews At | Includes |
|------|-------|-----------|----------|
| Lite | $0 + state fees | N/A | Articles, 14-day processing, business coaching |
| Essential | $199/yr + state fees | $199/yr | Lite + OA + compliance + 1-day processing |
| Elite | $249/yr + state fees | $249/yr | Essential + domain + website + branding tools |
**Key insight:** Tailor Brands is a branding/website company that added LLC formation. Their value prop is design tools, not legal expertise.
#### Northwest Registered Agent
| Tier | Price | Includes |
|------|-------|----------|
| Single tier | $39 + state fees | Articles + 1yr RA included + OA + mail forwarding |
**Key insight:** Northwest is the value leader. $39 flat, no tiers, no upsells, includes 1yr RA. They make money on RA renewals ($125/yr). Very transparent pricing — no hidden subscriptions. Popular with informed customers who've researched.
#### Bizee (formerly Incfile)
| Tier | Price | Includes |
|------|-------|----------|
| Basic | $0 + state fees | Articles + 1yr RA free |
| Pro | $199 + state fees | Basic + OA + EIN + banking resolution |
| Premium | $349 + state fees | Pro + expedited + business docs + domain |
**Key insight:** Bizee offers free 1st-year RA with every formation, even the $0 tier. Revenue comes from RA renewals ($119/yr) and upsells.
#### Swyft Filings
| Tier | Price | Includes |
|------|-------|----------|
| Basic | $0 + state fees | Articles + name check |
| Standard | $199 + state fees | Basic + EIN + OA + 1yr RA free |
| Premium | $299 + state fees | Standard + FedEx delivery + website + business license report |
#### Inc Authority
| Tier | Price | Includes |
|------|-------|----------|
| Free | $0 + state fees | Articles only |
| Starter | $199 + state fees | Free + EIN + OA |
| Executive | $399 + state fees | Starter + expedited + docs + compliance |
#### Rocket Lawyer
| Plan | Price | Notes |
|------|-------|-------|
| Members | $0 formation ($39.99/mo membership) | RA included, all legal docs included |
| Non-members | $99.99 + state fees | One-time, no membership |
**Key insight:** Subscription model. The "free" formation requires a $39.99/mo membership that most people forget to cancel. Very profitable model.
#### CorpNet
| Tier | Price | Includes |
|------|-------|----------|
| Basic | $79 + state fees | Articles + name check |
| Deluxe | $179 + state fees | Basic + EIN + OA + 1yr RA |
| Complete | $249 + state fees | Deluxe + compliance + custom docs |
---
## US Registered Agent — Competitor Pricing
| Service | First Year | Annual Renewal | Notes |
|---------|-----------|---------------|-------|
| **Northwest RA** | $125 | $125 | Included free with $39 formation. Flat, transparent. |
| **ZenBusiness** | Included in Premium | $199/yr | Not sold standalone — bundled with compliance |
| **LegalZoom** | Included in Premium | $249/yr | Also sold standalone at $249/yr |
| **Harbor Compliance** | **$99** | **$149** | Standalone RA specialist. SOC 2 certified. Entity Manager software. |
| **Bizee** | **Free** (with any formation) | $119/yr | Loss-leader first year |
| **Swyft Filings** | Free (with Standard+) | $149/yr | |
| **Inc Authority** | $99 | $99 | Cheapest ongoing |
| **CorpNet** | $149 | $149 | |
| **CSC Global** | $299 | $299 | Enterprise/corporate. 50-state coverage. |
| **CT Corporation** | $310 | $310 | Law firm focused. Oldest RA service. |
| **Cogency Global** | ~$200 | ~$200 | Mid-market corporate |
| **Registered Agents Inc.** | $99 | $99 | Budget option |
**Market range:** $99-$310/yr. Most popular price point: $125-$149/yr.
**Performance West at $99/yr** is at market floor — matching Harbor Compliance's first-year
rate and undercutting Northwest RA ($125), Swyft ($149), and CorpNet ($149). Wyoming at $49/yr
is the cheapest RA in the market.
---
## US Annual Report Filing — Competitor Pricing
| Service | Price | Notes |
|---------|-------|-------|
| ZenBusiness Worry-Free Compliance | $199/yr | Includes annual report + compliance alerts |
| ZenBusiness Advanced Compliance | $299/yr | Worry-Free + advanced monitoring |
| LegalZoom Compliance | Part of Premium ($299 formation) | Annual report reminders (not filing) |
| Harbor Compliance | $99/yr + state fees | Actual filing service |
| Northwest RA | $100/report + state fees | Per-filing basis |
| Bizee | ~$99/yr | Part of compliance package |
| Inc Authority | $99/yr | |
**Performance West at $99/yr** for annual report filing is at market rate. Our $199/yr maintenance bundle (AR + RA) is competitive with ZenBusiness's $199 Worry-Free Compliance but includes more (RA renewal).
---
## Canadian Formation — Competitor Pricing
The Canadian market is much smaller than US formation. Fewer competitors, higher prices,
less automation. Most are Ontario-focused.
### Canadian Competitor Breakdown
#### Ownr (by RBC — largest Canadian competitor)
| Service | Price | Includes |
|---------|-------|---------|
| Federal incorporation | C$499 + gov fees (~C$200) | Articles, bylaws, CRA BN, minute book, 1yr RA |
| Ontario incorporation | C$499 + gov fees (~C$360) | Same as federal but Ontario-specific |
| BC incorporation | C$499 + gov fees (~C$350) | Same |
| Alberta incorporation | C$499 + gov fees (~C$275) | Same |
| Annual renewal | C$49/yr | Maintain registered office, document storage |
**Key insight:** Ownr is owned by RBC (Royal Bank of Canada). Digital-first, self-service platform. C$499 is ~US$390 — very close to our $399 Complete tier. Their C$49/yr renewal (~US$38) is much cheaper than our $199/yr maintenance, BUT it only includes address service, not actual annual report filing.
#### Ontario Business Central
| Service | Price | Includes |
|---------|-------|---------|
| Ontario Standard | C$499 + C$360 gov fee | Articles, bylaws, resolutions, certificate |
| Ontario Premium | C$699 + C$360 gov fee | Standard + minute book + corporate seal + register setup |
| Minute book add-on | C$99 | Physical minute book binder |
| Corporate seal | C$49 | Traditional embossed seal |
**Key insight:** Traditional service. C$499 (~US$390) for a basic Ontario incorporation. No tech platform — human-processed orders.
#### OnCorp (Dye & Durham)
| Service | Price | Includes |
|---------|-------|---------|
| Ontario incorporation | C$399 + gov fees | Articles, certificate, initial return |
| Federal incorporation | C$399 + gov fees | Articles, certificate |
| Premium packages | C$599-799 + gov fees | Above + minute book + RA + compliance |
**Key insight:** Part of Dye & Durham (legal tech conglomerate). C$399 (~US$312) is the price floor for Canadian service providers.
#### Legalinc / Online incorporation services
| Service | Price Range | Notes |
|---------|-------------|-------|
| Basic Ontario | C$399-599 + gov fees | Articles + certificate |
| Premium Ontario | C$699-999 + gov fees | Articles + bylaws + minute book + RA |
| Basic BC | C$399-599 + gov fees | Similar structure |
#### Law Firms (traditional)
| Service | Price Range | Notes |
|---------|-------------|-------|
| Ontario incorporation | C$1,000-3,000 + gov fees | Includes legal advice, custom articles, shareholder agreements |
| BC incorporation | C$1,500-3,000 + gov fees | Higher due to fewer automated providers |
| Federal incorporation | C$1,500-2,500 + gov fees | Often includes multi-province registration advice |
#### DIY (Government Direct)
| Jurisdiction | Gov Fee | Portal |
|-------------|---------|--------|
| Federal (CBCA) | C$200 | Corporations Canada Online Filing Centre |
| Ontario | C$360 | Ontario Business Registry |
| BC | C$350 | BC Corporate Online |
| Alberta | C$275 | Alberta Corporate Registry |
---
## Canadian Registered Agent / Registered Office — Pricing
Canadian corporations must maintain a registered office (not the same as US "registered agent"
but functionally similar — an address where legal notices can be served).
| Service | Price | Notes |
|---------|-------|-------|
| Ownr | C$49/yr | Basic address service only |
| Ontario Business Central | C$199/yr | Full registered office |
| OnCorp | ~C$150/yr | Part of annual packages |
| Virtual office (Regus, WeWork) | C$100-300/mo | Full virtual office, overkill for RA |
| Anytime Mailbox (BC) | C$156-240/yr | Our current approach |
| Anytime Mailbox (ON) | C$96-168/yr | Toronto from C$7.99/mo |
| Law firm | C$200-500/yr | Often bundled with annual filings |
---
## Competitive Position — Performance West
### US Formation
| Tier | PW Price | Market Range | Position |
|------|----------|-------------|----------|
| Basic | **$179** | $0-$99 | **Above market.** Most competitors offer $0 basic. We don't do loss-leader pricing — our $179 includes actual human review and quality filing. |
| Complete | **$399** | $199-$399 | **At market ceiling.** Same as ZenBusiness Premium. But we include EIN + OA + RA (ZenBusiness charges $199/yr that auto-renews). |
| RA | **$99/yr** (WY: $49) | $99-$310/yr | **At market floor.** Matches Harbor Compliance first-year rate. Below Northwest ($125). Wyoming at $49 is cheapest in the market. |
| Annual Report | **$99/yr** | $99-$199/yr | **At market floor.** Good value. |
| EIN | **$49** | $70-$99 | **Below market.** ZenBusiness $99, LegalZoom included only in Pro $249. |
| Operating Agreement | **$99** | $0-$99 | **At market.** Many include in mid-tier; we include in Complete. |
| Maintenance Bundle | **$179/yr** | $199-$299/yr | **Below market.** ZenBusiness Worry-Free is $199 and doesn't include RA. Ours does at $179. |
| Free DID | **$0** (with formation + RA) | Not offered by competitors | **Unique perk.** No competitor offers a free phone number with formation. |
**Honest assessment:** Our $179 Basic is above the $0 crowd. This is intentional — we don't
use loss-leader tactics with hidden subscriptions. Customers who find us are generally
comparing against the _real_ cost of ZenBusiness ($0 + $199/yr Pro renewal + $199/yr RA =
$398 year 1, $398/yr ongoing) or LegalZoom ($249 + $49/mo attorney = $837 year 1).
Our Complete at $399 is genuinely all-inclusive with no surprise renewals beyond RA ($99/yr)
and optional maintenance ($179/yr).
### Canadian Formation
| Tier | PW Price | Market Range (CAD) | Position |
|------|----------|-------------|----------|
| Formation | **C$449** + gov fees + AMB | C$399-599 | **Competitive.** Below Ownr (C$499) before AMB. Includes minutes + binder + compliance calendar. AMB mailbox billed separately (~C$96-240/yr). |
| CRA BN | **$49** | C$0 (DIY) - C$99 | **Fair.** Ownr includes BN; we charge $49 add-on. |
| Maintenance | **$179/yr** | C$49-199/yr | **Above Ownr's C$49/yr**, but we actually file the annual return — they just hold your address. |
| Free DID | **$0** (with formation + RA) | Not offered | **Unique perk.** Free Canadian phone number with formation + ongoing RA. |
**Honest assessment:** Our C$449 is below Ownr (C$499) and includes significantly more
(AMB mailbox, organizational minutes, corporate binder, compliance calendar with automated
reminders). Ownr is RBC-backed with a big marketing budget. Our advantage: we serve
non-Canadian clients who need Canadian corps for business purposes (telecom carriers,
international trade), which Ownr doesn't specifically market to.
The $179/yr maintenance is higher than Ownr's C$49/yr but we _do the work_ (file the annual
return) vs just storing documents.
### CRTC Carrier Package
No direct competitor comparison — this is a unique product. The closest alternatives:
- Canadian telecom law firm: C$10,000-25,000+ for CRTC registration assistance
- DIY: Free (just mail a letter to CRTC) but requires Canadian corporation, registered
office, understanding of CRTC process, BITS affidavit, CCTS membership, etc.
- Our $3,899 USD package is a turnkey solution with no comparable competitor
---
## Pricing Recommendations
### Current pricing (updated 2026-04-05):
- US Basic: $179 (above $0 crowd, justified by human review and quality filing)
- US Complete: $399 (matches ZenBusiness Premium, genuinely all-inclusive)
- US RA: $99/yr (at market floor — matches Harbor Compliance first-year; Wyoming $49)
- US Annual Report: $99/yr (market rate)
- US EIN: $49 (below market — good value signal)
- US Maintenance Bundle: $179/yr (below ZenBusiness $199, and ours includes RA)
- CA Formation: C$449 (below Ownr C$499, includes more)
- CRTC: $3,899 (unique product, no competitor comparison)
- Free DID: unique perk — no competitor offers this
---
## Key Takeaways
1. **The $0 formation is a marketing gimmick.** Real cost of ZenBusiness "free" LLC:
$0 + $199/yr Pro (auto-renews) + $199/yr RA = **$398/yr ongoing**. Our $179 one-time +
$99/yr RA = **$278 total year 1, $99/yr ongoing**. We're actually cheaper long-term.
2. **Registered agent is where the money is.** Every competitor gives away formation to
lock in recurring RA fees. Our $99/yr is at market floor (Wyoming $49 is the cheapest).
3. **Canadian market is underserved.** Ownr (C$499) is the only tech-forward competitor.
Law firms charge C$1,500+. Our C$449 undercuts Ownr with better deliverables. We
dominate the "non-Canadian needing a Canadian corp" niche.
4. **Annual compliance is the second recurring stream.** ZenBusiness charges $199-299/yr
just for reminders. We charge $179/yr and actually file the reports + include RA renewal.
5. **Nobody offers CRTC carrier registration.** This is our moat. The $3,899 package has
zero direct competitors in the online formation space.
6. **Free DID is a unique differentiator.** No competitor offers a free phone number with
formation. This drives RA renewal stickiness — lose the RA, lose the free number.

335
docs/crm.md Normal file
View file

@ -0,0 +1,335 @@
# Performance West — ERPNext CRM Integration
**Last updated:** 2026-04-06
## Architecture Overview
```
Browser Astro Site Express API ERPNext
| | | |
+- Place order --------->+- POST /api/orders ----->+- Create DocType ----->|
| | | |
| | | ERPNext Webhook |
| | | | |
| | | +----+----+ |
| | | | Webhook |------->|
| | | | triggers| |
| | | | workers | |
| | | +----+----+ |
| | | | |
| | | +----+----+ |
| | | | Generate | |
| | | | Docs | |
| | | +----+----+ |
| | | | |
| | | +----+----+ |
| | | | Upload | |
| | | | to MinIO| |
| | | +----+----+ |
| | | | |
| | | Update status ---->|
| | | |
<-- email with docs -----| | |
```
**Data flow:**
1. Customer submits order on Astro site
2. Express API creates ERPNext Sales Invoice + Payment Request
3. Customer pays via Adyen or SHKeeper (payment routed through ERPNext gateways)
4. ERPNext marks invoice as Paid, webhook fires to Express API
5. Express API dispatches job to Workers HTTP server (:8090)
6. Workers generate documents (DOCX templates or LLM-written), convert to PDF
7. Documents are uploaded to MinIO
8. Worker updates ERPNext order status and attaches the MinIO URL
9. Admin reviews in ERPNext; approves or requests revision
10. Delivery worker emails documents to customer
**Key principle:** ERPNext is the single source of truth for all customer data, orders, and tickets. The Express API and Python workers read/write to ERPNext via its REST API. The API's own PostgreSQL database stores only state filing fees, API keys, session data, discount codes, payment surcharges, and commission ledger backup.
## ERPNext Setup
- **URL:** https://crm.performancewest.net
- **Admin:** `Administrator` (password in Ansible vault)
- **API keys:** Set in Express API `.env` as `ERPNEXT_API_KEY` / `ERPNEXT_API_SECRET`
- **Image:** `performancewest-erpnext:latest` (custom, extends `frappe/erpnext:version-15`)
- **6 apps installed:** frappe, erpnext, payments, frappe_crypto, frappe_adyen, performancewest_erpnext
- **Timezone:** America/Chicago
## Custom DocTypes
### Formation Order
Tracks LLC/Corp formation orders through the pipeline.
| Field | Type | Description |
|-------|------|-------------|
| customer | Link (Customer) | ERPNext Customer record |
| entity_name | Data | Desired company name |
| entity_type | Select | LLC, Corporation, Nonprofit |
| state | Data | Two-letter state code |
| members | Table (Formation Member) | Member names, ownership %, capital |
| management_type | Select | Member-managed, Manager-managed |
| registered_agent | Data | RA provider name |
| add_ons | Table (Formation Add-On) | Operating agreement, EIN, RA service |
| status | Select | See Order Flow below |
| minio_path | Data | Path to generated documents in MinIO |
| filing_number | Data | State filing confirmation number |
| order_total | Currency | Total amount charged |
### Compliance Calendar
Tracks recurring compliance deadlines per entity.
| Field | Type | Description |
|-------|------|-------------|
| customer | Link (Customer) | ERPNext Customer |
| entity_name | Data | Company name |
| state | Data | State code |
| event_type | Select | Annual Report, Franchise Tax, RA Renewal, etc. |
| due_date | Date | Next due date |
| recurrence | Select | Annual, Quarterly, Monthly |
| status | Select | Upcoming, Due Soon, Overdue, Completed |
| reminder_sent | Check | Whether reminder email was sent |
### Sensitive ID
Stores SSN/EIN with encryption. Uses ERPNext's Password field type, which encrypts values at rest.
| Field | Type | Description |
|-------|------|-------------|
| customer | Link (Customer) | ERPNext Customer |
| id_type | Select | SSN, EIN, ITIN |
| id_value | Password | Encrypted value (never exposed in API responses) |
| entity_name | Data | Associated entity (for EIN) |
### Referral Partner
Tracks affiliate/referral partners and their commissions.
| Field | Type | Description |
|-------|------|-------------|
| partner_name | Data | Partner name |
| partner_email | Data | Email |
| referral_code | Data | Unique referral code |
| commission_rate | Percent | Commission percentage |
| total_referrals | Int | Count of referred customers |
| total_paid | Currency | Total commissions paid |
### Compliance Service
Tracks compliance consulting service orders (FLSA audit, CCPA audit, etc.).
| Field | Type | Description |
|-------|------|-------------|
| customer | Link (Customer) | ERPNext Customer |
| service_type | Select | FLSA Audit, CCPA Audit, TCPA Audit, Contractor Assessment, Handbook Review, Breach Response Plan, Privacy Policy |
| status | Select | See Order Flow below |
| intake_data | JSON | Service-specific intake form data |
| minio_path | Data | Path to generated documents in MinIO |
| order_total | Currency | Total amount charged |
### Sales Agent
Tracks sales agents and their referral codes.
| Field | Type | Description |
|-------|------|-------------|
| agent_name | Data | Agent full name |
| agent_email | Data | Email |
| referral_code | Data | REF-XXXXX format code |
| commission_tier | Select | Standard, Premium |
| payout_method | Select | Relay ACH |
### Commission Ledger
Per-order commission records.
| Field | Type | Description |
|-------|------|-------------|
| agent | Link (Sales Agent) | Referring agent |
| order | Link (Sales Order) | The order |
| service_type | Select | Formation, CRTC, Bundle |
| commission_amount | Currency | Flat commission ($50/$100/$300) |
| status | Select | Pending, Eligible, Paid |
| paid_date | Date | When commission was paid |
## Custom Fields on Standard DocTypes
| DocType | Field | Type | Purpose |
|---------|-------|------|---------|
| Sales Order | custom_identity_status | Select | Identity verification status for CRTC orders |
| Sales Order | custom_order_type | Select | formation, crtc, bundle, compliance |
| Sales Order | custom_external_order_id | Data | PostgreSQL order ID |
| Sales Invoice | custom_surcharge_pct | Percent | Payment method surcharge applied |
| Sales Invoice | custom_payment_gateway | Data | Which gateway processed payment |
| Payment Request | custom_adyen_session_id | Data | Adyen session reference |
## Order Flow
All orders (Formation Order and Compliance Service) follow this status pipeline:
```
Ordered --> Queued --> Processing --> Review --> Approved --> Ready --> Delivered
```
| Status | Description |
|--------|-------------|
| **Ordered** | Customer has paid; order created in ERPNext |
| **Queued** | Payment confirmed; order queued for processing |
| **Processing** | Worker is actively generating documents or filing |
| **Review** | Documents generated; awaiting admin review |
| **Approved** | Admin approved; documents ready for delivery |
| **Ready** | All reviews passed; documents ready for delivery |
| **Delivered** | Documents emailed to customer; order complete |
**Error states:**
| Status | Description |
|--------|-------------|
| **Failed** | Worker encountered an error; needs manual intervention |
| **Revision** | Reviewer requested changes; returns to Processing |
| **Refunded** | Order cancelled and refunded |
## Document Generation Pipeline
Two paths depending on the service:
### Template-Based (Formation Orders)
Used for: Operating agreements, invoices, privacy policies.
1. Worker fetches the DOCX template from MinIO (`templates/operating-agreement.docx`)
2. `DocxBuilder` fills Jinja2 placeholders with order data from ERPNext
3. DocServer converts DOCX to PDF (or LibreOffice headless as fallback)
4. Both files uploaded to MinIO at `orders/{order_id}/`
5. ERPNext order updated with `minio_path`
### LLM-Based (Compliance Services)
Used for: FLSA audits, CCPA audits, TCPA audits, contractor assessments, handbook reviews, breach response plans.
1. Worker fetches the DOCX template from MinIO (provides structure/formatting)
2. Worker calls Ollama (qwen2.5:7b) with a service-specific prompt + intake data
3. LLM generates analysis text for each section
4. `DocxBuilder` fills template placeholders and inserts LLM-generated sections
5. DocServer converts to PDF (LibreOffice fallback)
6. Both files uploaded to MinIO
7. Order status set to **Review** (always requires human review for LLM output)
### Hybrid
Some documents use both approaches: template for structure/boilerplate, LLM for analysis sections. Example: FLSA audit uses a template for the report structure, table formatting, and disclaimer, but LLM writes the executive summary, classification analysis, and remediation plan.
## MinIO Storage Structure
```
performancewest/ # Bucket
+-- templates/ # DOCX templates (9 uploaded)
| +-- operating-agreement.docx
| +-- privacy-policy.docx
| +-- breach-response-plan.docx
| +-- flsa-audit-report.docx
| +-- contractor-assessment.docx
| +-- handbook-review.docx
| +-- ccpa-audit-report.docx
| +-- tcpa-audit-report.docx
| +-- invoice.docx
+-- orders/ # Generated documents per order
| +-- FO-2026-0001/ # Formation Order
| | +-- operating-agreement.docx
| | +-- operating-agreement.pdf
| | +-- articles-of-organization.pdf
| | +-- ein-confirmation.pdf
| +-- CS-2026-0042/ # Compliance Service
| | +-- flsa-audit-report.docx
| | +-- flsa-audit-report.pdf
| | +-- remediation-checklist.pdf
| +-- ...
+-- invoices/ # Generated invoices
| +-- INV-2026-0001.pdf
| +-- ...
+-- backups/ # Encrypted database backups
+-- erpnext-2026-03-19.sql.gpg
+-- ...
```
**Access control:** MinIO is internal only (not exposed to the internet). Documents are served to customers via pre-signed URLs generated by the Express API, valid for 1 hour.
## Listmonk Integration
Listmonk (`lists.performancewest.net`) handles email marketing campaigns. It does **not**
store customer orders or tickets — ERPNext is the CRM source of truth.
**Admin:** `admin` / `F6IHwDFeMjaDGDPR1OQcKtUA86BGfs2`
**Sync flow:**
1. When a new Customer is created in ERPNext, the Express API pushes the subscriber to Listmonk via its REST API
2. Listmonk manages email campaigns, drip sequences, and newsletter sends
3. Listmonk tracks email opens/clicks and manages subscriber lists
4. Bounce processing via POP3 from Carbonio (`co.carrierone.com`)
**Mass email:** SMTP2GO is used for Listmonk campaign sends (not Carbonio — Carbonio is for transactional email only).
**Campaigns:**
| Campaign | Trigger | Content |
|----------|---------|---------|
| Welcome drip | New customer created | 3-email series: welcome, services overview, compliance tips |
| Formation follow-up | Formation delivered | Annual report reminder, RA renewal, compliance calendar |
| CRTC follow-up | CRTC carrier delivered | Banking setup, BITS filing, ATS survey prep |
| Compliance upsell | 30 days post-formation | FLSA audit, handbook review, privacy policy offers |
| Renewal reminder | 30 days before RA renewal | Registered agent renewal notice |
**Important:** Listmonk subscribers are synced one-way from ERPNext. ERPNext remains the source of truth. If a subscriber unsubscribes in Listmonk, the `email_opted_out` flag is synced back to ERPNext via webhook.
## ERPNext Helpdesk
ERPNext's built-in Helpdesk module handles all customer support:
| Feature | ERPNext Helpdesk |
|---------|-----------------|
| Ticket creation | Via API (contact form), email, or ERPNext UI |
| Assignment | Auto-assign rules based on ticket type |
| SLA tracking | Built-in SLA configuration per priority |
| Knowledge base | ERPNext Knowledge Base module |
| Customer portal | ERPNext portal (customers can view their tickets) |
| Email integration | ERPNext Email Account (incoming/outgoing) |
This eliminates the need for a separate ticketing system. All customer data stays in one place with native linking between tickets and orders.
## Security
### Encrypted Backups
- ERPNext database is backed up daily via `bench backup`
- Backups are GPG-encrypted before upload to MinIO `backups/` prefix
- Retention: 30 daily, 12 monthly, indefinite yearly
- Restore tested monthly
### RBAC (Role-Based Access Control)
ERPNext provides granular role permissions:
| Role | Access |
|------|--------|
| **Admin** | Full access to all DocTypes |
| **Operations** | Formation Orders, Compliance Services (read/write), Customers (read) |
| **Support** | Helpdesk tickets (read/write), Customers (read) |
| **API User** | REST API access with specific DocType permissions |
| **Sales Agent** | Own referrals and commission ledger (read) |
### Audit Logging
- ERPNext Version (audit log) tracks all changes to all DocTypes
- Every create/update/delete is logged with user, timestamp, and field-level diff
- Audit logs are included in encrypted backups
- Access logs retained for 1 year
### Sensitive Data (SSN/EIN)
- Stored in ERPNext Password fields (AES-256 encrypted at rest)
- Never returned in API list responses; only accessible via explicit single-record GET with appropriate role
- Masked in the ERPNext UI (shown as `***-**-1234`)
- Workers decrypt only when needed for IRS EIN application, then discard from memory

318
docs/document-generation.md Normal file
View file

@ -0,0 +1,318 @@
# Performance West — Document Generation System
**Last updated:** 2026-03-27
## Overview
The document generation system produces professional compliance documents for customers. It supports two generation modes:
1. **Template-based** — DOCX templates with Jinja2 placeholders, filled with order data
2. **LLM-based** — Templates provide structure; Ollama generates analysis sections
All generated documents pass through a quality gate (admin review) before delivery.
## Architecture
```
┌─────────────┐
│ ERPNext │ (order data + intake forms)
└──────┬──────┘
│
┌──────┴──────┐
│ Worker │ (Python — polls for Queued orders)
└──────┬──────┘
│
┌────────────┼────────────┐
│ │
┌────────┴────────┐ ┌─────────┴─────────┐
│ Template-based │ │ LLM-based │
│ (DocxBuilder) │ │ (DocxBuilder + │
│ │ │ Ollama/LLM) │
└────────┬────────┘ └─────────┬─────────┘
│ │
└────────────┬────────────┘
│
┌──────┴──────┐
│ PDF Convert │
│ ┌─────────┐ │
│ │DocServer│ │ ← PRIMARY (Windows, MS Word COM, :5050)
│ │ :5050 │ │
│ └────┬────┘ │
│ │ fail │
│ ┌────┴────┐ │
│ │LibreOfc │ │ ← FALLBACK (headless, in Docker)
│ └─────────┘ │
└──────┬──────┘
│
┌──────┴──────┐
│ MinIO │ (upload DOCX + PDF)
└──────┬──────┘
│
┌──────┴──────┐
│ ERPNext │ (update status → Review)
└─────────────┘
```
## Template-Based Generation
### When Used
- Operating agreements (formation orders)
- Privacy policies
- Invoices
- CRTC registration letter (Canada CRTC Carrier Package)
- BC corporate binder (9 sections — cover page, incorporation certificate placeholder,
articles of incorporation, registered office, directors/officers, share structure,
CRTC registration, vendor directory, compliance calendar)
- Vendor directory PDF (Canadian telecom vendors and contacts)
- Any document where the content is deterministic (no analysis needed)
### How It Works
1. Worker fetches the `.docx` template from MinIO (`templates/{template-name}.docx`)
2. `DocxBuilder` loads the template via `python-docx`
3. Variables from the ERPNext order are substituted into Jinja2 placeholders
4. The filled document is saved as DOCX
5. LibreOffice converts DOCX to PDF
6. Both files are uploaded to MinIO
### DOCX Template Format
Templates are standard `.docx` files with Jinja2 syntax embedded in the text:
**Simple variables:**
```
This Operating Agreement of {{ entity_name }}, a limited liability company
organized under the laws of {{ state_name }}...
```
**Conditionals:**
```
{% if management_type == 'manager' %}
The Manager(s) of the Company shall be {{ managers }}.
{% else %}
All Members shall have the authority to manage the business.
{% endif %}
```
**Loops (for tables or repeated sections):**
```
{% for member in members %}
{{ member.name }} — {{ member.ownership_pct }}% ownership
{% endfor %}
```
**Section placeholders (for LLM-generated content):**
```
{{ executive_summary }}
{{ classification_analysis }}
{{ remediation_plan }}
```
### Creating a New Template
1. Run `python scripts/templates/create_templates.py` to generate the base templates, or create manually in Word/LibreOffice
2. Use `{{ variable_name }}` for all dynamic content
3. Use Times New Roman for body text, navy blue (`#2D4E78`) for headings
4. Include the Performance West header, confidentiality footer, and page numbers
5. Save as `.docx` (not `.doc`)
6. Upload to MinIO: `mc cp template.docx minio/performancewest/templates/`
### Modifying an Existing Template
1. Download from MinIO: `mc cp minio/performancewest/templates/name.docx .`
2. Edit in Word or LibreOffice — preserve all `{{ }}` placeholders
3. Test locally: `python -c "from scripts.document_gen.docx_builder import DocxBuilder; ..."`
4. Upload the updated template back to MinIO
5. Existing generated documents are not affected (they are separate files)
## LLM-Based Generation
### When Used
- FLSA/wage & hour audit reports
- CCPA/CPRA compliance audit reports
- TCPA consent audit reports
- Independent contractor classification assessments
- Employee handbook reviews
- Data breach response plans
### How It Works
1. Worker fetches the DOCX template (provides structure and formatting)
2. Worker constructs a prompt from the service-specific handler + intake data
3. Worker sends the prompt to Ollama (qwen2.5:7b running locally)
4. LLM returns analysis text for each section
5. `DocxBuilder.insert_section()` replaces section placeholders with LLM output
6. Simple variables (company name, dates) are filled via `DocxBuilder.fill()`
7. Document is converted to PDF and uploaded to MinIO
8. Status is always set to **Review** — LLM output must be human-reviewed
### Prompt Engineering Guidelines
Each compliance service has a dedicated handler in `scripts/workers/services/` that constructs the prompt. Follow these guidelines:
**Structure:**
```
You are a compliance consultant preparing a {document_type} for {company_name}.
CONTEXT:
{intake_data formatted as structured text}
INSTRUCTIONS:
- Write in a professional, objective tone
- Cite specific regulations by name and section number
- Identify concrete findings (compliant, non-compliant, needs improvement)
- Provide actionable remediation steps with deadlines
- Do not include legal advice disclaimers (the template adds these)
OUTPUT FORMAT:
Return a JSON object with the following keys:
- executive_summary: 2-3 paragraph overview
- {section_name}: detailed analysis for each section
- remediation_plan: prioritized action items
Write for a business audience. Be specific, not generic.
```
**Key rules:**
- Always request JSON output — easier to parse and insert into template sections
- Include the intake data as structured context, not raw form dumps
- Specify the exact section names that match template placeholders
- Set temperature to 0.3 for consistency; compliance documents should not be creative
- Maximum token limit: 4096 per section to prevent rambling
- If the LLM returns malformed JSON, retry once with a stricter prompt
**Model selection:**
- Default: `qwen2.5:7b` (good balance of quality and speed for 16GB VRAM)
- For complex multi-state analysis: `qwen2.5:14b` if GPU memory allows
- Configured via `OLLAMA_MODEL` environment variable
## PDF Conversion
DOCX to PDF conversion uses a two-tier approach:
### PRIMARY: Windows DocServer (Microsoft Word COM)
A Windows server runs a Flask-based DocServer at `:5050` that uses Microsoft Word via COM
automation for pixel-perfect DOCX → PDF conversion. This produces the highest-fidelity
output (exact font rendering, correct page breaks, proper table formatting).
```python
# pdf_converter.py — primary path
response = requests.post(
f"http://{DOCSERVER_HOST}:5050/convert",
files={"file": open(docx_path, "rb")},
timeout=60,
)
pdf_bytes = response.content
```
### FALLBACK: LibreOffice Headless
If DocServer is unavailable (network error, timeout, Windows server down), the converter
falls back to LibreOffice in headless mode:
```bash
libreoffice --headless --convert-to pdf --outdir /tmp document.docx
```
### Converter Logic
The `pdf_converter.py` module handles:
- **DocServer first** — POST to `:5050/convert`, 60-second timeout
- **Fallback to LibreOffice** — if DocServer returns error or times out
- Retry logic (up to 3 attempts per converter)
- Temporary file cleanup
- Error reporting to ERPNext
- Logs which converter was used for each document
LibreOffice is installed in the Python worker Docker container (`scripts/Dockerfile`).
DocServer host is configured via `DOCSERVER_HOST` environment variable (default: `192.168.1.x`).
## MinIO Upload/Download
The `minio_client.py` module provides:
```python
# Upload a generated document
upload_document(
local_path="/tmp/operating-agreement.pdf",
minio_path="orders/FO-2026-0001/operating-agreement.pdf",
content_type="application/pdf",
)
# Download a template
download_template(
template_name="operating-agreement", # downloads operating-agreement.docx
local_path="/tmp/operating-agreement.docx",
)
# Generate a pre-signed URL for customer download
url = presign_url(
minio_path="orders/FO-2026-0001/operating-agreement.pdf",
expires=3600, # 1 hour
)
```
**Bucket structure:** See `docs/crm.md` for the full MinIO directory layout.
**Security:** MinIO is not exposed externally. The Express API generates time-limited pre-signed URLs for customer downloads.
## Quality Gates
### Admin Review
Every generated document enters **Review** status before delivery:
1. Admin opens the order in ERPNext
2. Downloads the DOCX/PDF from the attached MinIO link
3. Reviews for accuracy, completeness, and professionalism
4. Actions:
- **Approve** — moves to Ready
- **Request Revision** — moves to Revision with notes; worker re-generates
- **Reject** — flags for manual document creation
### Revision Loop
When a reviewer requests changes:
1. Order status returns to **Processing**
2. Reviewer's notes are stored in the ERPNext order comments
3. Worker re-generates with adjusted prompts or manual edits
4. Document re-enters **Review**
5. Maximum 3 automated revision cycles; after that, manual creation is required
## File Reference
```
scripts/
├── document_gen/
│ ├── __init__.py
│ ├── docx_builder.py # DOCX template filling (Jinja2 + python-docx)
│ ├── llm_writer.py # Ollama prompt construction and parsing
│ ├── minio_client.py # MinIO upload/download/presign
│ └── pdf_converter.py # LibreOffice headless DOCX→PDF
├── templates/
│ ├── create_templates.py # Generates all .docx templates (run once)
│ ├── crtc-registration-letter.docx # CRTC carrier registration letter template
│ ├── bc-corporate-binder.docx # BC corporate binder (9 sections)
│ ├── vendor-directory.docx # Canadian telecom vendor directory
│ └── *.docx # Other generated template files
└── workers/
├── base_worker.py # ERPNext polling loop, status transitions
├── erpnext_client.py # ERPNext REST API client
├── delivery_worker.py # Email delivery with SMTP
├── renewal_worker.py # Subscription renewal reminders
└── services/
├── base_handler.py # Base class for service handlers
├── privacy_policy.py # Template-based: fill and convert
├── breach_response.py # LLM: breach response plan
├── flsa_audit.py # LLM: FLSA audit report
├── ccpa_audit.py # LLM: CCPA audit report
├── consent_audit.py # LLM: TCPA consent audit
├── contractor_review.py # LLM: contractor classification
├── handbook_review.py # LLM: handbook review
├── campaign_review.py # LLM: marketing campaign review
└── dnc_review.py # LLM: DNC compliance review
```

179
docs/e2e-test-plan.md Normal file
View file

@ -0,0 +1,179 @@
# CRTC Pipeline E2E Test Plan
**Created:** 2026-04-06
**Environment:** Dev stack (site=4323, api=3002, postgres=5433, shared ERPNext/MinIO)
**Scope:** Post-payment pipeline only (order already submitted and paid)
**Vendor strategy:** Test/sandbox APIs where available, mock where not
**eSign:** Inject base64 signature via API
**Test output:** Playwright screenshots at each checkpoint + console report
---
## Vendor Mock/Sandbox Strategy
| Vendor | Strategy | Details |
|--------|----------|---------|
| BC Registry (COLIN) | **Mock** — no sandbox | Patch to return fake BC# `BC1234567` |
| Flowroute DID | **Test mode** | `FLOWROUTE_TEST=true`, get test DID |
| Porkbun .ca | **Mock** — no sandbox | Patch to return `test-e2e-{uuid}.ca` |
| Anytime Mailbox | **Mock** — costs money | Patch to return fake AMB unit ID |
| HestiaCP | **Mock** — don't create real accounts | Patch to return success |
| GCKey | **Mock** — no gov accounts | Patch to return fake credentials |
| SMTP | **Capture to file** | `DRY_RUN_EMAIL=true` or Mailhog |
| MinIO | **Real** | Dev MinIO shared with prod |
| DocServer | **Real** | Windows VM (or LibreOffice fallback) |
| ERPNext | **Real** | Shared instance, test SO cleaned up after |
---
## Phases
### Phase 0: Test Harness (Opus 4.6)
Write `scripts/tests/e2e_crtc_pipeline.py`:
- Playwright + requests + psycopg2 orchestration script
- Connects to dev PG, dev API, dev workers, ERPNext
- Creates test data, runs pipeline, screenshots, verifies, cleans up
- Screenshots to `scripts/tests/screenshots/`
### Phase 1: Create Test Order (Sonnet 4.6)
- Insert PG `canada_crtc_orders` with `payment_status=paid`, `funds_available=TRUE`
- Create ERPNext SO at `"Client Selection"` state
- **Screenshot 1:** ERPNext SO detail page
### Phase 2: Steps 1-4 — Incorporation (Sonnet 4.6)
- Pre-populate mocked vendor results in PG (BC#, DID, AMB)
- Advance ERPNext SO workflow through Steps 1-4
- **Screenshot 2:** ERPNext SO with BC#/DID/AMB fields
- **Screenshot 3:** PG query results
### Phase 3: Step 5 — Domain (Sonnet 4.6)
- Pre-populate domain in PG, advance workflow to `"Domain Ready"`
- **Screenshot 4:** ERPNext SO domain fields
### Phase 4: Step 6 — CRTC Letter DOCX/PDF (Opus 4.6)
- Trigger `generate_crtc_docs` job on worker
- Verify DOCX: entity name, BC#, 5 sections, signature block
- Verify PDF: MinIO object exists, valid PDF header, >0 bytes
- Verify DocServer heartbeat (or LibreOffice fallback noted)
- **Screenshot 5:** MinIO console — PDF listing
- **Screenshot 6:** ERPNext SO — `"Awaiting eSign"` state
### Phase 5: Step 6b — eSign (Sonnet 4.6)
- Generate JWT token for test order
- Screenshot eSign portal page
- POST inject base64 signature
- Verify PG: `esign_signed_at`, ERPNext SO: `"CRTC Submitted"`
- **Screenshot 7:** eSign portal page
- **Screenshot 8:** ERPNext SO post-eSign
### Phase 6: Steps 7-10 — Binder + Delivery (Sonnet 4.6)
- Wait for `resume_crtc_pipeline` job completion
- Verify binder: MinIO object, valid PDF, multi-page
- Verify delivery email (Mailhog or file capture)
- Verify banking referral sent
- **Screenshot 9:** MinIO binder PDF
- **Screenshot 10:** Delivery email
- **Screenshot 11:** ERPNext SO `"Banking Ready"`
### Phase 7: Steps 11-13 — BITS/CCTS/Compliance (Sonnet 4.6)
- Wait for pipeline to reach `"Ready for Review"`
- Verify BITS: ToDo exists, `custom_bits_filed_at` set
- Verify CCTS: ToDo exists, `custom_ccts_filed_at` set
- Verify Compliance Calendar: 12+ entries with correct dates/amounts
- **Screenshot 12:** Compliance Calendar list
- **Screenshot 13:** ToDo list (BITS + CCTS)
- **Screenshot 14:** ERPNext SO final state
### Phase 8: Cleanup (Sonnet 4.6)
- Delete PG test rows, ERPNext SO/Calendar/ToDo, MinIO objects
- Print cleanup report
---
## Screenshot Manifest (14 screenshots)
| # | Filename | Source | Verifies |
|---|----------|--------|----------|
| 1 | `01-so-client-selection.png` | ERPNext SO | Initial post-payment state |
| 2 | `02-so-incorporation-complete.png` | ERPNext SO | BC#, DID, AMB populated |
| 3 | `03-pg-order-fields.png` | Terminal PG | Raw DB row |
| 4 | `04-so-domain-ready.png` | ERPNext SO | Domain + HestiaCP |
| 5 | `05-minio-crtc-letter.png` | MinIO console | Letter PDF exists |
| 6 | `06-so-awaiting-esign.png` | ERPNext SO | Awaiting eSign state |
| 7 | `07-esign-portal-page.png` | Browser | eSign page with preview |
| 8 | `08-so-crtc-submitted.png` | ERPNext SO | Post-eSign state |
| 9 | `09-minio-binder.png` | MinIO console | Binder PDF exists |
| 10 | `10-delivery-email.png` | Mailhog/file | Client delivery email |
| 11 | `11-so-banking-ready.png` | ERPNext SO | Banking referral sent |
| 12 | `12-compliance-calendar.png` | ERPNext list | 12+ compliance entries |
| 13 | `13-todos-bits-ccts.png` | ERPNext list | BITS + CCTS ToDos |
| 14 | `14-so-ready-for-review.png` | ERPNext SO | Final state all fields |
---
## Model Assignment
| Phase | Model | Why |
|-------|-------|-----|
| 0: Test harness | **Opus 4.6** | Complex architecture — mocks, Playwright, error handling |
| 1: Create order | Sonnet 4.6 | Mechanical DB + API calls |
| 2: Steps 1-4 | Sonnet 4.6 | Pre-populate mock data |
| 3: Step 5 | Sonnet 4.6 | Pre-populate mock data |
| 4: Step 6 DOCX/PDF | **Opus 4.6** | Critical — DOCX structure + PDF conversion verification |
| 5: eSign | Sonnet 4.6 | API inject + verify |
| 6: Steps 7-10 | Sonnet 4.6 | File + email verification |
| 7: Steps 11-13 | Sonnet 4.6 | ERPNext entry verification |
| 8: Cleanup | Sonnet 4.6 | Mechanical deletes |
**Total effort:** 8-10 hours (1-2 sessions)
---
## Test Results (2026-04-06)
### Run Summary
| Phase | Result | Time | Details |
|-------|--------|------|---------|
| 1 | PASS | <1s | PG order + ERPNext SO created + submitted + workflow advanced (Received → Mailbox Ready) |
| 2-3 | PASS | <1s | Mock BC# BC1234567, DID +16045551234, domain, AMB |
| 4 | PASS | 2s | DOCX 37.6KB (5/5 content checks), PDF 42KB (LibreOffice), uploaded to MinIO |
| 5 | PASS | 3s | eSign page screenshot captured, JWT simulated in PG |
| 6 | PASS | 10s | PDF verified in MinIO (42KB, valid header) |
| 7 | PASS | 1s | ERPNext SO at "Mailbox Ready" state, no compliance entries (expected) |
| 7b | PASS | 30s | eSign screenshot captured, ERPNext login times out (Docker network) |
| **Total** | **ALL PASS** | **48s** | |
### Binder Compilation (Separate Test)
| Test | Result | Details |
|------|--------|---------|
| DOCX generation | PASS | 37.5KB |
| LibreOffice PDF | PASS | 41.4KB |
| Binder compilation | PASS | 37.3KB, **5 pages** (cover + TOC + divider + letter content) |
### DocServer Investigation
Word COM fails under SYSTEM account and "Run whether user is logged on or not" mode.
Requires interactive desktop session (RDP login). Auto-logon configured (registry keys set)
but blocked by hosting provider's Windows Server 2019 policy.
**Workaround:** RDP into the VM once after reboot → AtLogOn trigger fires → Word COM works.
LibreOffice fallback handles conversions automatically when DocServer is unavailable.
### Known Limitations
1. **DocServer** — requires RDP login after cold reboot (auto-logon blocked by hosting provider)
2. **eSign JWT** — test uses different secret than dev API; falls back to PG simulation
3. **Compliance Calendar** — DocType not imported to ERPNext; 417 error on query
4. **ERPNext screenshots** — Playwright can't log into ERPNext from Docker (login page structure)
5. **Full pipeline** — individual components tested; full 14-step pipeline needs ERPNext workflow + all DocTypes imported

111
docs/entity-cache-sources.md Normal file
View file

@ -0,0 +1,111 @@
# Entity Cache Data Sources
Bulk business entity data for the corporation status check feature.
Updated: 2026-04-20
## Working Socrata SODA API States (free, JSON, unlimited)
| State | Dataset ID | Records | Status Field | Formation State Field | Notes |
|-------|-----------|---------|--------------|----------------------|-------|
| CO | `4ykn-tg5h` | ~3M | `entitystatus` | `jurisdictonofformation` | Fully loaded |
| IA | `ykb6-ywnd` | ~500K | `entity_status` | `home_state` | Working |
| CT | `n7gp-d28j` | ~1.2M | `status` | `state_of_formation` | Working |
| OR | `tckn-sxa6` | ~800K | `status` | `state_of_origin` | Active businesses only |
| NY | `n9v6-gdp6` | ~2M | N/A (active only) | `jurisdiction` | No status field — all records are active |
**API pattern:** `https://data.{state}.gov/resource/{id}.json?$limit=50000&$offset=0&$order=:id`
## Broken Socrata URLs (portals reorganized, need new IDs)
| State | Old ID | Notes |
|-------|--------|-------|
| WA | `7naq-cqm3` | 404. data.wa.gov catalog empty for business category |
| IL | `vqps-xatp` | 404. IL SOS prohibits bulk scraping officially |
| PA | `6ftj-q3fu` | 404. PA has `xvd7-5r2c` but no status field |
| MI | `uc6u-xab8` | 404. LARA portal, no confirmed free download |
| AK | `p2kg-xwxr` | DNS failure. data.alaska.gov may be deprecated |
| VT | `c7cm-s92n` | 404. VT open data portal reorganized |
## Free Bulk Download (non-Socrata)
| State | Source | Format | Cost | Fields | Status |
|-------|--------|--------|------|--------|--------|
| FL | Sunbiz FTP | Fixed-width ASCII | Free (register for FTP creds) | Name, status (A/I), filing type, date, EIN, address, RA, officers | Has status |
| VA | data.virginia.gov | XLSX (~86MB) | Free | Name, address, officers, status, type, creation date | Has status |
**FL download:** https://dos.fl.gov/sunbiz/other-services/data-downloads/
**VA download:** https://data.virginia.gov/dataset/corporation
## Free Subscription Downloads
| State | Source | Cost | Records | Notes |
|-------|--------|------|---------|-------|
| CA | bizfileOnline.sos.ca.gov | **FREE** (weekly subscription) | ~17M | Sign up at BizFileOnline → BE & UCC Bulk Orders → Weekly Data Download |
| FL | sftp.floridados.gov | **FREE** (SFTP) | ~4M | User: Public / Pass: PubAccess1845! — Quarterly full + daily diffs |
## Paid Bulk Data
| State | Source | Cost | Notes |
|-------|--------|------|-------|
| WY | SOS subscription form | $10K+/year | Too expensive — we scrape WyoBiz instead |
| TX | SOSDirect bulk orders | $20/month (weekly) or $1,350 one-time | https://direct.sos.state.tx.us/help/help-corp.asp?pg=bulk |
| TX | Comptroller franchise tax | **FREE** on data.texas.gov (xn8i-yb9w) | 3.2M records but SODA API returns empty — may need portal CSV export |
| MN | SOS data subscription | $30/week (free non-commercial) | CSV, delivered within 10 days |
| NE | SOS special request | $15 per 1,000 records | CSV with filters |
| AZ | Corp Commission form M027 | $75 partial / $1,000 full | Importable format |
| NC | SOS data subscription | $750 initial + $250/year | FTP weekly updates |
| LA | SOS office | $6,900–$12,500 | Too expensive |
## No Bulk Access (Playwright search only)
These states require live SOS portal searches via our Playwright adapters (~3-20s per lookup, cached 24h):
DE, IL, GA, MA, MD, NH, NJ, SC, SD, TN, KY, IN, MS, MO, WV, ND, OK, RI, HI, NM, NV (search API only), MT, NE (unless paid), AL, AR, KS, LA, ME
Our state adapters handle all 52 jurisdictions via `search_name()` for on-demand lookups.
## SEC EDGAR (public companies only)
For ~10K publicly-traded companies, SEC filings include authoritative state of incorporation:
- **Company list:** https://www.sec.gov/files/company_tickers.json
- **Detail:** https://data.sec.gov/submissions/CIK{padded_10}.json
- **Fields:** `stateOfIncorporation`, `name`, `ein`, `addresses`
- **Rate limit:** 10 req/sec, free, requires User-Agent header
- **Limitation:** Only SEC-registered filers (public companies, not private LLCs)
## Aggregator APIs
| Service | Free Tier | Coverage | Notes |
|---------|-----------|----------|-------|
| OpenCorporates | 200 calls/month | 170+ jurisdictions | Not viable for bulk. Paid plans start GBP 2,250/yr |
| Cobalt Intelligence | 20 free lookups | All 50 states | Credit-based paid API. Gold standard but expensive |
| Apify "US Business Entity Search" | Pay-per-use | 34 state registries | Uses SIP Public Data Gateway. Most comprehensive |
## Daily Cron
The `pw-entity-cache-refresh` timer runs at 07:00 UTC (2am CT) daily:
```
python -m scripts.formation.bulk_download --all
```
Downloads all configured Socrata states and upserts into `entity_cache`.
## Schema
```sql
-- entity_cache table (migration 009)
entity_name TEXT NOT NULL -- Uppercase
entity_number TEXT -- State filing number
entity_type TEXT -- LLC, CORPORATION, LP, NONPROFIT
status TEXT -- ACTIVE, DISSOLVED, SUSPENDED, DELINQUENT, INACTIVE
formation_date DATE
formation_state TEXT -- 2-letter code of state where entity was originally formed
registered_agent TEXT
principal_address TEXT
state TEXT NOT NULL -- State this record is registered in
source TEXT DEFAULT 'socrata'
UNIQUE(jurisdiction, entity_number)
INDEX gin_trgm on entity_name -- Fuzzy search
INDEX on state
INDEX on status
```

BIN
docs/examplefilings/Adaptive Communications LLC/2025-03-03 Adaptive Communications LLC 499A Initial Worksheet.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Adaptive Communications LLC/2025-03-06 Adaptive Communications LLC 499A Initial Worksheet.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Cloud One PBX LLC CPNI.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Engage Holdings, LLC dba iQventures/2024 Engage Holdings LLC CPNI.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Engage Holdings, LLC dba iQventures/Engage Communications Corporation RMD Plan.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Engage Holdings, LLC dba iQventures/Engage Communications Corporation RMD Plan.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Fortel Networks Inc CPNI.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Fortel Networks Inc/2024-12-27 FCC RMD Mailing Letter.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Fortel Networks Inc/2026-02-27 Fortel Networks RMD Plan.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Fortel Networks Inc/2026-02-27 Fortel Networks RMD Plan.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Fortel Networks Inc/FORTEL NETWORKS Revised RMD Plan.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Fortel Networks Inc/FORTEL NETWORKS Revised RMD Plan.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-05-16 SOS Receipt.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-05-16 SOS Registration.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-05-30 Franklin Technology Services LLC FRN Registration Confirmation.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-05-30 Franklin Technology Services LLC initial 499A Reg Filing.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-06-05 Franklin Technology Services LLC initial 499A Reg Filing.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-06-18 Robocall Mitigation Plan for Franklin Technology Services LLC.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/2025-06-18 Robocall Mitigation Plan for Franklin Technology Services LLC.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/520L Original.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/Carrier One Inc MSA ES 2 - FTS Signed.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/Carrier One Inc MSA ES 2 - FTS.doc Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/Carrier One Inc MSA ES 2 - FTS.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/CertOfGoodStanding.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/Franklin 520L.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/Franklin Technology Services LLC fss4.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/Inv_1804492505_from_FRANKLIN_TECHNOLOGY_SERVICES_LLC_29784.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Franklin Technology Services LLC/company-code-request-form---0923.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/SecretOrderLink LLC/2025-04-15 SecretOrderLink LLC neca-ocn-company-code-request.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/SecretOrderLink LLC/2025-06-10 colorado sos receipt.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/SecretOrderLink LLC/SecretOrderLink_LLC.zip Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Syntracom LLC/2024 Syntracom LLC CPNI.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Syntracom LLC/2026-02-26 Syntracom LLC RMD Plan.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Syntracom LLC/2026-02-26 Syntracom LLC RMD Plan.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Syntracom LLC/Syntracom LLC RMD Plan.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Syntracom LLC/Syntracom LLC RMD Plan.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/TIP Systems LLC/2024 TIP Systems LLC CPNI.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Telehood LLC/2024 revenues 499A Reporting Worksheet.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Telehood LLC/telehood 2024 revenue report from denovo switch.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/2022 VoipFlo 499A Final.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/2023 VoipFlo 499A Final.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/2024 VoipFlo 499A Final.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/2025 VoipFlo 499A Final.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/2026-02-27 VoIPFlo Inc RMD.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/2026-02-27 VoIPFlo Inc RMD.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up.zip Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/499A 2022 reporting 2021 revenue draft.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/499A 2024 reporting 2023 revenue draft.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/ATT IPFLEX.pdf Normal file
View file

Binary file not shown.

26
docs/examplefilings/Voipflo/Catch up/Annual_Telecom_Summary.csv Normal file
View file

@ -0,0 +1,26 @@
Stripe,,,,,,
Year,DID,Prepaid Usage,Stripe Total,,,
2021," $4,126 "," $6,814 "," $10,940 ",,,
2022," $2,711 "," $15,022 "," $17,732 ",,,
2023," $13,891 "," $13,420 "," $27,311 ",,,
2024," $16,798 "," $8,328 "," $25,126 ",,,
,,,,,,
,,,,,,
Wires ,,,,,,
Year, DID , Channels , Top Up , Usage , Total ,
2021," $19,047 "," $24,934 "," $24,247 "," $264,370 "," $332,596 ",
2022," $26,967 "," $44,735 "," $39,664 "," $471,477 "," $582,843 ",
2023," $38,450 "," $60,360 "," $129,500 "," $371,589 "," $599,899 ",
2024," $32,856 "," $50,510 "," $43,250 "," $76,876 "," $203,492 ",
,,,,,,
,,,,,,
Grand Total,,,,,,
Year, DID Total ,Channels, Minutes Total ,Set Up Fees, Discounts , Total
2021," $23,173 "," $24,934 "," $295,430 ",1548.99,-3201.35," $341,884 "
2022," $29,678 "," $44,735 "," $526,162 ",419.74,-3505.94," $597,489 "
2023," $52,341 "," $60,360 "," $514,508 ",4545,-3505.94," $628,249 "
2024," $49,654 "," $50,510 "," $128,454 ",167,-3201.35," $225,584 "
,,,,,,
,,,,,,
,,,,,,
,,,,,,
1 Stripe
2 Year DID Prepaid Usage Stripe Total
3 2021 $4,126 $6,814 $10,940
4 2022 $2,711 $15,022 $17,732
5 2023 $13,891 $13,420 $27,311
6 2024 $16,798 $8,328 $25,126
7
8
9 Wires
10 Year DID Channels Top Up Usage Total
11 2021 $19,047 $24,934 $24,247 $264,370 $332,596
12 2022 $26,967 $44,735 $39,664 $471,477 $582,843
13 2023 $38,450 $60,360 $129,500 $371,589 $599,899
14 2024 $32,856 $50,510 $43,250 $76,876 $203,492
15
16
17 Grand Total
18 Year DID Total Channels Minutes Total Set Up Fees Discounts Total
19 2021 $23,173 $24,934 $295,430 1548.99 -3201.35 $341,884
20 2022 $29,678 $44,735 $526,162 419.74 -3505.94 $597,489
21 2023 $52,341 $60,360 $514,508 4545 -3505.94 $628,249
22 2024 $49,654 $50,510 $128,454 167 -3201.35 $225,584
23
24
25
26

BIN
docs/examplefilings/Voipflo/Catch up/Annual_Telecom_Summary.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/Compliance_Report.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/Hyper Telecom, LLC_Sales by Product_Service Detail.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/IPFLEX ATT.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Catch up/Revenue by CDR (Mins only) by Year.xlsx Normal file
View file

Binary file not shown.

5
docs/examplefilings/Voipflo/Catch up/Section_Percentages_by_Year2.csv Normal file
View file

@ -0,0 +1,5 @@
Year,Toll Free,503,504,505,506,507,508,509
2021,22.87,50,0.53,1.6,2.13,0,1.06,21.81
2022,3.92,56.37,0.49,1.96,0.98,0,0.98,35.29
2023,4.02,61.06,4.77,4.52,2.51,1.01,2.26,19.85
2024,3.52,62.76,3.81,2.35,1.76,0.88,1.76,23.17
1 Year Toll Free 503 504 505 506 507 508 509
2 2021 22.87 50 0.53 1.6 2.13 0 1.06 21.81
3 2022 3.92 56.37 0.49 1.96 0.98 0 0.98 35.29
4 2023 4.02 61.06 4.77 4.52 2.51 1.01 2.26 19.85
5 2024 3.52 62.76 3.81 2.35 1.76 0.88 1.76 23.17

BIN
docs/examplefilings/Voipflo/Catch up/Stripe unified_payments 2021-2024.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/Compliance_Report.pdf Normal file
View file

Binary file not shown.

5
docs/examplefilings/Voipflo/NPAC Regions - Section_Percentages_by_Year.csv Normal file
View file

@ -0,0 +1,5 @@
Year,Toll Free,503,504,505,506,507,508,509
2021,22.87,50,0.53,1.6,2.13,0,1.06,21.81
2022,3.92,56.37,0.49,1.96,0.98,0,0.98,35.29
2023,4.02,61.06,4.77,4.52,2.51,1.01,2.26,19.85
2024,3.52,62.76,3.81,2.35,1.76,0.88,1.76,23.17
1 Year Toll Free 503 504 505 506 507 508 509
2 2021 22.87 50 0.53 1.6 2.13 0 1.06 21.81
3 2022 3.92 56.37 0.49 1.96 0.98 0 0.98 35.29
4 2023 4.02 61.06 4.77 4.52 2.51 1.01 2.26 19.85
5 2024 3.52 62.76 3.81 2.35 1.76 0.88 1.76 23.17

BIN
docs/examplefilings/Voipflo/Screenshot before working on usac.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 96 KiB

BIN
docs/examplefilings/Voipflo/voipflo - performance west 499a calculation worksheet.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Voipflo/voipflo work.xlsx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Zingo Media Group LLC/2024 Zingo Media Group LLC CPNI.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Zingo Media Group LLC/2025-12-02 Robocall Mitigation Plan for Zingo Media Group LLC.docx Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Zingo Media Group LLC/2025-12-02 Robocall Mitigation Plan for Zingo Media Group LLC.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/Zingo Media Group LLC/old Robocall Mitigation Plan for Zingo Media Group LLC.pdf Normal file
View file

Binary file not shown.

BIN
docs/examplefilings/voipflo CPNI.docx Normal file
View file

Binary file not shown.

3197
docs/fcc-references/2026-499A-instructions.txt Normal file
View file

File diff suppressed because it is too large Load diff

BIN
docs/fcc-references/2026-FCC-Form-499A-Form-Instructions.pdf Normal file
View file

Binary file not shown.

355
docs/foreign-incorporation-guide.md Normal file
View file

@ -0,0 +1,355 @@
# Foreign Non-Resident Incorporation Guide — Canada vs US
**Last updated:** 2026-04-05
**Purpose:** Guide for non-US/non-Canadian foreigners who want to form a business entity.
Recommendation: if they don't have SSN/ITIN, steer them toward Canadian incorporation.
---
## The Problem: US LLC Formation for Foreigners
Foreign non-residents who want a US LLC face these barriers:
| Barrier | Details |
|---------|---------|
| **EIN requires SSN or ITIN** | IRS Form SS-4 asks for the responsible party's SSN or ITIN. Without either, you must fax the form — takes 4-6 weeks, often lost. |
| **ITIN requires a tax return** | You can only apply for ITIN by filing a US tax return (Form W-7 + 1040-NR). Catch-22: you need the ITIN to get the EIN to open the bank account to earn income to file the return. |
| **US bank accounts** | Nearly impossible without SSN/ITIN. Most banks require physical branch visit + SSN. Mercury, Relay, Novo all require SSN. |
| **Stripe US** | Requires SSN or ITIN for identity verification of the responsible person. |
| **PayPal US** | Requires SSN for business accounts. |
| **State-level complications** | Some states (CA, NY) have additional requirements for foreign-owned LLCs. |
| **FATCA/CRS reporting** | Foreign-owned US LLCs trigger complex tax reporting obligations. |
**Bottom line:** A foreigner without ITIN faces 2-6 months of bureaucracy just to get an
EIN and bank account for a US LLC. Many give up.
---
## The Solution: Canadian Corporation
Canadian provincial incorporation has **none of these barriers** for foreigners:
| Factor | US LLC | Canadian Corporation |
|--------|--------|---------------------|
| Government ID number needed? | SSN or ITIN (hard to get) | **No SIN required** |
| Resident director required? | No (most states) | **No (BC, ON, AB, SK, MB, QC)** |
| Physical presence required? | No (most states) | **No — fully remote** |
| ID for incorporation | Not needed at filing | **Passport or national ID** |
| Bank account | Requires SSN/ITIN | **Fintech banks accept foreign directors** |
| Payment processing | Stripe requires SSN | **Stripe Canada accepts foreign directors** |
| Time to operational | 2-6 months (EIN + bank) | **1-2 weeks** |
| Corporate tax (small biz) | 21% federal | **11% (BC) / 12.2% (ON)** |
| Sales tax on exports | Varies by state | **0% GST/HST on exports** |
### What foreigners DON'T need for Canadian incorporation:
- No SIN (Social Insurance Number) — SIN is for employment/tax, not incorporation
- No Canadian passport or permanent residence card
- No ITIN (that's a US concept — doesn't exist in Canada)
- No physical visit to Canada
- No Canadian bank account at time of incorporation
- No Canadian co-signer or guarantor
### What foreigners DO need:
| Requirement | Details |
|-------------|---------|
| Valid government photo ID | Passport, national ID card, or driver's license |
| Residential address | Can be in their home country (for director record) |
| Registered office in the province | **We provide this** via Anytime Mailbox |
| Filing fee payment | Credit card (Visa/MC) |
| Email address | For correspondence — we provision a .ca email if CRTC |
---
## Province-by-Province Requirements for Non-Resident Foreign Directors
### Provinces WITH NO Resident Director Requirement (Foreign-Friendly)
These provinces allow 100% foreign ownership with all directors being non-residents:
#### British Columbia (BC)
| Item | Details |
|------|---------|
| Governing Act | BC Business Corporations Act (BCBCA) |
| Resident director requirement | **None** — never had one |
| Incorporation portal | BC Corporate Online (anonymous, no login) |
| Government fee | ~C$350 |
| Annual return | C$42.71/yr (BC Annual Report) |
| Director ID needed at filing? | No — just name and address |
| Director address | Any worldwide address accepted |
| Registered office | Must be in BC — we provide (AMB Vancouver) |
| SIN needed? | No |
| Language | English only |
| Our price | C$449 + C$350 gov fee + AMB mailbox (~C$156-240/yr) |
#### Ontario (ON)
| Item | Details |
|------|---------|
| Governing Act | Ontario Business Corporations Act (OBCA) |
| Resident director requirement | **None** — removed by Bill 213, July 5, 2021 |
| Incorporation portal | Ontario Business Registry (requires Ontario Business Account login) |
| Government fee | ~C$360 |
| Annual return | C$25/yr (Ontario Annual Return) |
| Director ID needed at filing? | Name, address, resident Canadian checkbox (can be "No") |
| Director address | Any worldwide address accepted |
| Registered office | Must be in Ontario — we provide (AMB Toronto) |
| SIN needed? | No |
| Language | English or French |
| Our price | C$449 + C$360 gov fee + AMB mailbox (~C$96-168/yr) |
#### Alberta (AB)
| Item | Details |
|------|---------|
| Governing Act | Alberta Business Corporations Act (ABCA) |
| Resident director requirement | **None** |
| Incorporation portal | Alberta Corporate Registry (account required) |
| Government fee | ~C$275 |
| Annual return | C$20/yr |
| Director address | Any worldwide address accepted |
| Registered office | Must be in Alberta |
| SIN needed? | No |
| Our price | Not yet offered — architecture supports it |
#### Saskatchewan (SK)
| Item | Details |
|------|---------|
| Governing Act | Saskatchewan Business Corporations Act (SBCA) |
| Resident director requirement | **None** |
| Government fee | ~C$266 |
| Annual return | C$50/yr |
| SIN needed? | No |
| Our price | Not yet offered |
#### Manitoba (MB)
| Item | Details |
|------|---------|
| Governing Act | The Corporations Act (Manitoba) (TMCCA) |
| Resident director requirement | **None** |
| Government fee | ~C$350 |
| Annual return | C$50/yr |
| SIN needed? | No |
| Our price | Not yet offered |
#### Quebec (QC)
| Item | Details |
|------|---------|
| Governing Act | Quebec Business Corporations Act (QBCA) |
| Resident director requirement | **None** |
| Government fee | ~C$379 |
| Annual return | C$89/yr |
| Language | **French required** for filings and corporate documents |
| SIN needed? | No |
| Banking caveat | **Venn does not serve Quebec corporations** per TOS |
| Our price | Not yet offered — French language requirement adds complexity |
### Provinces WITH Resident Director Requirement (NOT Foreign-Friendly)
These provinces require at least 25% of directors to be **resident Canadians**.
Non-residents cannot be the sole director.
| Province | Requirement | Governing Act |
|----------|-------------|---------------|
| Nova Scotia (NS) | 25% Canadian residents | NSCA s.71 |
| New Brunswick (NB) | 25% Canadian residents | NBBCA s.63 |
| Prince Edward Island (PE) | 25% Canadian residents | PEI Companies Act |
| Newfoundland & Labrador (NL) | 25% Canadian residents | CNLCA s.170 |
**Workaround:** If a client specifically needs one of these provinces, they need a Canadian
resident co-director. We do NOT offer nominee director services.
### Federal (CBCA) — NOT Recommended for Foreigners
| Item | Details |
|------|---------|
| Governing Act | Canada Business Corporations Act (CBCA) |
| Resident director requirement | **Yes — 25% must be Canadian residents** |
| Government fee | C$200 (cheapest) |
| Language | English and French |
| Why not recommended | Residency requirement defeats the purpose for foreign non-residents |
---
## Banking for Non-Resident Foreign Directors
This is the hardest part. The corporation is Canadian, but the directors/owners are not.
### Venn.ca (Our Current Referral Partner)
| Item | Details |
|------|---------|
| Eligibility | TOS says "Customers resident in Canada" but in practice this refers to the **corporation's domicile**, not the individual. Confirmed: US passport + US residential address accepted for account opening. |
| KYC | FINTRAC requirements — identity verification of beneficial owners via passport/ID |
| Quebec | Explicitly excluded from service (Venn TOS Section 2) |
| Non-resident directors? | **Yes — confirmed working.** PW account opened with US passport + US residential address for the director, and AMB mailbox (Canadian registered office) as the business address. |
| How it works | Business address = AMB mailbox (Canadian), Director/beneficial owner = foreign passport + foreign home address. Venn treats the corporation as Canadian (it is), doesn't require the director to be Canadian. |
| Recommendation | **Primary banking referral for all Canadian formations**, including non-resident directors. |
**Status:** Venn accepts non-Canadian directors. The key is that the **business address is
Canadian** (our AMB mailbox). The director's personal address and nationality don't matter.
Need to verify the full signup flow via Playwright recon to document exact ID types accepted
(passport, national ID, driver's license) and any country restrictions beyond Quebec and
OFAC-sanctioned nations.
### Wise Business (Recommended for Non-Residents)
| Item | Details |
|------|---------|
| Canadian registration | Wise Payments Canada Inc., regulated by FINTRAC |
| Accepts non-resident directors? | **Yes** — Wise serves businesses globally. Canadian corp with foreign directors accepted. |
| Verification | Passport + proof of address (home country) + company registration documents |
| Currencies | CAD, USD, EUR, GBP + 40 more |
| CAD account | Yes — local Canadian bank details for EFT/direct deposit |
| USD account | Yes — US routing number + account number for ACH |
| Cards | Wise Business debit cards for team spending |
| Fees | Low FX margins (0.4-0.6%), no monthly fee |
| Setup time | ~1-3 business days online |
### Airwallex (Good for High-Volume International)
| Item | Details |
|------|---------|
| Canadian registration | Airwallex (Canada) Ltd., regulated by FINTRAC |
| Accepts non-resident directors? | **Yes** — designed for international businesses |
| Verification | Company documents + director passport + proof of address |
| Currencies | CAD, USD + 60+ currencies |
| Best for | Businesses with high international transfer volume, marketplace payouts |
| Fees | Competitive FX, volume discounts |
| Setup time | ~2-5 business days |
### Payoneer (Good for Freelancers/Marketplaces)
| Item | Details |
|------|---------|
| Accepts non-resident directors? | **Yes** — global platform |
| Best for | Receiving payments from US/EU marketplaces (Amazon, Fiverr, Upwork) |
| CAD receiving account | Yes |
| USD receiving account | Yes |
### Traditional Banks (Require Branch Visit)
| Bank | Non-Resident Directors? | Requirements |
|------|------------------------|--------------|
| TD Canada Trust | Case-by-case | At least one person must visit a branch. Passport + company docs. |
| RBC Royal Bank | Case-by-case | Similar to TD. May require introduction by existing client. |
| BMO | Case-by-case | Commercial banking team handles non-resident applications. |
| Scotiabank | Most flexible for international | Caribbean/Latin American connections help. |
**Traditional banks generally require at least one in-person visit** to a Canadian branch
for initial account opening. Some allow subsequent management remotely.
---
## Payment Processing for Non-Resident Directors
| Processor | Accepts Non-Resident Directors? | Requirements |
|-----------|-------------------------------|--------------|
| **Stripe Canada** | **Yes** — accepts passport for identity verification | Canadian corporation + director passport + registered office address |
| **PayPal Canada** | **Yes** — more flexible than PayPal US | Canadian corporation + director passport |
| **Square Canada** | Yes | Canadian corporation + director ID |
| **Adyen** | Yes (enterprise) | KYC on all beneficial owners |
**Key insight:** Stripe Canada does NOT require SIN for the responsible person — they accept
a passport. This is a massive advantage over Stripe US (which requires SSN/ITIN).
---
## Our Recommendation Flow for Foreign Non-Residents
### On the Formation Order Page
When a customer selects "I don't have a US SSN or ITIN" or selects a non-US country of
residence, show a callout:
```
No US SSN or ITIN? Consider a Canadian corporation.
Canadian provinces like BC and Ontario allow 100% foreign ownership with no
Canadian residency requirement for directors. No SIN needed. Incorporate
remotely in 3-7 business days.
Benefits over US LLC for non-residents:
- No SSN/ITIN needed (Canada has no equivalent requirement)
- Bank account via Wise Business (accepts non-resident directors)
- Stripe Canada accepts passport for verification
- Lower corporate tax: 11% (BC) vs 21% (US federal)
- 0% sales tax on exports
C$449 + government fees (~C$350-360) + registered office mailbox.
[Start a Canadian Corporation →]
```
### On the CRTC Order Page
No changes needed — the CRTC page already targets foreign non-residents specifically
(US telecom operators who want Canadian carrier status). The Stripe Identity verification
already handles foreign passports.
---
## OFAC / Sanctions Considerations
Even though Canada has fewer barriers for foreigners, **OFAC sanctions still apply** if the
person intends to transact with US parties or use US financial infrastructure:
- Nationals of comprehensively sanctioned countries (Cuba, Iran, North Korea, Syria, parts
of Russia/Belarus/Venezuela/Myanmar) are blocked from US financial system regardless of
where they incorporate
- FINTRAC (Canada's AML agency) may also flag certain nationalities for enhanced due diligence
- Canadian banks perform their own sanctions screening
- **We do not provide sanctions compliance advice** — customers should verify their personal
compliance status with qualified legal counsel
---
## Summary: Which Province to Recommend for Foreign Non-Residents
| If the client... | Recommend | Why |
|-----------------|-----------|-----|
| Wants cheapest option | **Alberta** (C$275 gov fee) | Lowest filing fee, no residency requirement |
| Wants established business presence | **Ontario** (C$360 gov fee) | Largest market, Toronto address prestige |
| Wants Pacific/Asia-Pacific focus | **BC** (C$350 gov fee) | Vancouver gateway, strong Asian business ties |
| Wants cheapest annual maintenance | **Ontario** (C$25/yr) | Lowest annual return fee |
| Needs French-language corporate docs | **Quebec** (C$379 gov fee) | Only if specifically needed — banking complications |
| Wants federal presence in all provinces | **Not recommended** | 25% Canadian resident director requirement |
**Default recommendation:** British Columbia or Ontario, depending on business focus.
BC for Pacific/international, Ontario for North American market presence.
---
## Implementation Notes
### Formation Page Changes
1. Add a "Country of Residence" field to the formation order form
2. When country is NOT US and NOT Canada, show the "Consider Canadian Corporation" callout
3. When the user doesn't have SSN/ITIN (checkbox), show the callout
4. Link to the Canadian formation flow (same page, country=CA auto-selected)
### Banking Referral Changes
1. For ALL Canadian formations (resident or non-resident directors): recommend **Venn** as primary
- Confirmed: Venn accepts non-Canadian directors with foreign passport + foreign address
- Business address uses our AMB mailbox (Canadian) — this satisfies Venn's requirements
2. Wise Business and Airwallex as **secondary alternatives** (for clients who prefer them or need features Venn doesn't offer)
3. Banking referral email template stays the same (Venn link) — no need to branch by residency
### Product-Facts.md Updates
1. Add "No SSN or ITIN required" to Canadian formation bullet points
2. Add "Non-resident foreign directors welcome" language
3. Add banking alternatives for non-residents (Wise, Airwallex)
### Venn Verification Needed
- [x] Can a Canadian corporation with 100% non-resident directors open a Venn account? **YES — confirmed.** Business address uses AMB mailbox (Canadian). Director uses foreign passport + foreign home address.
- [ ] Run Playwright recon on Venn signup flow to document exact ID types accepted and country restrictions
- [ ] Confirm whether non-US/non-CA passports (e.g., EU, Asian, African) are also accepted
- [ ] Check if Venn requires the director to have a specific type of address proof

342
docs/formation-system.md Normal file
View file

@ -0,0 +1,342 @@
# Performance West — 52-Jurisdiction Business Formation System
**Last updated:** 2026-04-05
50 US states + District of Columbia + British Columbia (Canada) = 52 jurisdictions.
## Architecture
```
Customer Website API Database
| | | |
+- Select state ----------->| | |
+- Search name ------------>+- GET /states/:code/ ----->+- (proxy to Python) -->|
| <-- available/taken ---- | name-search | |
+- Fill details ----------->| | |
+- Submit order ----------->+- POST /formations ------->+- INSERT ------------->|
| <-- order number ------ | | formation_orders |
| | | |
| ERPNext (BPM Orchestrator) | |
| | | |
| +------+------+ | |
| | Webhook |<-- order.created --| |
| | triggers | (not polling) | |
| | worker | | |
| +------+------+ | |
| | | |
| +------+------+ | |
| | Load state | | |
| | adapter | | |
| +------+------+ | |
| | | |
| +------+------+ | |
| | Playwright |--> State SOS | |
| | automation | Portal | |
| +------+------+ | |
| | | |
| +------+------+ | |
| | Update DB |---- UPDATE ------->| |
| | with result | status=filed | |
| +------+------+ | |
| | | |
| <-- email docs --------- | | |
```
**ERPNext as BPM orchestrator:** ERPNext webhooks trigger formation workers on order events (e.g., `order.created`, `payment.confirmed`). Workers are event-driven, not polling-based.
## Directory Structure
```
scripts/formation/
+-- __init__.py
+-- base.py # StatePortal base class + data models
+-- name_search.py # Multi-state name search coordinator
+-- formation_worker.py # Event-driven queue processor (ERPNext webhook triggers)
+-- operating_agreement.py # Template-based .docx/.pdf generator
+-- ein_worker.py # IRS EIN online application (Playwright)
+-- document_delivery.py # SMTP email with attached formation docs
+-- states/
+-- __init__.py # Registry: get_adapter(), get_config(), STATES dict
+-- al/ # Alabama
| +-- __init__.py
| +-- config.py # Portal URLs, NW RA address, fees, CSS selectors
| +-- adapter.py # ALPortal(StatePortal) -- search + filing automation
+-- ak/ # Alaska
+-- az/ # Arizona
... (51 US: 50 states + DC)
+-- dc/ # District of Columbia
+-- bc/ # British Columbia (Canada) -- CRTC Carrier Package
```
## BC (Canada) — CRTC Carrier Package
British Columbia uses a completely different workflow from US states:
- **Not a state SOS filing** — BC adapter handles the CRTC Carrier Package registration
- **Different portal:** BC Corporate Online (bcregistryservices.gov.bc.ca) — anonymous, no login required
- **CRTC requirements:** Carrier registration with the Canadian Radio-television and Telecommunications Commission
- **Separate API endpoint:** `/api/v1/canada-crtc` for BC-specific orders
- **Separate DB table:** `canada_crtc_orders` tracks BC orders independently
- **14-step pipeline** managed by `services/canada_crtc.py`
The BC adapter implements `BCPortal(StatePortal)` but overrides both name search and filing methods for Canadian requirements. BC government fees are passed through at cost.
### BC Config (`scripts/formation/states/bc/config.py`)
The BC config contains configuration blocks for all Canadian-specific services:
| Config Block | Purpose |
|-------------|---------|
| `bits` | BITS (international telecom) registration — filing URL, required documents |
| `ccts` | CCTS (complaint commission) membership — application URL, required info |
| `gckey` | GCKey signup wizard — 5-step URLs, CSS selectors, hCaptcha sitekeys, password rules |
| `ats` | Annual Telecommunications Survey — 6 survey forms (REP-T/T1, REP-U, 802a, 802j, Facilities, Pricing) with deadlines and revenue thresholds |
| `corporate_obligations` | BC corporate tax/filing obligations — T2, GST/HST, T4/T4A, BC PST, WorkSafeBC, CRTC update |
### GCKey Provisioning
Each carrier needs its own GCKey account (Government of Canada credential) for filing
annual telecommunications surveys via My CRTC Account.
- **Username format:** `pw-{bc_number}`
- **Recovery email:** `regulatory@domain.ca` (we control the mailbox)
- **Automation:** `gckey_provisioner.py` — Playwright-based 5-step signup wizard
- **hCaptcha:** Invisible challenge on Step 2 (sitekey `99871bd1-7b22-417a-b6cc-7ef645e5147a`)
- **Credentials stored** in ERPNext Sensitive ID (encrypted)
- **Steps 3-5** selectors inferred from Step 1-2 recon — need verification on first live run
### Compliance Calendar (17 Entries Per Carrier)
Created at pipeline Step 13. Entries span regulatory, corporate tax, and survey obligations:
**Regulatory (7):** BC Annual Report, CRTC Maintenance, Mailbox Renewal, Domain Renewal,
DID Renewal, CCTS Renewal, CRTC Registration Update
**Corporate Tax (6):** T2 Return (Jun 30), Tax Payment (Mar 31), GST/HST (Mar 31),
T4/T4A Slips (Feb 28), BC PST (volume-based), WorkSafeBC (Mar 1 — if employees)
**Annual Telecom Surveys (4+):** REP-T/T1 (mandatory for ALL carriers, Mar 1),
REP-U/802a/802j/Facilities/Pricing (only if >$10M CAD revenue)
## State Adapter Status
### Name Search Methods
| Method | States | How It Works |
|--------|--------|-------------|
| **Socrata REST API** | CO, IA, IL, MI, NY, OR, PA, VT, WA | Free JSON API via state open data portals. No browser needed. |
| **SFTP Bulk Download** | FL | Free SFTP (public credentials) with daily entity dumps. Pre-load into local DB. |
| **Playwright** | All remaining ~40 US states | Browser automation against state SOS web portals. |
| **BC Corporate Online** | BC (Canada) | Browser automation against BC Registry Services. |
### Filing Method
**All 51 US jurisdictions use Playwright** — no state offers a filing API.
**BC (Canada)** uses Playwright against BC Corporate Online + CRTC portal.
### Implementation Status
| State | Name Search | LLC Filing | Corp Filing | Selectors Verified |
|-------|-------------|-----------|-------------|-------------------|
| **WY** | Working | Stub (needs filing walkthrough) | Stub | Name search: YES |
| **CO** | Socrata API (working) | Stub | Stub | N/A (API) |
| **BC** | Stub (BC Corporate Online) | N/A (CRTC Carrier Package) | Stub | Need portal inspection |
| All others | Stub (structure ready) | Stub | Stub | Need portal inspection |
~12 states have real implementations, ~40 still stubbed.
### Per-State Work Required
For each state, the following work is needed to go live:
1. **Visit the state's name search URL** in a browser
2. **Inspect form elements** — record CSS selectors for input fields, buttons, result areas
3. **Update `config.py`** with verified selectors
4. **Test name search** with known entities
5. **Visit the filing URL** and walk through the LLC formation form
6. **Record all filing form selectors** — name, agent, address, member, payment fields
7. **Implement the `file_llc()` method** with the state-specific workflow
8. **Test with a real formation** (or test/sandbox environment if available)
9. **Repeat for `file_corporation()`**
Estimated time: **1-3 hours per state** depending on portal complexity.
## API Endpoints
| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/states` | All 52 jurisdictions with fees |
| `GET` | `/api/v1/states/:code/name-search?name=...` | Name availability check |
| `POST` | `/api/v1/formations` | Create formation order |
| `GET` | `/api/v1/formations/:orderNumber` | Check order status |
| `GET` | `/api/v1/bundles` | List available service bundles |
| `GET` | `/api/v1/payment-methods` | Available payment methods + surcharges |
| `POST` | `/api/v1/agents` | Sales agent referral tracking |
| `POST` | `/api/v1/canada-crtc` | BC (Canada) CRTC Carrier Package order |
## Database Tables
### `state_filing_fees` — 52 rows (populated via migration 002)
All state/jurisdiction filing fees, portal URLs, special requirements (publication, franchise tax, etc.)
### `formation_orders` — Customer orders
Full order lifecycle: received -> processing -> submitted -> filed -> delivered.
Includes `erpnext_invoice_name` and `erpnext_payment_request` columns for ERPNext integration.
### `nwra_wholesale_pricing` — NW RA costs per state
Our wholesale cost for registered agent service (TBD from portal exploration).
### `canada_crtc_orders` — BC Canada orders
Separate table for CRTC Carrier Package orders with Canadian-specific fields.
Includes `erpnext_invoice_name` and `erpnext_payment_request` columns.
### `service_bundles` — Pre-configured service bundles
Bundle definitions (e.g., "Complete Formation + RA + EIN") with 20% discount applied.
### `bundle_orders` — Bundle order tracking
Links bundle purchases to individual service orders.
### `sales_agents` — Referral agent accounts
Agent ID (REF-XXXXX), contact info, commission tier, payout details.
### `commission_ledger` — Agent commission tracking
Per-order commission records: agent_id, order_id, service_type, flat_commission_amount, status (pending/paid).
### `payment_surcharges` — Payment method surcharge rates
ACH 0%, Card 3%, Klarna 5%, CashApp 3%, AmazonPay 3%, Crypto 0%.
### `accounting_advisors` — Advisor profiles
Accounting advisor details for post-formation consulting referrals.
### `accounting_support_accounts` — Client accounting support
Links clients to assigned accounting advisors.
### `conversation_flags` — Support conversation metadata
Flags for support conversations (escalation, priority, category).
## Formation Worker
`scripts/formation/formation_worker.py` is triggered by ERPNext webhooks (event-driven):
1. ERPNext webhook fires on `order.created` or `payment.confirmed`
2. Worker loads the appropriate state adapter
3. Verifies name availability
4. Submits the filing via Playwright
5. Updates DB with filing number and status
6. Generates operating agreement (if ordered)
7. Obtains EIN (if ordered)
8. Emails all documents to customer
**Human-paced delays:** 30-120 minutes between orders (configurable via env vars) to avoid appearing automated.
**Single-instance locking:** `fcntl.flock` on `/tmp/formation-worker.lock` prevents concurrent runs.
## Document Generation — PDF Conversion
- **Primary:** Windows DocServer (108.181.102.34, port 22422) — Office 365 Word COM automation via MinIO transport
- `docserver_worker.py` polls `to-convert/` bucket every 12 seconds
- Converts via Word COM, drops PDF in `converted/` bucket
- Heartbeat file at `minio://performancewest/docserver-heartbeat.json` (60s interval)
- Atomic uploads via `.tmp_` prefix + `copy_object` rename
- Task Scheduler: `PW-DocserverWorker` — auto-restart on failure
- **Fallback:** LibreOffice headless (`soffice --headless --convert-to pdf`) auto-activates when DocServer heartbeat stale (>5 min)
- **E2E tested:** 36KB DOCX → 82KB PDF in 12 seconds total round-trip
Operating agreements, CRTC letters, and other generated documents go through DocServer first. If the Windows VM is down, the system falls back to LibreOffice automatically.
## Northwest Registered Agent Integration
NW RA is used **only for registered agent service**, not for filings.
- Wholesale portal at accounts.northwestregisteredagent.com
- We order RA service for the customer's state after filing completes
- NW RA address for each state is stored in the state's `config.py`
## Operating Agreement Generator
Template-based using `python-docx`:
- Standard 10-article LLC operating agreement
- Variables filled from order data (entity name, state, members, etc.)
- Outputs `.docx` + `.pdf` (via Windows DocServer, LibreOffice fallback)
- Disclaimer: "This is not legal advice"
## EIN Obtainment
Playwright automation against IRS EIN Assistant:
- Available Mon-Fri 7am-10pm ET only
- Fills SS-4 equivalent online form
- Extracts EIN from confirmation page
- Saves PDF confirmation
## Pricing
| Component | Customer Pays | Our Cost |
|-----------|--------------|----------|
| State filing fee | Pass-through (varies $35-$725) | Same |
| Service fee (basic) | $179 | $0 (our margin) |
| Service fee (complete) | $399 | $0 (our margin) |
| RA service | $99/year (WY: $49/year) | ~$80/year (NW RA wholesale, TBD) |
| EIN | $49 | $0 (IRS is free) |
| Operating agreement | $99 | $0 (template-generated) |
| Expedited | Pass-through (varies by state) | Same |
## Service Bundles (20% Off)
Customers can purchase pre-configured bundles at a 20% discount off individual pricing:
| Bundle | Includes | Individual Total | Bundle Price |
|--------|----------|-----------------|-------------|
| **Starter** | Basic Formation + EIN | $198 | $158 |
| **Professional** | Complete Formation + EIN + RA (1yr) | $573 | $458 |
| **Full Package** | Complete Formation + EIN + RA (1yr) + Operating Agreement | $672 | $538 |
Bundle orders are tracked in `service_bundles` and `bundle_orders` tables.
## Payment Methods & Surcharges
| Method | Surcharge | Notes |
|--------|-----------|-------|
| **ACH Direct Debit** | 0% | Recommended — lowest cost |
| **Credit/Debit Card** | 3% | Via Adyen (Visa/MC/Amex + Apple Pay + Google Pay) |
| **Klarna (Pay in 4)** | 5% | Via Adyen — installment payments |
| **Cash App Pay** | 3% | Via Adyen |
| **Amazon Pay** | 3% | Via Adyen |
| **Crypto (BTC/ETH/USDC/USDT/MATIC/TRX/BNB/LTC/DOGE)** | 0% | Via SHKeeper (pay.performancewest.net) |
Surcharges are displayed at checkout before payment confirmation. Stored in `payment_surcharges` table. Surcharge injection is handled by the `performancewest_erpnext` Frappe app hook.
**SHKeeper** runs as a self-hosted instance in k3s (Kubernetes) at `pay.performancewest.net` for crypto payments. Supports any ERC-20/TRC-20/BEP-20 token. Webhook callbacks confirm payment and trigger formation workflow via ERPNext.
## Sales Agent Commission System
Sales agents refer clients using a unique referral code (format: `REF-XXXXX`).
### How It Works
1. Agent shares their referral link: `performancewest.net/form?ref=REF-XXXXX`
2. Client receives a **5% discount** on service fees
3. Agent earns a **flat commission per service** (not percentage-based)
### Commission Schedule
| Service | Agent Commission |
|---------|-----------------|
| Canada CRTC Package | $300 |
| Basic Formation | $50 |
| Bundle Purchase | $100 |
Commissions are tracked in ERPNext Commission Ledger DocType (with PostgreSQL backup in `commission_ledger`). Paid 14 days after order delivery via Relay ACH.
## Discount Code System
Discount codes can be created in ERPNext and applied at checkout:
- **Percentage-based** (e.g., 10% off)
- **Fixed amount** (e.g., $25 off)
- **Usage limits** (single-use, multi-use, or unlimited)
- **Expiration dates**
- Discount codes stack with agent referral discounts (capped at 15% total)
- Discounts apply to **service fees only** — never to state filing fees, government fees, or expedited fees
## Employment Pages
Employment/careers pages exist in the codebase but are **hidden in production** (not linked from navigation, not indexed by search engines). Gated behind `import.meta.env.DEV` flag. Reserved for future use.

359
docs/go-live-todo.md Normal file
View file

@ -0,0 +1,359 @@
# Performance West — Go-Live Deployment Checklist
**Last updated:** 2026-04-05
---
## PRIORITY 1 — Infrastructure ~~COMPLETE~~
- [x] Provision Proxmox Linux VM: Debian 13, 32GB RAM, 8 vCPU, 232GB SSD
- [x] Point DNS: performancewest.net, api., portal., crm., lists., analytics., pay., crypto., minio., minio-console., dev., api.dev. → 207.174.124.71
- [x] Run Ansible site.yml playbook to provision full stack
- [x] Run all DB migrations (001–035) against PostgreSQL
- [x] Set up Let's Encrypt TLS certificates for all 12 subdomains
- [x] Configure firewall (UFW): allow 80, 443, SSH 22022 only + trusted IPs
- [x] Configure fail2ban: sshd, nginx-badbots, pw-api jails
- [x] Set up `performancewest.service` systemd unit for auto-start on reboot
- [x] Install k3s with `--docker --disable=traefik`
- [x] Install Helm 3
- [x] Set up `dev.performancewest.net` / `api.dev.performancewest.net` dev stack (ports 4323/3002)
- [x] Provision Windows VM for DocServer (108.181.102.34, Office 365 Word COM, MinIO transport)
- SSH: port 22422 (key auth), Python 3.13 + pywin32 + minio SDK
- Task Scheduler: PW-DocserverWorker (auto-start, auto-restart on failure)
- Private network: 10.4.20.247 → MinIO via nginx
- [x] RAM upgrade: 62GB RAM verified, all 15 containers UP
---
## PRIORITY 2 — ERPNext + Integrations ~~COMPLETE~~
- [x] Configure ERPNext: create site, install erpnext + payments apps
- [x] Run setup wizard (Company: Performance West Inc., USD, America/Chicago)
- [x] Build custom ERPNext image with frappe_crypto + frappe_adyen + performancewest_erpnext
- [x] Install 6 apps: frappe, erpnext, payments, frappe_crypto, frappe_adyen, performancewest_erpnext
- [x] Import 7 custom DocTypes: Formation Order, Compliance Calendar, Sensitive ID, Referral Partner, Compliance Service, Sales Agent, Commission Ledger
- [x] Import 3 workflows: Formation Order (18 states), Canada CRTC (30 steps), Renewal
- [x] Create 16 service Items (CRTC Package $3,899, LLC Basic $179, etc.)
- [ ] Update Subscription Plans to new pricing (RA $99/yr ($49 WY), Annual Report $99/yr, CRTC Maintenance $349/yr)
- [ ] Update ERPNext Item rates: LLC Basic $179 (was $149), RA $99 (was $125), add WY RA $49
- [ ] Create new Items: CA Formation C$449, Formation Maintenance $179/yr, Free DID (stub)
- [x] Add custom fields: Sales Order (30+ fields incl. identity, esign, binder, regulatory)
- [x] Add custom fields: Sales Invoice (surcharge_pct, payment_gateway, stripe_payment_intent)
- [x] Hide 18 irrelevant modules for all users
- [x] Generate API keys (ERPNEXT_API_KEY / ERPNEXT_API_SECRET)
- [x] Configure ERPNext outgoing SMTP (co.carrierone.com:587, noreply@performancewest.net)
- [x] Configure ERPNext incoming email (support@performancewest.net → auto-create Issue)
- [x] Import 18 ERPNext webhooks: 11 CRTC + 7 Formation (all pointing to Express API)
- [x] Create ERPNext roles: Sales Agent (no desk), Accounting Advisor (desk access)
- [x] Import 20 compliance service fixtures (compliance_services.json)
- [x] Configure ERPNext Assignment Rule: Accounting Support → Accounting Advisor role
- [x] Portal Settings: enable Sales Order, Sales Invoice, Issue for customer portal
- [x] Website Settings: PW branding, navy theme, custom CSS
- [x] Create portal.performancewest.net DNS + SSL + nginx vhost → ERPNext :8080
- [x] 6 CRTC workflow notification emails (Received → Delivered) using Carbonio SMTP
- [ ] Configure ERPNext incoming email IMAP password for support@ account
- [ ] Create ERPNext Payment Gateway Account for Crypto-Crypto (SHKeeper)
- [ ] Configure Crypto Payment Settings in ERPNext UI (pay.performancewest.net + SHKeeper API key)
- [ ] Configure ERPNext Assignment Rules: expand for CRTC ticket routing
---
## PRIORITY 3 — Payment Processing
- [x] Deploy SHKeeper via Helm in k3s (7 crypto daemons: BTC, ETH, MATIC, BNB, TRX, LTC, DOGE)
- [x] Set up SHKeeper nginx reverse proxy at pay.performancewest.net + crypto.performancewest.net
- [x] Build frappe_crypto app (SHKeeper gateway, checkout page, webhook receiver)
- [x] Rewrite checkout.ts: Stripe Checkout Sessions (card + ACH + Klarna), PayPal Orders v2, SHKeeper crypto
- [x] Add Stripe webhook handler — events: checkout.session.completed, payment_intent.succeeded, balance.available
- [x] Add SHKeeper webhook handler for crypto payment confirmation
- [x] Add PayPal capture / webhook handler
- [x] Order confirmation email on payment (Carbonio SMTP via email.ts)
- [x] Auto-create Sales Invoice + Payment Entry on payment (createInvoiceFromSalesOrder)
- [x] Fund detection: balance.available webhook → T+2/T+4 business day advance → Stripe Issuing topup
- [x] Abandoned cart recovery (payment_reminder.py cron every 5 min, 15min/1d/2d intervals)
- [x] Payment method selector on order form Step 5 (ACH recommended, expedited → PayPal/crypto only)
- [x] Expedited processing toggle (+$500, restricts to PayPal/crypto only)
- [ ] Set `STRIPE_SECRET_KEY` + `STRIPE_WEBHOOK_SECRET` + `STRIPE_IDENTITY_WEBHOOK_SECRET` in .env
- [ ] Register Stripe webhook at api.performancewest.net/api/v1/webhooks/stripe
- Events: checkout.session.completed, payment_intent.succeeded, balance.available, identity.verification_session.verified
- [ ] Set `SHKEEPER_API_KEY` in .env
- [ ] Test end-to-end Stripe card payment flow
- [ ] Test end-to-end Stripe ACH payment flow
- [ ] Test end-to-end PayPal payment flow
- [ ] Test end-to-end crypto payment flow
- [ ] Adyen: apply for merchant account (future — not blocking launch)
---
## PRIORITY 4 — Banking & Financial
- [ ] Set up Relay virtual debit card (SID-0002) dedicated to filing fees
- [ ] Store Relay card details in ERPNext Sensitive ID (encrypted)
- [ ] Set up Relay checking account structure (Operating, Filing Fees, Profit, Tax, Commissions, Owner Pay)
- [ ] Store PayPal Mastercard (SID-0001) details in ERPNext Sensitive ID
- [ ] Change NW RA portal password (was shared in chat — URGENT)
- [ ] Create Northwest Registered Agent wholesale orders for each state's RA address
---
## PRIORITY 5 — Document Generation & Workers
- [x] Set up MinIO: create performancewest bucket, configure access
- [x] Upload 9 DOCX templates to MinIO (to-convert/ → converted/ transport buckets created)
- [x] Configure Ollama with qwen2.5:7b model
- [x] Install Playwright browsers (chromium) in worker container
- [x] Add PyJWT to scripts/requirements.txt (for portal eSign JWT generation)
- [x] DocServer: MinIO-based transport (docserver_worker.py polls to-convert/, drops converted/)
- Worker polls every 12s, heartbeat every 60s at minio://performancewest/docserver-heartbeat.json
- LibreOffice headless fallback auto-activates when DocServer unavailable
- [x] Test LibreOffice fallback DOCX-to-PDF conversion *(verify manually)*
- [x] Provision Windows VM, run docserver/install.ps1 with MinIO credentials
- [x] Verify Word COM conversion end-to-end (36KB DOCX → 82KB PDF, 12s round-trip)
- [x] MinIO nginx allow-list updated with private network IP 10.4.20.247
- [x] ERPNext CSS fix after reboot (`chmod o+x /var/lib/docker` + `bench build --force`)
- [x] ERPNext "Sent via ERPNext" email footer disabled (`disable_standard_email_footer: 1`)
---
## PRIORITY 6 — External Accounts & Services
- [ ] Claim Google Business Profile at business.google.com for Performance West Inc.
- [ ] Claim Trustpilot business profile at business.trustpilot.com
- [ ] Update Google Reviews link in homepage with actual Google Place ID
- [ ] Create SOSDirect account for Texas state filings
- [ ] Create UtahID account for Utah state filings
- [ ] Sign up for 2captcha or anticaptcha (Delaware CAPTCHA solving)
- [ ] Set up Porkbun account for .ca domain registration (CRTC service)
- [ ] Set `PORKBUN_API_KEY` / `PORKBUN_SECRET_KEY` in .env
- [ ] Set up Flowroute account for Canadian DID provisioning
- [ ] Set `FLOWROUTE_ACCESS_KEY` / `FLOWROUTE_SECRET_KEY` in .env
- [ ] Configure HestiaCP on cp.carrierone.com for .ca domain hosting + email
- [ ] Set `HESTIA_SSH_KEY` path in workers container .env (key must be mounted or baked)
- [ ] Test HestiaCP provisioner: `python -m scripts.workers.hestia_provisioner provision test.ca "Test Company"`
- [ ] Verify all 14 mailbox types create correctly per domain
- [ ] Set up Anytime Mailbox wholesale/partner account
- [ ] Configure ANYTIME_MAILBOX_IMAP_PASS for OTP auto-fetch
- [x] Configure client email processor cron (every 15 min): deployed via `worker-crons` ansible role (`pw-client-email-processor.timer`)
---
## PRIORITY 7 — Listmonk (Email Marketing) ~~COMPLETE~~
- [x] Deploy Listmonk at lists.performancewest.net (Docker, PostgreSQL-backed)
- [x] Configure SMTP2GO outbound email (separate from Carbonio transactional SMTP)
- [x] Import 10,191 FCC RMD contacts into Listmonk (3 subscriber lists)
- [x] Configure bounce processing via POP3 from Carbonio (bounces@performancewest.net)
- [x] Create 22 scheduled campaigns across 4 lists
- [x] nginx vhost at lists.performancewest.net with Let's Encrypt cert
- [x] Remove RMD/Robocall Mitigation Database language from all campaigns
---
## PRIORITY 8 — Analytics & Security
- [x] Deploy Umami analytics container at analytics.performancewest.net
- [x] Umami first-run config: site registered, site ID `55250014-ee15-44ac-a1f6-81dabad3fe0f`
- [x] Add Umami tracking script to Base.astro (`!isDev` guard, production only)
- [x] nginx CSP includes analytics.performancewest.net in script-src + connect-src
- [x] CAA DNS records for Let's Encrypt
- [x] HSTS headers on all domains
- [x] fail2ban pw-api jail (rate-limit abusers at /api/v1/checkout)
- [ ] Verify SSL Labs A+ grade after deployment
- [ ] Verify SecurityHeaders.com A+ grade
- [ ] Verify Mozilla Observatory A+ grade
- [ ] Verify Google Safe Browsing clean status
---
## PRIORITY 9 — State Formation Automation
- [ ] Populate CSS selectors for top 10 states (WY, CO, DE, FL, TX, NV, UT, NM, OH, MT)
- [ ] Test Wyoming name search end-to-end via Playwright
- [ ] Test Colorado name search via Socrata API (confirmed working in isolation)
- [ ] Test full formation order flow: order → name search → payment → filing
- [ ] Implement ~40 remaining state adapters (only ~12 have real implementations)
---
## PRIORITY 10 — Canada CRTC Service
- [x] CRTC order form (5-step, identity verification, AMB location picker, payment methods)
- [x] Stripe Identity gate (Step 4, auto-advance after verified, form snapshot persistence)
- [x] AMB location scraper (daily cron, operator_name extraction, sold-out deactivation)
- [x] Anytime Mailbox signup automation (Playwright + IMAP OTP from Carbonio)
- [x] Flowroute DID search + purchase (area codes 604/778/236/250)
- [x] .ca domain registration via Porkbun (CIRA CPR: BC corp number, category CCO)
- [x] HestiaCP provisioner: 14 mailboxes per domain including regulatory@, abuse@, postmaster@
- Credentials stored in ERPNext Sensitive ID (encrypted)
- Email 1 (brief): domain live notification
- Email 2 (credentials): all 14 passwords, IMAP/SMTP settings, webmail URL
- [x] BC incorporation via COLIN (anonymous filing, no login required)
- [x] CRTC notification letter generation (DOCX template → MinIO transport → Word/LibreOffice PDF)
- [x] eSign portal page (/portal/sign) — canvas drawing pad, letter preview iframe, JWT auth
- Pipeline pauses at Step 6b, emails client JWT-signed sign link (72h expiry)
- Signature stored as base64 PNG in PG (esign_signature_b64)
- On submit: ERPNext workflow advances to "CRTC Submitted", resume_crtc_pipeline job dispatched
- [x] Corporate binder compilation (PDF merge: certificate + articles + CRTC letter + OA)
- [x] Binder delivery email: FROM regulatory@domain.ca (HestiaCP SMTP credentials)
- AMB binder label: `c/o <operator_name>`, unit number
- Own-address binder label: company name + attn contact
- [x] Admin print/ship email (PirateShip USPS label instructions)
- [x] Client portal order status page at portal.performancewest.net/orders
- 10-step visual pipeline with colored chips (completed/active/pending)
- Action CTAs: "Complete Setup →" (Client Selection), "Sign CRTC Letter →" (Pending eSign)
- Invoice table with Paid/Partial/Unpaid badges
- [x] Phase 2 customer auth: ERPNext Website User created on order, portal password set from success page
- [x] Phase 4 auto-invoice: Sales Invoice + Payment Entry created on payment
- [x] Phase 5 ERPNext notifications: 6 workflow state emails (Received → Delivered) via Carbonio
- [x] Phase 6 custom portal /orders page in performancewest_erpnext Frappe app
- [x] BITS registration step (Step 11) — GCKey provisioning via Playwright + admin ToDo for BITS filing
- GCKey signup wizard automated: 5-step flow, hCaptcha handling, credentials to ERPNext Sensitive ID
- Username format: `pw-{bc_number}`, recovery email: `regulatory@domain.ca`
- [x] CCTS registration step (Step 12) — admin ToDo + client obligations email
- [x] Compliance calendar auto-creation (Step 13) — 17 entries per carrier
- Regulatory: BC annual report, CRTC maintenance, mailbox, domain, DID, CCTS, CRTC update
- Tax: T2, corporate tax, GST/HST, T4/T4A, BC PST, WorkSafeBC
- Surveys: REP-T/T1 (mandatory), REP-U/802a/802j/Facilities/Pricing (>$10M threshold)
- [x] Compliance calendar renewal lifecycle (`renewal_worker.py`)
- Daily cron: upcoming → due soon → invoice sent → paid → completed → re-calendar
- Billable items generate ERPNext Sales Invoice; payment required before completion
- Webhook handler: `handle_renewal_payment` in job_server.py
- [x] CRTC pipeline expanded from 12 to 14 steps (BITS + CCTS + expanded compliance + review)
- [x] BC config expanded: `bits`, `ccts`, `gckey`, `ats` (6 survey forms), `corporate_obligations` (7 tax/filing items)
- [ ] BC COLIN selector verification (Steps 5-12 need live session testing)
- [ ] Verify GCKey Steps 3-5 selectors on first live provisioning run
- [ ] Verify AMB operator_name extraction on next daily scraper run
- [ ] Test full CRTC order end-to-end on dev stack
- [ ] Deploy BITS/CCTS/compliance/renewal code to production
- [x] Add renewal cron — deployed via `worker-crons` ansible role (`pw-renewal-worker.timer` daily 04:00 UTC)
- [x] Add USF factor monitor cron — deployed via `worker-crons` ansible role (`pw-usf-factor-monitor.timer` daily 09:00 CT)
- Polls https://www.usac.org/service-providers/making-payments/contribution-factors/
- On detecting a new quarterly factor, emails all FCC-carrier customers (bcc justin@) with the new % and the delta vs. prior quarter so they can update their USF surcharges before the quarter starts
- Requires migration 049 (`usf_contribution_factors` table) to be applied
- [x] Create ERPNext Items for renewal invoicing: CRTC-MAINT-ANNUAL, MAILBOX-RENEWAL, BC-ANNUAL-REPORT, DOMAIN-RENEWAL-CA, COMPLIANCE-OTHER (fixture: `performancewest_erpnext/performancewest_erpnext/fixtures/item.json`; imports on `bench migrate`)
- [ ] Import updated Compliance Calendar DocType to production ERPNext
---
## PRIORITY 11 — Multi-Province, Canadian Formation & Universal Compliance
> Full plan: [`docs/multi-province-plan.md`](multi-province-plan.md) — 16 sub-phases, 28-36 hours, 5-6 sessions
**Three interconnected features:**
1. Multi-province CRTC ($3,899, Ontario first)
2. Standalone Canadian formation (C$449 + gov fees, separate flow from CRTC)
3. Universal compliance calendar (all order types: US + CA formation + CRTC)
- [ ] Phase 0: OBR + CRA BN Playwright recon (Ontario Business Registry + CRA Business Number)
- [ ] Phase 1: ProvinceConfig abstraction + universal compliance module design
- [ ] Phase 2: DB migrations (CRTC province column + formation entity types + country)
- [ ] Phase 3a-d: Ontario config, adapter, AMB scraper extension, Flowroute ON area codes
- [ ] Phase 3e: CanadianIncorporationHandler (shared pipeline for formation-only + CRTC)
- [ ] Phase 3f: CRA Business Number registration stub ($49 add-on)
- [ ] Phase 3g: Universal compliance entry creator (all order types)
- [ ] Phase 4: Service page province comparison table + FAQ rewrite
- [ ] Phase 5a: CRTC order form multi-province (province selector, dynamic content)
- [ ] Phase 5b: Formation page backend wiring (frontend already supports Canada)
- [ ] Phase 6a: CRTC API route (accept province)
- [ ] Phase 6b: CRTC pipeline refactor (compose with CanadianIncorporationHandler)
- [ ] Phase 6c: Formation API route (accept CA provinces + entity types ltd/inc/corp)
- [ ] Phase 7a: Canadian province compliance configs (BC + ON corporate obligations)
- [ ] Phase 7b: US state compliance configs (all 51 jurisdictions — annual report, franchise tax, RA)
- [ ] Phase 8: Dev E2E tests (CRTC ON + CA formation-only + US formation compliance)
**New products:**
- CA Formation: C$449 + gov fees (incorp + minutes + binder + compliance calendar). AMB mailbox separate.
- CRA BN add-on: $49
- Formation Maintenance Bundle (US or CA): $179/yr (annual report $99 + RA renewal $99)
---
## PRIORITY 12 — Sales & Marketing
- [ ] Configure Google Analytics 4 property and connect to Umami export
- [ ] Set up Google Search Console for performancewest.net
- [ ] Set up Google Ads account (future)
- [ ] Create referral program landing page (/agents)
- [ ] Onboard first 3 sales agents (test referral code flow end-to-end)
- [ ] Create Trustpilot review request automation in post-delivery email
---
## PRIORITY 13 — Content & Video
- [ ] Generate AI-narrated video for Canada CRTC service page
- [ ] Generate marketing videos for US formation services
- [ ] Create vendor directory PDF for CRTC clients (5 categories, delivered via portal)
- [ ] Create US fintech banking guide PDF for CRTC clients (Wise, Airwallex, Payoneer)
---
## PRIORITY 14 — MCP Server & AI Integration
- [ ] Publish MCP server package to npm (`@performancewest/mcp`)
- [ ] Test all 10 MCP tools against live ERPNext
- [ ] Document MCP server usage for AI agent integration
---
## PRIORITY 15 — Client Portal & Testing
- [x] Portal order status page (portal.performancewest.net/orders) — visual 10-step pipeline
- [x] eSign page (/portal/sign) — canvas signature, letter preview, JWT auth
- [x] Client selection page (/portal/setup) — unit picker, DID picker, confirm
- [x] Domain search page (/portal/domain-search)
- [x] Manage services page (/portal/manage-services)
- [ ] Phase 7: SupportWidget → ERPNext Issue direct (remove PG tickets fallback)
- [ ] Phase 8: Deprecate PG customer auth (portal-auth.ts login/register → ERPNext portal only)
- [ ] Phase 9: E2E test — order → payment → invoice → portal login → order status → ticket
- [ ] Load test: simulate 10 concurrent CRTC orders through the full pipeline
- [ ] Mobile test all order form steps on iOS Safari + Android Chrome
---
## PRIORITY 16 — Environment Variables Still Needed
- [ ] `STRIPE_SECRET_KEY` — from Stripe Dashboard (live key)
- [ ] `STRIPE_WEBHOOK_SECRET` — from Stripe Dashboard → Webhooks endpoint
- [ ] `STRIPE_IDENTITY_WEBHOOK_SECRET` — from Stripe Dashboard (identity webhook)
- [x] `CUSTOMER_JWT_SECRET` — generated and set (M0IFZv9ipOxU5juZnf7zwdTfpk_5_5...)
- [x] `SMTP_PASS` — set ($m)}4G8&!yu;{)#]sp, Carbonio noreply@)
- [ ] `SHKEEPER_API_KEY` — from SHKeeper admin panel at crypto.performancewest.net
- [ ] `PORKBUN_API_KEY` / `PORKBUN_SECRET_KEY` — from Porkbun account API settings
- [ ] `FLOWROUTE_ACCESS_KEY` / `FLOWROUTE_SECRET_KEY` — from Flowroute account
- [ ] `HESTIA_SSH_KEY` — path to SSH private key on workers container (mount via volume)
- [ ] `ANYTIME_MAILBOX_IMAP_PASS` — mailbox password for IMAP OTP fetch
- [ ] `PAYPAL_CLIENT_ID` / `PAYPAL_CLIENT_SECRET` — from PayPal developer dashboard
- [ ] `MINIO_ACCESS_KEY` / `MINIO_SECRET_KEY` — already set (verify on server)
- [x] Windows DocServer MinIO credentials — configured in `C:\docserver\docserver.env` on VM
---
## PRIORITY 17 — Low Priority / When Revenue Supports
- [ ] Adyen merchant account application (card/ACH/Klarna/CashApp/AmazonPay via Adyen)
- [ ] Stripe Issuing cardholder setup for SID-0002 (Relay is interim filing card)
- [ ] Automated annual report filing for existing clients
- [ ] Attorney review integration (removed from site; may re-add as premium tier)
- [ ] Multi-language support (French for Quebec clients)
- [ ] Mobile app (React Native) for client portal access
- [ ] Wholesale API for resellers and referring attorneys
---
## POST-LAUNCH MONITORING
- [ ] Set up UptimeRobot (or similar) monitors for:
- https://performancewest.net (site)
- https://api.performancewest.net/health (API)
- https://portal.performancewest.net (ERPNext portal)
- https://lists.performancewest.net (Listmonk)
- SHKeeper /health endpoint
- [ ] Set up Grafana + Prometheus for container metrics (future)
- [ ] Set up PagerDuty or similar for on-call alerts
- [ ] Review Umami weekly dashboard every Monday
- [ ] Review ERPNext open Issues weekly (customer support queue)
- [ ] Review abandoned cart report weekly (payment_reminder.py logs)
- [ ] Monthly: review state filing fee table for changes
- [ ] Monthly: review AMB location pricing (daily scraper catches this automatically)
- [ ] Quarterly: rotate API keys (Stripe, SHKeeper, Porkbun, Flowroute)

271
docs/infrastructure.md Normal file
View file

@ -0,0 +1,271 @@
# Infrastructure
**Last updated:** 2026-04-06
## Production Server — Linux VM
| Resource | Spec |
|----------|------|
| OS | Debian 13 (Trixie) |
| IP | 207.174.124.71 |
| SSH | `ssh -p 22022 deploy@207.174.124.71` |
| vCPU | 8 |
| RAM | 32 GB |
| Disk | 232 GB SSD |
| Network | Bridged, static IP |
## Proxmox VM — Windows (DocServer) — NOT YET PROVISIONED
| Resource | Spec |
|----------|------|
| OS | Windows Server 2022 |
| vCPU | 2 |
| RAM | 4 GB |
| Disk | 40 GB SSD |
| Software | Microsoft Office 2021 |
| Service | DocServer on port 5050 |
The Windows VM will provide high-fidelity DOCX-to-PDF conversion via Office 2021. DocServer exposes a REST API on port 5050. LibreOffice on the Linux VM serves as a fallback.
## External Infrastructure Dependencies
- **HestiaCP** — `cp.carrierone.com:22022` — DNS management and mail hosting for `performancewest.net` (user: `justin`)
- **Nameservers** — `ns1.he.net` through `ns5.he.net` + `ns0.cp.carrierone.com`
## Auto-Start on Reboot
All services are configured to restart automatically after a reboot via two complementary mechanisms:
### 1. systemd `performancewest.service`
A custom systemd unit at `/etc/systemd/system/performancewest.service` runs `docker compose up -d --remove-orphans` after the Docker daemon and network are ready. This ensures the full compose stack is reconciled on every boot.
```bash
# Status
sudo systemctl status performancewest.service
# Manually start/stop the stack
sudo systemctl start performancewest.service
sudo systemctl stop performancewest.service
# Reload (runs docker compose up -d --remove-orphans)
sudo systemctl reload performancewest.service
```
Enabled services verified: `performancewest`, `docker`, `nginx`, `fail2ban`, `unattended-upgrades`, `k3s`.
### 2. Docker `restart: unless-stopped`
Every container in `docker-compose.yml` has `restart: unless-stopped`. If Docker itself restarts, each container is individually restarted by the Docker daemon before the systemd unit fires.
### 3. k3s (SHKeeper)
k3s is a separate systemd service (`k3s.service`) that starts automatically on boot. All SHKeeper pods have `restartPolicy: Always` and are managed by Kubernetes deployments.
### Boot order
```
Kernel → network-online.target → docker.service → performancewest.service
└─ docker compose up -d
→ k3s.service → SHKeeper pods auto-reconciled
```
## Docker Compose Orchestration
All Docker services are defined in `docker-compose.yml` at the project root. Environment variables are sourced from `.env` (see `.env.example` for required values).
```bash
# Start all services
cd /opt/performancewest
docker compose up -d
# Rebuild after code changes
docker compose build site api && docker compose up -d site api
# View logs
docker compose logs -f site api workers
# Stop everything
docker compose down
```
### Running Containers (13 Docker + k3s pods)
**Docker Compose:**
| Container | Image | Port |
|-----------|-------|------|
| site | performancewest-site (Astro/nginx) | 4322 |
| api | performancewest-api (Express/TS) | 3001 |
| api-postgres | postgres:16-alpine | 5432 |
| erpnext | performancewest-erpnext:latest (custom) | 8080 |
| erpnext-worker-default | performancewest-erpnext:latest | — |
| erpnext-worker-short | performancewest-erpnext:latest | — |
| erpnext-scheduler | performancewest-erpnext:latest | — |
| erpnext-mariadb | mariadb:10.6 | 3306 |
| erpnext-redis | redis:7-alpine | 6379 |
| listmonk | listmonk/listmonk:latest | 9100 |
| listmonk-postgres | postgres:16-alpine | — |
| minio | minio/minio:latest | 9000/9001 |
| workers | performancewest-workers (Python) | 8090 |
| ollama | ollama/ollama:latest | 11434 |
| umami | ghcr.io/umami-software/umami:postgresql-latest | 3100 |
| umami-postgres | postgres:16-alpine | — |
**k3s / Kubernetes (SHKeeper):**
| Deployment | Replicas | Port |
|------------|----------|------|
| shkeeper-deployment | 1 | 5000 (LoadBalancer) |
| bitcoin-shkeeper | 3 | — |
| ethereum-shkeeper | 3 | — |
| polygon-shkeeper | 3 | — |
| bnb-shkeeper | 3 | — |
| tron-shkeeper | 3 | — |
| litecoin-shkeeper | 3 | — |
| dogecoin-shkeeper | 3 | — |
| mariadb (SHKeeper) | 1 | — |
### Service Dependencies
```
site (standalone)
api → api-postgres
erpnext → erpnext-mariadb, erpnext-redis
erpnext-worker-default → erpnext
erpnext-worker-short → erpnext
erpnext-scheduler → erpnext
listmonk → listmonk-postgres
minio (standalone)
workers → erpnext, minio, api-postgres, ollama
ollama (standalone)
umami → umami-postgres
```
SHKeeper pods are managed by k3s and are independent of Docker Compose.
### ERPNext Notes
- Image: `performancewest-erpnext:latest` — custom image built from `erpnext/Dockerfile` extending `frappe/erpnext:version-15`
- Baked-in apps: `frappe_crypto` (1.0.0), `frappe_adyen` (1.0.0), `performancewest_erpnext` (1.0.0)
- Database: MariaDB 10.6 (NOT PostgreSQL — ERPNext v15 doesn't support Postgres)
- 6 apps installed: frappe, erpnext, payments, frappe_crypto, frappe_adyen, performancewest_erpnext
- Admin credentials: `Administrator` / stored in Ansible vault
- API keys set in `.env`: `ERPNEXT_API_KEY` / `ERPNEXT_API_SECRET`
- First-run init: `bench new-site` is run by the Ansible `erpnext` role on first deploy (guarded by sentinel file `erpnext-initialized`)
### k3s Notes
- Installed with `--docker --disable=traefik` to avoid port conflicts with host nginx
- Helm 3 installed for SHKeeper chart management (`vsys-host/shkeeper`)
- SHKeeper exposed via LoadBalancer service at port 5000, proxied through host nginx
- k3s uses Docker as its container runtime (not containerd)
## nginx Reverse Proxy
Host-level nginx handles TLS termination. Configs live in `/etc/nginx/sites-available/`. All deployed via the Ansible `nginx` role from `infra/ansible/roles/nginx/templates/`.
| Config file | Domain | Upstream |
|---|---|---|
| `pw-site.conf` | `performancewest.net`, `www.` | `:4322` |
| `pw-api.conf` | `api.performancewest.net` | `:3001` |
| `pw-crm.conf` | `crm.performancewest.net` | `:8080` (requires `proxy_set_header Host performancewest.net`) |
| `pw-listmonk.conf` | `lists.performancewest.net` | `:9100` |
| `pw-portal.conf` | `portal.performancewest.net` | `:8080` (static assets from Docker volumes, Frappe branding replaced via sub_filter) |
| `pw-analytics.conf` | `analytics.performancewest.net` | `:3100` |
| `pw-btcpay-tls.conf` | `pay.performancewest.net` | SHKeeper `:5000` |
| `pw-crypto-tls.conf` | `crypto.performancewest.net` | SHKeeper admin |
| `pw-minio.conf` | `minio.performancewest.net` | `:9000` |
| `pw-minio.conf` | `minio-console.performancewest.net` | `:9001` |
### TLS Certificates
Managed by Certbot with automatic renewal (cron at 3:30 AM daily):
```bash
# Certificates obtained for:
performancewest.net + www.performancewest.net
api.performancewest.net
crm.performancewest.net
analytics.performancewest.net
pay.performancewest.net
crypto.performancewest.net
minio.performancewest.net
minio-console.performancewest.net
# Note: mail.performancewest.net cert lives on HestiaCP (207.174.124.15)
```
## Firewall (UFW)
```
Rule 1: ALLOW IN from 24.162.65.184 # Trusted IP 1
Rule 2: ALLOW IN from 76.228.206.147 # Trusted IP 2
Rule 3: ALLOW IN 22022/tcp # SSH
Rule 4: ALLOW IN 80/tcp # HTTP
Rule 5: ALLOW IN 443/tcp # HTTPS
Default: DENY incoming, ALLOW outgoing
```
## Fail2ban
Jails active: `sshd`, `nginx-badbots`, `pw-api` (enabled after API container log exists).
Trusted IPs whitelisted in `/etc/fail2ban/jail.local`: `24.162.65.184`, `76.228.206.147`.
## Unattended Security Updates
Configured via `/etc/apt/apt.conf.d/50unattended-upgrades` and `20auto-upgrades`:
- Daily apt update + upgrade
- Automatic reboot at 4:00 AM if kernel update requires it
- 7-day autoclean
## Ansible Deployment
```
infra/ansible/
inventory/
hosts.yml # deploy user, port 22022, 207.174.124.71
bootstrap.yml # root user, first-run only
group_vars/all.yml # all vars + vault references
playbooks/
bootstrap.yml # First-run: common + docker (runs as root)
site.yml # Full provisioning: all roles
deploy.yml # Code deploy only (no infra changes)
run-migrations.yml # Run a specific SQL migration
roles/
common/ # Packages, deploy user, SSH hardening, UFW
docker/ # Docker CE + compose plugin + performancewest.service (boot auto-start)
postgresql/ # API postgres + migrations + backup cron
app/ # Express API container + .env
site/ # Astro site container
erpnext/ # ERPNext + MariaDB + workers + bench new-site (custom image build)
minio/ # MinIO + mc client + bucket creation
workers/ # Python workers + Ollama + model pull
shkeeper/ # k3s + Helm + SHKeeper deployment (replaces old bitcart role)
nginx/ # nginx + certbot TLS (all domains) + fail2ban
```
### Deploy Commands
```bash
# First-time server setup (run as local user with SSH key to root)
ansible-playbook -i infra/ansible/inventory/bootstrap.yml infra/ansible/playbooks/bootstrap.yml
# Full provisioning (run after bootstrap — uses deploy user)
ansible-playbook -i infra/ansible/inventory/hosts.yml infra/ansible/playbooks/site.yml --ask-vault-pass
# Code-only deploy (no infra changes, no vault needed for most)
ansible-playbook -i infra/ansible/inventory/hosts.yml infra/ansible/playbooks/deploy.yml
# Run a specific DB migration
ansible-playbook -i infra/ansible/inventory/hosts.yml infra/ansible/playbooks/run-migrations.yml -e "migration=010_canada_crtc.sql"
```
## Monitoring
- **Uptime checks** — external HTTP monitoring for all subdomains
- **ERPNext alerts** — system errors surfaced as ERPNext Issues
- **Docker restart policies** — `unless-stopped` on all containers
- **k3s pod management** — Kubernetes ensures SHKeeper pods stay running
- **systemd auto-start** — `performancewest.service` (enabled) runs `docker compose up -d` on every boot
- **PostgreSQL backups** — `/usr/local/bin/pg-backup.sh` runs at 2 AM daily, 30-day retention, stored in `/opt/backups/postgresql/`

309
docs/marketing.md Normal file
View file

@ -0,0 +1,309 @@
# Performance West Inc. — Marketing Plan
**Last updated:** 2026-03-27
---
## Target Audience
Small-to-medium business owners (1–200 employees) who need regulatory compliance help but
don't want to pay $300–$500/hr attorney rates for what is often procedural, non-litigation
work. They want fixed pricing, fast turnaround, and someone who speaks plain English.
---
## Three Discovery Layers
### Layer 1: Human Buyers via Forums & Search
People actively searching for answers to compliance questions on Reddit, Stack Exchange,
Quora, and Google. They have an immediate problem — a DOL audit letter, a CCPA complaint,
a contractor they're not sure how to classify. They need help now.
**How we reach them:** LLM-monitored forum replies, SEO content, Google Ads on
high-intent keywords.
### Layer 2: Referrals
Accountants, bookkeepers, HR consultants, and business attorneys who don't do compliance
work themselves but whose clients ask about it. They refer to us because we don't compete
with them — we do the procedural filings they don't want to touch.
**How we reach them:** Referral partnership program, co-branded content, direct outreach
to accounting firms and HR consultancies.
### Layer 3: Free Tools
People who aren't ready to buy but want to self-assess. They take the Contractor
Classification Quiz, Privacy Policy Check, or TCPA SMS Check. We capture their email,
nurture with educational content, and convert when they realize they need professional help.
**How we reach them:** SEO-optimized tool pages, social media promotion, forum mentions
when someone is exploring/unsure.
### Layer 4: AI Agent Discovery (MCP Server)
AI assistants (Claude, ChatGPT, Cursor) can discover and transact with Performance West
via our MCP server. When a user asks an AI agent about business formation, telecom
compliance, or CRTC registration, the agent can walk them through a formation questionnaire
and place orders directly.
**How we reach them:** Install: `npx @performancewest/mcp-server`. Submit to Smithery,
mcp.so, and Glama directories. The MCP server exposes tools for service lookup, formation
questionnaire, order creation, and order status.
---
## Target Buyer Personas
### Persona 1: The Startup Founder (Corporate + Employment)
- **Age:** 25–40
- **Business:** Pre-revenue to $2M ARR, 1–20 employees
- **Pain points:** Picked the wrong entity type, hiring first employees, confused about
contractor vs employee, no HR policies
- **Services:** Business Formation, Contractor Classification Review, Employee Handbook
- **Where they hang out:** r/startups, r/Entrepreneur, r/smallbusiness, Hacker News,
Twitter/X, Indie Hackers
### Persona 2: The E-commerce Operator (Privacy + TCPA)
- **Age:** 25–45
- **Business:** $500K–$10M revenue, sells online, collects customer data
- **Pain points:** CCPA notices from customers, SMS marketing compliance, privacy policy
is copy-pasted from another site
- **Services:** CCPA Compliance Audit, Privacy Policy Review, SMS Consent Audit,
Marketing Campaign Review
- **Where they hang out:** r/ecommerce, r/marketing, Shopify Community, Twitter/X
### Persona 3: The Small Business Owner (Employment + Corporate)
- **Age:** 35–60
- **Business:** $1M–$20M revenue, 10–200 employees, brick-and-mortar or service business
- **Pain points:** Got a DOL audit letter, worried about overtime classification, employee
handbook is outdated, expanding to new states
- **Services:** FLSA Audit, Employee Handbook Review, State Registrations, Annual Reports
- **Where they hang out:** r/smallbusiness, Alignable, local business groups, LinkedIn
### Persona 4: The Telecom Operator (Telecom Compliance)
- **Age:** 30–55
- **Business:** CLEC, VoIP provider, ISP, IPES, or reseller
- **Pain points:** FCC filings, STIR/SHAKEN deadlines, state PUC registrations, NECA/LERG
- **Services:** FCC 499-A Filing, STIR/SHAKEN, IPES Registration, Telecom DB Management
- **Where they hang out:** DSLReports, r/telecom, r/voip, industry conferences, LinkedIn
### Persona 5: The Marketing Agency (TCPA)
- **Age:** 28–50
- **Business:** Digital marketing agency running SMS/call campaigns for clients
- **Pain points:** TCPA liability, one-to-one consent rules, DNC compliance, client campaigns
- **Services:** SMS/Call Consent Audit, DNC Review, Marketing Campaign Review
- **Where they hang out:** r/marketing, r/digitalmarketing, LinkedIn, marketing Slack groups
### Persona 6: The Accountant/Bookkeeper (Referral Partner)
- **Age:** 30–60
- **Business:** CPA firm or bookkeeping practice with SMB clients
- **Pain points:** Clients ask them compliance questions they can't answer
- **Services:** Refers clients to us; we refer tax questions back to them
- **Where they hang out:** r/accounting, r/tax, LinkedIn, AICPA communities
### Persona 7: The International Telecom Carrier
- **Age:** 30–55
- **Business:** VoIP operator, ITSP, or wholesale carrier wanting to operate internationally
- **Pain points:** FCC Section 214 authorization costs ($58K–$525K+), CALEA wiretap
compliance, FBI background checks, Team Telecom review delays (12–18 months),
STIR/SHAKEN requirements. US carrier licensing is prohibitively expensive and slow
for small operators.
- **Services:** Canada CRTC Carrier Package ($3,899) — BC corporation, CRTC registration
letter, BITS registration, CCTS membership, Canadian DID, .ca domain, corporate binder
- **Why Canada:** CRTC registration is notification-based (no approval needed), no background
checks, no CALEA equivalent, fraction of the cost of US FCC licensing. Canadian carriers
can interconnect with US networks via international trunking.
- **Where they hang out:** r/telecom, r/VoIP, DSLReports, telecom trade forums,
LinkedIn telecom groups, WhatsApp carrier groups
---
## SEO Keywords by Category
### Telecom Compliance
- FCC Form 499-A filing service
- STIR/SHAKEN implementation help
- IPES registration FCC
- ISP registration requirements
- state PUC registration telecom
- NECA membership application
- telecom compliance consultant
- FCC CORES registration help
### Canada CRTC / International Telecom
- CRTC carrier registration
- Canadian telecom carrier
- BC corporation telecom
- BITS registration Canada
- alternative to FCC 214
- Canadian carrier vs US carrier
- CRTC reseller registration
- Canada telecom license cost
- FCC 214 alternative Canada
- international carrier registration cheap
### Employment Compliance
- FLSA compliance audit
- contractor vs employee classification
- 1099 vs W-2 test
- employee handbook compliance review
- DOL wage and hour audit preparation
- exempt vs non-exempt classification
- overtime compliance small business
- independent contractor misclassification risk
### Data Privacy
- CCPA compliance audit small business
- CCPA privacy policy requirements
- California privacy rights compliance
- data mapping CCPA
- privacy policy review service
- breach response plan template
- CPRA compliance checklist
- do not sell my information compliance
### TCPA Compliance
- TCPA consent requirements SMS
- one-to-one consent rule TCPA
- DNC compliance review
- SMS marketing compliance
- TCPA audit service
- telemarketing compliance consultant
- prior express written consent
- TCPA penalty calculator
### Corporate Services
- LLC formation service
- business formation Wyoming
- foreign qualification filing
- annual report filing service
- registered agent service Wyoming
- LLC vs S-Corp vs C-Corp
- multi-state business registration
- EIN application service
---
## Content Marketing Cadence
### Weekly (every Monday)
- 1 blog post (800–1,200 words) targeting a long-tail SEO keyword
- Rotate through categories: Telecom → Employment → Privacy → TCPA → Corporate
- Each post ends with a CTA to the relevant free tool or service page
### Bi-weekly (every other Wednesday)
- 1 Reddit/forum educational post (150–300 words) in a target subreddit
- Helpful, non-promotional, signed "-- Justin"
- Subtle mention of Performance West or free tool where natural
### Monthly
- 1 in-depth guide or checklist (2,000–3,000 words) — gated behind email capture
- 1 email newsletter to captured leads — compliance news, tips, new tool announcements
- Review and update product-facts.md with any service changes
### Quarterly
- Refresh free tool content and scoring logic
- Analyze forum monitoring performance (replies sent, clicks, conversions)
- Update keyword targets based on Search Console and forum trending topics
---
## Community Presence Strategy
### Principles
1. **Be helpful first.** Every forum interaction must provide genuine value before any mention
of Performance West. If the post doesn't naturally connect to our services, don't force it.
2. **Build reputation over time.** Consistent, knowledgeable answers build trust. One spammy
post destroys months of goodwill.
3. **Respect community norms.** Read the rules of every subreddit and forum before posting.
Some ban self-promotion entirely — in those, only answer questions helpfully.
4. **Use personal voice.** Posts come from Justin, a real person, not "Performance West Inc."
People trust people, not brands.
### Execution
- Maintain active Reddit accounts with genuine comment history
- Participate in threads even when there's no service to promote
- Upvote and engage with other helpful answers
- Share the free tools as resources, not sales pitches
- Never argue with people who disagree — thank them and move on
---
## Free Tool Traffic Flywheel
The free tools (Contractor Quiz, Privacy Check, TCPA Check) serve as the engine of a
self-reinforcing growth loop:
```
Forum post mentions free tool
↓
User visits tool page (organic traffic)
↓
User completes assessment (engagement)
↓
Tool shows risk score + recommendation (value delivery)
↓
User enters email to get detailed report (lead capture)
↓
Email nurture sequence educates over 7 days
↓
User books consultation or purchases service (conversion)
↓
Satisfied client refers others / leaves review (amplification)
↓
Reviews + backlinks improve SEO rankings
↓
More organic traffic to tool pages
↓
Cycle repeats
```
### Why This Works
1. **Low friction:** Free tools require no commitment — just answer a few questions
2. **Immediate value:** Users get a risk assessment instantly, before we ask for anything
3. **Self-qualifying:** High-risk scores indicate buyers; low-risk scores filter out non-buyers
4. **SEO compounding:** Tool pages attract backlinks from forums, blogs, and other sites
5. **Forum-native:** Mentioning "here's a free quiz to check" is genuinely helpful, not salesy
6. **Data collection:** Aggregate quiz results reveal which compliance areas have the most demand
### Metrics to Track
- Tool page visits (by source: organic, forum, direct, referral)
- Assessment completion rate
- Email capture rate
- Email → consultation conversion rate
- Consultation → purchase conversion rate
- Average time from first tool visit to purchase
- Which tool drives the most revenue
---
## Service Bundles (Pricing/Marketing)
### Formation Bundles
| Bundle | Includes | Price |
|--------|----------|-------|
| **Wyoming LLC Starter** | Formation + RA + Operating Agreement + EIN | $599 |
| **Wyoming LLC Complete** | Starter + Annual Report + Compliance Calendar | $849 |
| **Multi-State Bundle** | Formation in 2 states + Foreign Qualification | $1,199 |
### Telecom Bundles
| Bundle | Includes | Price |
|--------|----------|-------|
| **CLEC Starter** | FCC 499-A + CORES + 1 State PUC | $2,499 |
| **VoIP Complete** | CLEC Starter + STIR/SHAKEN + IPES | $4,999 |
| **Canada CRTC Carrier Package** | BC Corp + CRTC Letter + BITS + CCTS + DID + .ca Domain + Corporate Binder | $3,899 |
### Compliance Bundles
| Bundle | Includes | Price |
|--------|----------|-------|
| **Privacy Starter** | Privacy Policy + Cookie Consent + Data Map | $1,499 |
| **Employment Starter** | Handbook Review + FLSA Audit + Contractor Assessment | $2,499 |
| **Full Compliance** | Privacy + Employment + TCPA Audit | $4,999 |
Bundles are priced at 15-20% discount vs. individual services to incentivize larger purchases.
---
## Production Notes
- **Employment pages are hidden in production.** The `/employment` and `/careers` routes
are excluded from the sitemap and have `noindex` meta tags. These pages exist for
internal reference only and should not be indexed or linked publicly.

204
docs/marketing/distribution-channels.md Normal file
View file

@ -0,0 +1,204 @@
# Performance West — Distribution Channels
**Last updated:** 2026-03-27
Based on 2025-2026 research into where business owners, accountants, bookkeepers,
and HR professionals actually discuss compliance topics online.
---
## TIER 1 — Automated + Highest ROI
### Reddit (Automated LLM Monitor)
| Subreddit | Members | Compliance Topics | Why It Works |
|-----------|---------|-------------------|-------------|
| r/tax | 841K | 1099 vs W-2, misclassification, IRS compliance | Highest-relevance sub. Nearly every post is on-topic. |
| r/smallbusiness | 470K | Contractor classification, LLC, privacy policy, TCPA | Business owners asking for help directly. |
| r/Entrepreneur | 470K | Formation, contractor, privacy questions | Founders making compliance decisions. |
| r/legaladvice | 1.6M | Misclassification, wage theft, FLSA | Employee-side posts show employers the risk. |
| r/Bookkeeping | 75K | 1099 processing, payroll compliance, QBO/Xero | Bookkeepers who refer clients. Strict rules. |
| r/accounting | 1.23M | Contractor classification, payroll tax | Accountants who encounter compliance daily. |
| r/humanresources | 107K | FLSA, handbooks, discrimination, HR policies | HR professionals. Direct compliance Q&A. |
| r/QuickBooks | 37K | Payroll/1099 compliance in QuickBooks context | QB users hit compliance issues in software. |
| r/IRS | 442K | Enforcement notices, compliance questions | Tax compliance and notices. |
| r/antiwork | 1.6M | Misclassification, wage theft (massive engagement) | Shows employer risk. Educational replies. |
| r/EmploymentLaw | 7.1K | 100% compliance questions. Every post is relevant. | Small but highest signal-to-noise ratio. |
| r/ecommerce | 91K | CCPA, privacy, SMS marketing | E-commerce compliance pain points. |
| r/marketing | 141K | TCPA, SMS consent, DNC | Marketers hitting TCPA issues. |
| r/construction | — | Contractor misclassification (#1 industry) | Construction is ground zero for 1099 issues. |
| r/restaurateur | — | Wage-hour violations (tip credit, overtime) | Restaurants are the highest-risk industry. |
| r/realestateinvesting | — | Contractor classification, entity formation | RE investors use 1099 workers extensively. |
| r/freelance | — | Other side of contractor misclassification | Freelancers asking "am I misclassified?" |
| r/startups | 1.2M | Formation, early compliance | Startups making first compliance decisions. |
| r/payroll | ~10K | Payroll tax compliance, classification | Focused payroll compliance community. |
**Automation:** reddit-monitor.py (Ollama qwen2.5:3b, 3 replies/run, 10/day max)
### Google Search (SEO)
| Approach | Target Keywords | Expected ROI |
|----------|----------------|-------------|
| Service pages | "contractor classification review", "CCPA compliance audit" | Very High |
| Free tool pages | "1099 vs W-2 quiz", "TCPA compliance checker" | Very High (compounds) |
| Blog content | Long-tail compliance questions | High (compounds over 6+ months) |
### AI Agent Discovery — MCP Server
| Approach | Integration | Expected ROI |
|----------|-------------|-------------|
| MCP Server | Install: `npx @performancewest/mcp-server` | Very High — zero-friction AI-assisted sales |
| AI assistants (Claude, ChatGPT, Cursor) can walk users through formation questionnaire and place orders | Submit to Smithery, mcp.so, Glama directories | Compounds as AI adoption grows |
The MCP server exposes tools for service lookup, formation questionnaire, order creation,
and order status. AI agents discover our services when users ask about business formation,
telecom compliance, or CRTC registration.
### Free Tools (Owned Traffic Flywheel)
| Tool | SEO Keywords | Conversion Path |
|------|-------------|----------------|
| Contractor Classification Quiz | "1099 vs W-2 test", "am I misclassifying" | High risk result → $499 review CTA |
| Privacy Policy Check | "CCPA compliance checker" | Gaps found → $799 policy review CTA |
| TCPA SMS Check | "SMS compliance audit" | High risk → $1,299 consent audit CTA |
| Formation Guide | "LLC formation questionnaire", "which state to form LLC" | Completed guide → formation order CTA |
---
## TIER 2 — Manual Engagement, High ROI
### Facebook Groups (Manual — Create Your Own + Participate in Others)
| Group Strategy | Size/Reach | Compliance Topics | Notes |
|---------------|-----------|-------------------|-------|
| **Create own group** ("Small Business HR Compliance") | Build to 5K+ | All categories | Full control. Schedule posts. Capture emails via join questions. |
| QuickBooks Users & Proadvisors | ~50K | 1099, payroll, compliance | Answer questions. Build reputation. |
| Bookkeepers' Corner | ~30K | 1099 processing, contractor classification | Bookkeepers who refer clients. |
| Restaurant Owners groups | 30-50K | Tip credit, wage-hour, FLSA | Highest-risk industry for wage violations. |
| Cleaning Business Owners | ~50K | 1099 misclassification | Many misclassify cleaners as contractors. |
| Construction Business Owners | 20-40K | Subcontractor vs employee classification | Ground zero for misclassification. |
| HR for Small Business | 15-30K | FLSA, handbooks, policies | Direct target audience. |
| Women Entrepreneurs groups | 100-300K+ | Broad compliance | Active engagement on hiring/compliance. |
**No automation possible.** Budget 30-60 min/day for manual engagement.
### QuickBooks Community (1.6M members, 1.3M posts)
- Answer 1099/payroll/contractor compliance questions
- Cannot promote externally — Intuit removes links
- Build reputation as helpful expert
- High volume of compliance questions daily
### Intuit Accountants Community (ProConnect/Lacerte)
- Tax professionals who refer clients
- Active daily discussions on compliance
- Ideal referral partner channel
- Top contributors have 200-450+ posts
### LinkedIn (Personal Brand + Groups)
| Approach | Effort | ROI |
|----------|--------|-----|
| Personal posts from Justin (2-3x/week) | Medium | High — organic reach among decision-makers |
| Comment on compliance discussions | Medium | Medium — builds authority |
| Connect with CPAs, HR consultants, attorneys | Medium | Very High — referral partnerships |
| LinkedIn Groups (HR, SMB, Compliance) | Low | Medium |
### Alignable (9M small business owners)
- Local business social network
- "Legal & Insurance" and "Hiring" topic forums
- Low competition from compliance consultants
- Good for building local authority
### BiggerPockets (3M members)
- Real estate investors
- Active contractor classification, 1099, entity formation discussions
- "Legal & Legislation" and "Tax" forum categories
- Manual answers build authority
---
## TIER 3 — Niche, Lower Volume
### ContractorTalk (170K members, 3.6M posts)
- Construction industry professionals
- "Business" section: 155K threads, 50M views
- Worker classification, insurance, licensing
- Has sponsor programs for paid visibility
### Industry-Specific Forums
| Forum | Industry | Key Compliance Topics |
|-------|----------|---------------------|
| RestaurantOwner.com | Restaurant | Tip credit, overtime, youth employment, FLSA |
| LawnSite.com | Landscaping | H-2B visa, seasonal workers, classification |
| TruckersReport.com | Trucking | IC rules, ABC test, ELD compliance |
| DentalTown | Medical/Dental | Employment law for small practices |
### Canada CRTC / International Telecom Channels
| Channel | Audience | Approach |
|---------|----------|----------|
| r/telecom | Telecom professionals | Educational posts about CRTC vs FCC carrier licensing |
| r/VoIP | VoIP operators and enthusiasts | Answer questions about carrier licensing, mention Canada alternative |
| DSLReports Telecom Forum | ISPs, CLECs, telecom operators | Long-form educational posts about CRTC registration |
| Telecom trade forums | Industry professionals | Participate in FCC 214 and carrier licensing discussions |
| LinkedIn telecom groups | Decision-makers at telcos | Share thought leadership on international carrier strategies |
| WhatsApp carrier groups | Wholesale voice/SMS traders | Direct outreach when relevant |
**Key message:** "Canadian CRTC registration is notification-based at a fraction of FCC 214
cost ($3,899 vs $58K–$525K+). No background checks, no CALEA, no Team Telecom delays."
### Quora (400M monthly visitors)
- Answer compliance questions
- Answers rank in Google (long-tail SEO)
- Lower volume than Reddit but longer shelf life
### Referral Partnerships (Relationship-Based)
| Partner Type | Where to Find | What They Refer |
|-------------|---------------|----------------|
| CPA / Accounting firms | LinkedIn, Intuit communities | Contractor classification, corporate filings |
| HR Consultants | LinkedIn, r/humanresources | FLSA audits, handbook reviews |
| Business Attorneys | LinkedIn | Compliance filings they don't want to do |
| Bookkeepers | Alignable, Facebook groups | State registrations, annual reports |
| Payroll Companies | Direct outreach | Contractor classification, employment compliance |
### Email Marketing (Owned Channel)
| Approach | Source | Expected ROI |
|----------|--------|-------------|
| Free tool → email capture → nurture sequence | Website tools | Very High |
| Monthly compliance newsletter | Mailing list subscribers | High |
| Triggered sequences by compliance category | Segmented leads | High |
---
## SKIP / NOT RECOMMENDED
| Channel | Reason |
|---------|--------|
| **Stack Exchange** | Wrong audience (developers/academics, not business owners). Dropped. |
| **dev.to** | Developer audience. Business owners don't read dev.to. Dropped. |
| **Hacker News** | No write API. Tech audience. Cannot automate. |
| **Discord** | No scalable monitoring. Manual participation not worth effort. |
| **Twitter/X** | API pricing prohibitive. Organic reach collapsed. |
| **TikTok / Instagram** | Wrong format for compliance consulting. |
| **Cold Email / Cold Calling** | Legal risk, reputation risk, low conversion. Never. |
| **Print / Trade Publications** | Cost-prohibitive for our price points. |
---
## Channel Priority Timeline
| Priority | Channels | When | Monthly Cost |
|----------|----------|------|-------------|
| **P0 — Month 1** | Reddit monitor (automated), Free tools (built), SEO (service pages) | Immediately | $0 |
| **P1 — Month 1-2** | Own Facebook Group, LinkedIn personal posts, Email nurture | Week 2+ | $0 |
| **P2 — Month 2-3** | QB Community, Intuit Accountants, Alignable, Facebook group participation | Month 2 | $0 |
| **P3 — Month 3+** | BiggerPockets, ContractorTalk, Quora, Referral partner outreach | Month 3+ | $0 |
| **P4 — Month 4+** | Google Ads (test budget), Industry forums, Podcast guesting | Month 4+ | $500-1K |
---
## Key Metrics
| Channel | Primary Metric | Target |
|---------|---------------|--------|
| Reddit | Clicks to site (UTM) | 50/week by month 3 |
| Free Tools | Assessment completions | 100/month, 40% email capture |
| Google Organic | Sessions to service/tool pages | 500/month by month 6 |
| Facebook Group | Members + engagement | 1K members by month 6 |
| QB Community | Answers posted + profile views | 10 answers/week |
| LinkedIn | Post impressions + connections | 10 new partner connections/quarter |
| Email | Open rate, click rate | 35% open, 5% click |
| Referrals | Referred leads | 5/month by month 6 |

207
docs/marketing/forum-monitor-plan.md Normal file
View file

@ -0,0 +1,207 @@
# Performance West — Forum Monitor Plan
**Last updated:** 2026-03-27
## Verdict: Reddit-Only Automated Monitor + Manual Engagement Elsewhere
After researching all platforms where business owners discuss compliance topics in
2025-2026, the conclusion is clear:
- **Reddit** is the only platform with API access for automated monitoring and posting
- **Every other platform** (Facebook Groups, QuickBooks Community, Alignable, BiggerPockets,
ContractorTalk, LinkedIn, Quora) prohibits automated posting and requires manual engagement
- **Stack Exchange and dev.to were dropped** — wrong audience for compliance consulting
(developers, not business owners)
---
## Compliance Topic Popularity (Ranked by 2025-2026 Discussion Volume)
| Rank | Topic | Est. Reddit Posts/Year | Key Platforms |
|------|-------|----------------------|---------------|
| 1 | **Contractor Misclassification / 1099 vs W-2** | 50+ | r/tax, r/legaladvice, r/antiwork, r/smallbusiness, r/Bookkeeping, QuickBooks Community |
| 2 | **LLC Formation / Corporate Registrations** | 25-35 | r/smallbusiness, r/Entrepreneur |
| 3 | **FLSA / Wage & Hour / Overtime** | 15-20 | r/humanresources, r/EmploymentLaw, r/legaladvice, r/antiwork |
| 4 | **Employee Handbooks / HR Policies** | 10-15 | r/humanresources, r/EmploymentLaw |
| 5 | **CCPA / Privacy Policies** | 15-25 | r/Entrepreneur, r/ecommerce, r/privacy |
| 6 | **TCPA / SMS Marketing Consent** | 10-15 | r/ecommerce, r/marketing |
| 7 | **Telecom / FCC / STIR/SHAKEN** | 3-5 | r/telecom, r/VoIP (very niche) |
**Key insight:** Contractor misclassification is the undisputed #1 compliance pain point.
It appears on every platform, from workers asking "am I misclassified?" to employers
asking "can I pay someone as a 1099?" to bookkeepers asking "how do I file 1099s correctly?"
---
## Build 1 — Reddit Monitor (Automated, Highest ROI)
### Target Subreddits (19 total, in priority order)
**TIER 1 — Highest volume, business owners asking compliance questions:**
| Subreddit | Members | Why |
|-----------|---------|-----|
| r/smallbusiness | 470K | Constant contractor/LLC/compliance posts from owners |
| r/Entrepreneur | 470K | Formation, contractor, privacy questions from founders |
| r/tax | 841K | 1099 vs W-2 questions daily. Virtually 100% relevant |
| r/legaladvice | 1.6M | Employee-side misclassification posts showing employer risk |
**TIER 2 — Professionals who refer clients + direct compliance Q&A:**
| Subreddit | Members | Why |
|-----------|---------|-----|
| r/Bookkeeping | 75K | 1099 processing, payroll compliance, QBO/Xero. Strict rules |
| r/accounting | 1.23M | Broad but huge. Contractor classification threads |
| r/humanresources | 107K | FLSA, handbooks, discrimination, HR policies |
| r/QuickBooks | 37K | Payroll/1099 compliance in QuickBooks context |
| r/IRS | 442K | Enforcement notices, compliance questions |
**TIER 3 — Industry-specific (highest misclassification/wage-hour risk):**
| Subreddit | Members | Why |
|-----------|---------|-----|
| r/ecommerce | 91K | CCPA, privacy policies, SMS marketing compliance |
| r/marketing | 141K | TCPA, SMS consent, DNC list |
| r/realestateinvesting | — | Contractor classification, entity formation |
| r/restaurateur | — | Wage-hour violations (huge in food service) |
| r/construction | — | Contractor misclassification (#1 violating industry) |
| r/antiwork | 1.6M | Misclassification/wage theft posts get massive engagement |
| r/EmploymentLaw | 7.1K | Small but 100% signal — every post is a compliance question |
| r/freelance | — | The "other side" of contractor misclassification |
| r/startups | 1.2M | Business formation, early compliance |
| r/payroll | ~10K | Payroll tax compliance, misclassification |
### Keyword Triggers
```python
COMPLIANCE_KEYWORDS = {
"flsa": ["FLSA", "wage and hour", "overtime violation", "exempt vs nonexempt",
"minimum wage", "off the clock", "meal break violation",
"unpaid overtime", "salary threshold", "wage theft",
"DOL audit", "Department of Labor"],
"misclassification": ["1099 vs W-2", "1099 vs W2", "independent contractor",
"misclassification", "misclassified", "contractor or employee",
"IC vs employee", "gig worker classification",
"pay contractor", "paying 1099", "1099 worker",
"contractor to employee", "should I 1099"],
"discrimination": ["workplace discrimination", "harassment policy", "Title VII",
"ADA compliance", "hostile work environment", "DEI policy",
"pay equity", "retaliation claim", "EEOC"],
"privacy": ["CCPA", "CPRA", "privacy policy", "data privacy", "opt-out request",
"cookie consent", "data breach notification", "biometric data",
"privacy compliance", "do not sell", "consumer rights request"],
"tcpa": ["TCPA", "robocall", "SMS marketing", "text message consent",
"do not call", "DNC list", "autodialer",
"prior express written consent", "one-to-one consent",
"SMS campaign sued", "text marketing compliance"],
"corporate": ["LLC formation", "form an LLC", "register a business",
"annual report filing", "registered agent", "foreign qualification",
"state registration", "business formation", "incorporate",
"S-Corp election", "C-Corp vs S-Corp", "EIN",
"operating agreement", "good standing"],
"telecom": ["FCC 499A", "STIR/SHAKEN", "telecom compliance",
"IPES registration", "ISP registration", "robocall attestation",
"FCC registration", "CLEC", "telecom license"],
"crtc": ["CRTC registration", "Canadian carrier", "BITS registration",
"Canadian telecom", "BC corporation telecom", "alternative to 214",
"FCC 214 alternative", "Canada CRTC", "CRTC reseller"],
"payroll": ["payroll compliance", "payroll tax", "W-4", "Form 941",
"employer taxes", "FUTA", "SUTA", "withholding",
"QuickBooks payroll", "Xero payroll", "payroll setup"],
}
```
### Rate Limits
- Max 3 replies per run, max 1 per subreddit
- 5-15 min pause between replies
- Daily limit: 10 replies
- Max post age: 7 days
- Shuffle subreddit order each run
### Subreddit-Specific Rules
- **r/Bookkeeping**: Rule 6 permanently bans AI discussion. Be extra careful.
- **r/tax**: No soliciting (Rule 2), no linking business content (Rule 3)
- **r/smallbusiness**: No blog links/SEO (Rule 2), no promotion (Rule 3)
- **r/legaladvice**: Reply as "compliance perspective" not legal advice
- **r/antiwork**: Audience is employees; frame replies showing employer risk
- **r/taxpros**: RESTRICTED — cannot post without approval. Skip for now.
---
## Manual Engagement Channels (No Automation Possible)
### Priority 1 — Create Your Own Facebook Group
Create "Small Business HR & Compliance Tips" or similar. Full control over:
- Scheduling posts (Hootsuite / Meta Business Suite)
- Email capture via join questions
- Content calendar
- No competition from other consultants
- 1.8B monthly Facebook Group users
### Priority 2 — QuickBooks Community (1.6M members)
Answer 1099/payroll/contractor questions. Establish expertise.
Cannot promote directly — Intuit removes external links.
Build reputation as a helpful expert.
### Priority 3 — Intuit Accountants Community (ProConnect)
Tax professionals who directly advise clients on compliance.
These are ideal referral partners. Build relationships.
### Priority 4 — LinkedIn Personal Brand
Post compliance tips 2-3x/week from Justin's personal account.
Comment on HR/compliance discussions. Connect with:
- CPAs and accounting firms (referral partners)
- HR consultants (referral partners)
- Business attorneys (referral partners)
### Priority 5 — Alignable (9M business owners)
Local SMB social network. "Legal & Insurance" and "Hiring" topic forums.
Low competition, high intent. Manual participation.
### Priority 6 — BiggerPockets (3M members)
Real estate investors — active contractor classification and entity
formation discussions. Manual answers in Legal & Tax forums.
### Priority 7 — ContractorTalk (170K, 3.6M posts)
Construction industry. Business forum covers worker classification,
insurance, licensing. Has sponsor programs for paid visibility.
### Priority 8 — Industry Facebook Groups (manual)
Join and participate in:
- Restaurant Owners groups (tip credit, wage-hour)
- Cleaning Business Owners (~50K) (1099 misclassification)
- Construction Business Owners (subcontractor classification)
- QuickBooks Users & Proadvisors (~50K)
- Bookkeepers' Corner (~30K)
### Priority 9 — Quora
Answer compliance questions. Answers rank in Google (long-tail SEO).
Lower volume than Reddit but longer shelf life.
---
## Dropped Channels (With Reasoning)
| Channel | Why Dropped |
|---------|-------------|
| **Stack Exchange** | Wrong audience. SE users are developers/academics, not business owners. The Law/Workplace SEs have compliance questions but strict anti-promotion rules and low volume. |
| **dev.to** | Developer audience. Business owners don't read dev.to articles about CCPA or FLSA. |
| **Hacker News** | No write API. Cannot automate. Tech audience, not SMB owners. |
| **Discord** | No scalable monitoring. Manual participation in dozens of servers not worth it. |
| **Twitter/X** | API pricing prohibitive ($100/mo minimum). Organic reach collapsed. |
| **TikTok / Instagram** | Wrong format for compliance consulting content. |
---
## Metrics
Track weekly:
- Reddit posts scanned vs. keyword matches vs. replies posted
- Click-throughs to performancewest.net (UTM links)
- Free tool completions from Reddit traffic
- Mailing list signups from Reddit traffic
- Quote requests attributed to forum channel
- SKIP reasons logged to capability-gaps.log
Monthly review:
- Best-performing subreddits by click-through rate
- Best-performing keyword triggers
- Reply quality audit (sample 10, score for helpfulness)
- Adjust subreddit priority and keyword triggers

622
docs/marketing/reddit-posts.md Normal file
View file

@ -0,0 +1,622 @@
# Performance West — Pre-Written Reddit Posts
**Last updated:** 2026-03-19
These are educational, helpful posts designed for specific subreddits. Each one provides
genuine value, is 150–300 words, and ends with "-- Justin". Performance West or a free
tool is mentioned only where natural. These are NOT ads — they're the kind of posts that
build reputation over time.
---
## Post 1: r/smallbusiness — Contractor Misclassification Guide
**Title:** The IRS uses a 20-factor test to decide if your "contractor" is actually an employee — here's the short version
If you're paying someone on a 1099 and they work set hours, use your equipment, and only work for you — the IRS and DOL may disagree with your classification. Here's the quick breakdown.
The IRS looks at three categories:
**Behavioral control:** Do you tell them *how* to do the work, not just *what* to do? Do you set their hours? Do you require them to work on-site? The more control you exert, the more it looks like employment.
**Financial control:** Do they invoice multiple clients, or just you? Do they have their own business expenses? Can they make a profit or take a loss? If you're their only income source and they have no business risk, that leans employee.
**Relationship type:** Is there a written contract? Do they get benefits? Is the work a core part of your business? A "contractor" who does the same thing as your employees, indefinitely, is hard to defend.
The penalties for getting this wrong are real: back taxes, penalties, and potentially back-pay for benefits and overtime. Some states (California AB5, Massachusetts, New Jersey) have even stricter tests.
If you want to quickly check where you stand, there's a free contractor classification quiz at performancewest.net/tools/contractor-quiz — 10 yes/no questions, instant risk score, no email required to see results.
The goal isn't to scare you — it's to help you fix it before someone else flags it.
-- Justin
---
## Post 2: r/smallbusiness — CCPA Checklist for Small Businesses
**Title:** If you have customers in California and make over $25M (or handle 100K+ consumers' data), CCPA applies to you — here's the checklist
A lot of small business owners assume CCPA only applies to big tech companies. It doesn't. If you meet any one of these thresholds, you're covered:
- Annual gross revenue over $25 million
- Buy, sell, or share personal info of 100,000+ consumers or households
- Derive 50%+ of revenue from selling personal information
And "personal information" under CCPA is broad — names, emails, IP addresses, purchase history, browsing behavior. If you run an e-commerce store with California customers, you're probably collecting this.
**Quick compliance checklist:**
1. **Privacy policy** — Must specifically disclose CCPA rights, categories of data collected, and whether you sell data
2. **"Do Not Sell" link** — Required on your homepage if you share data with third parties (including ad networks)
3. **Consumer request process** — You need a way for people to request access to or deletion of their data, and you must respond within 45 days
4. **Vendor contracts** — Your data processing agreements with vendors need CCPA-specific language
5. **Employee training** — Anyone handling consumer requests needs to know the process
6. **Recordkeeping** — Track all requests and responses for 24 months
If you want a quick self-assessment, we built a free 8-item privacy compliance check at performancewest.net/tools/privacy-check. Takes 2 minutes.
The fines are $2,500 per unintentional violation and $7,500 per intentional violation — per consumer, per incident.
-- Justin
---
## Post 3: r/Entrepreneur — Business Formation Guide
**Title:** LLC vs C-Corp vs S-Corp — a plain English breakdown for people who just want to pick the right one
I see this question every week, so here's the straightforward version:
**LLC (Limited Liability Company)**
- Best for: Most small businesses, especially service businesses and solo founders
- Tax: Pass-through by default (profits taxed on your personal return)
- Liability: Personal assets protected from business debts
- Paperwork: Minimal. Operating agreement + state filing. No board meetings required.
- Downside: Can't issue stock, so harder to raise VC funding
**C-Corp**
- Best for: Businesses planning to raise venture capital or go public
- Tax: Double taxation — corp pays tax on profits, you pay tax again on dividends
- Liability: Personal assets protected
- Paperwork: Board meetings, minutes, bylaws, stock issuance, annual reports
- Upside: Can issue multiple classes of stock, unlimited shareholders
**S-Corp (not actually an entity type)**
- What it is: A tax election you make with the IRS, applied to an LLC or C-Corp
- Best for: Businesses earning $60K+ in profit where you want to reduce self-employment tax
- How it works: You pay yourself a "reasonable salary" (subject to payroll tax), and take remaining profit as distributions (not subject to SE tax)
- Downside: Must run payroll, file additional tax forms, limited to 100 shareholders
**My suggestion for most people:** Start as an LLC. If/when profits warrant it, elect S-Corp status. Only form a C-Corp if you're raising institutional money.
If you need help with the actual filing, Performance West handles business formation from $179 (basic) or $399 complete with EIN + operating agreement + registered agent ($99/yr). 3-5 business days.
-- Justin
---
## Post 4: r/accounting — 1099 vs W-2 Classification Test
**Title:** Quick reference: how the IRS and DOL actually evaluate 1099 vs W-2 classification (they use different tests)
Something that trips up a lot of business owners — and their accountants: the IRS and DOL use *different tests* to evaluate worker classification, and a worker can pass one test but fail the other.
**IRS Common Law Test (20 factors, grouped into 3 categories):**
- Behavioral control (who decides how, when, where work is done)
- Financial control (who bears expenses, can the worker profit/lose)
- Type of relationship (permanence, benefits, written contract)
No single factor is decisive. It's a totality-of-circumstances analysis.
**DOL Economic Reality Test (6 factors):**
1. Extent to which the work is an integral part of the employer's business
2. Worker's opportunity for profit or loss based on managerial skill
3. Worker's investment relative to the employer's investment
4. Degree of skill and initiative required
5. Permanence of the relationship
6. Nature and degree of the employer's control
The DOL test focuses more on economic dependence. A worker can look like a contractor under IRS rules but an employee under DOL rules — which matters for FLSA (overtime, minimum wage).
**State tests add another layer.** California's ABC test (AB5) presumes employment unless the worker is (A) free from control, (B) performing work outside the usual course of business, and (C) has an independently established trade. Massachusetts and New Jersey have similar strict tests.
If you have clients asking about this, there's a free classification quiz at performancewest.net/tools/contractor-quiz that runs through the key factors in about 2 minutes. Useful for initial risk screening.
-- Justin
---
## Post 5: r/humanresources — Employee Handbook Compliance Checklist
**Title:** Federal and state-required employee handbook policies — the ones that actually get you in trouble if they're missing
I review employee handbooks regularly and the same gaps come up over and over. Here's what's legally required or strongly recommended at the federal level, plus common state requirements people miss:
**Federally required (or effectively required):**
- Equal Employment Opportunity (EEO) statement
- Anti-harassment and anti-discrimination policy (Title VII)
- FMLA leave policy (50+ employees)
- ADA reasonable accommodation process
- FLSA overtime and timekeeping policy
- USERRA military leave rights
- COBRA continuation coverage notice (20+ employees)
- OSHA workplace safety
**Commonly required by states (check yours):**
- Paid sick leave policy (CA, NY, WA, CO, and 15+ other states)
- Meal and rest break policy (CA is especially strict)
- Lactation accommodation policy
- Jury duty leave
- Voting leave
- Crime victim/witness leave
- State-specific anti-discrimination categories (sexual orientation, gender identity, political affiliation)
- Pay transparency requirements (CO, CA, WA, NY)
- Social media privacy protections
**The ones that cause the most problems when missing:**
1. At-will employment disclaimer — without it, employees argue they have an implied contract
2. Overtime policy — if your policy doesn't match FLSA requirements, you're exposed
3. Anti-harassment reporting procedure — a policy without a reporting mechanism doesn't protect you
4. Paid sick leave — states are adding this rapidly and the rules vary widely
If your handbook hasn't been reviewed in the last 2 years, it's probably out of date. Performance West does handbook compliance reviews for $999 flat, covering all states where you have employees, with a 5–7 business day turnaround.
-- Justin
---
## Post 6: r/ecommerce — CCPA Compliance for Online Stores
**Title:** Running an online store with California customers? Here's what CCPA actually requires you to do
If you sell to California residents and meet any CCPA threshold (over $25M revenue, 100K+ consumer records, or 50%+ revenue from selling data), this applies to you. But even below those thresholds, complying is smart risk management.
**What most e-commerce stores get wrong:**
1. **"We don't sell data"** — Under CCPA, sharing data with ad platforms (Google Analytics, Meta Pixel, TikTok Pixel) can constitute "selling" or "sharing" personal information. If you run retargeting ads, you're probably sharing data.
2. **Privacy policy is generic** — CCPA requires specific disclosures: categories of PI collected, purposes, categories of third parties, consumer rights. A template privacy policy from 2019 doesn't cut it.
3. **No "Do Not Sell" link** — Required on your homepage. Not buried in your footer privacy policy. An actual link or button.
4. **No consumer request process** — Consumers can request to know what data you have, delete it, or opt out of sale/sharing. You need a process and must respond within 45 days.
5. **Vendor contracts** — Your payment processor, email platform, analytics tools — all need data processing agreements with CCPA language.
**What to do right now:**
- Run through the free privacy compliance check at performancewest.net/tools/privacy-check
- Update your privacy policy with CCPA-specific language
- Add a "Do Not Sell or Share My Personal Information" link to your homepage
- Review your vendor contracts
CCPA fines are $2,500–$7,500 per violation, per consumer. For an e-commerce store with thousands of California customers, that adds up fast.
-- Justin
---
## Post 7: r/marketing — TCPA Consent Requirements for SMS Campaigns
**Title:** If you're running SMS marketing campaigns, here's what TCPA actually requires for consent (it changed in 2025)
The FCC's one-to-one consent rule went into effect January 2025 and it fundamentally changed how SMS marketing consent works. A lot of marketers are still running campaigns under the old rules. Here's what you need to know:
**Before (old rule):**
- Consumer fills out a lead form
- Lead form has a consent disclosure that lists multiple companies
- One consent = permission for all listed companies to text/call
- Lead generators could sell one lead to dozens of buyers
**Now (one-to-one consent rule):**
- Consent must be given to ONE specific seller at a time
- No more blanket consent covering multiple companies
- The consumer must clearly know exactly who will be contacting them
- Lead generators must get separate consent for each buyer
**What this means for your campaigns:**
1. **Lead gen forms** — If you buy leads, make sure the consent was given specifically to YOUR company, not a list of 30 companies
2. **Consent language** — Must identify your company by name, describe the type of messages, and explain how to opt out
3. **Record retention** — Keep proof of consent (timestamp, IP, exact language shown, what they agreed to)
4. **Opt-out** — Must be honored within a reasonable time. STOP, UNSUBSCRIBE, CANCEL must all work.
**Penalties:** $500–$1,500 per unsolicited text. Class actions routinely settle for millions.
If you want to check whether your current SMS program is compliant, there's a free TCPA compliance check at performancewest.net/tools/tcpa-check — 8 questions, takes about 2 minutes, includes a penalty exposure calculator.
-- Justin
---
## Post 8: r/marketing — The One-to-One Consent Rule Explained
**Title:** The FCC's "one-to-one consent" rule killed the bulk lead gen model — here's what replaced it
If your agency buys leads from aggregators and uses them for SMS or calling campaigns, this is important. The FCC's one-to-one consent rule (effective January 27, 2025) changed the consent standard for telemarketing.
**The old model (RIP):**
A consumer fills out a form on a comparison shopping site. The fine print says "By submitting, you agree to be contacted by Company A, Company B, Company C, and their partners." One form submission → consent for dozens of companies to call and text.
**The new model:**
Consent must be "given to only one identified seller at a time." The consumer must know exactly which company will contact them and must agree to each one individually.
**Practically, this means:**
- **Lead forms** must present each company separately and get individual consent
- **Comparison sites** can still collect leads but must get one-to-one consent per buyer
- **"And their partners"** language no longer provides valid consent
- **Existing leads** obtained under the old blanket-consent model are no longer valid for new outreach after January 2025
**What to audit right now:**
1. Where are your leads coming from? Ask your lead gen vendors exactly how consent is obtained.
2. Can you produce proof of one-to-one consent for every lead? (Timestamp, IP, exact form language, specific company named.)
3. Does your consent language identify your company by name?
4. Are you still using leads from before January 2025 that were obtained via blanket consent?
If you're not sure whether your campaigns comply, Performance West does marketing campaign compliance reviews for $599 per campaign — 2–3 business day turnaround, covers consent, content, opt-out, timing, and disclosure.
-- Justin
---
## Post 9: r/tax — Contractor Misclassification Tax Implications
**Title:** The actual financial cost of misclassifying an employee as a 1099 contractor — it's worse than most people think
I see a lot of discussion about 1099 vs W-2, but rarely does anyone break down what it actually costs when the IRS or a state reclassifies your contractor as an employee. Here's the math:
**Federal exposure (IRS):**
- 100% of the employee's share of FICA (6.2% SS + 1.45% Medicare) that you should have withheld
- Your share of FICA (6.2% + 1.45%) that you should have paid
- Federal income tax you should have withheld (estimated at 25% for most workers)
- Penalties: 1.5% of wages for failure to withhold income tax + 20% of FICA not withheld
- Interest on all of the above from the date it was originally due
**For a contractor paid $80,000/year, reclassified for 3 years:**
- FICA (both shares): ~$18,360
- Estimated income tax withholding: ~$60,000
- Penalties: ~$15,000+
- Interest: ~$5,000+
- **Total exposure: ~$98,000+** for ONE worker over 3 years
**State exposure (varies, but often includes):**
- State income tax withholding + penalties
- State unemployment insurance (retroactive)
- Workers' compensation premiums (retroactive) + penalties for no coverage
- State-specific misclassification fines ($5K–$25K per worker in some states)
**And it gets worse:**
- Reclassified employees may be entitled to retroactive overtime under FLSA
- They may be entitled to benefits (health insurance, 401k match, PTO)
- Other workers in the same role get reclassified too — it's never just one person
If you have contractors and want a quick gut-check, there's a free classification quiz at performancewest.net/tools/contractor-quiz. Takes 2 minutes and tells you where your risk is.
-- Justin
---
## Post 10: r/startups — Compliance Checklist for New Businesses
**Title:** Compliance checklist for startups — the stuff nobody tells you about until you get fined for it
You formed your LLC, got your EIN, opened a bank account. Congratulations. Here's everything else nobody mentioned:
**Entity & Corporate:**
- [ ] Operating agreement (even for a single-member LLC — protects your liability shield)
- [ ] Foreign qualification in every state where you have employees, an office, or significant sales
- [ ] Annual report filings (most states require these, due dates vary, miss it and you lose good standing)
- [ ] Business licenses (city, county, and state — varies by location and industry)
**Employment (once you hire anyone):**
- [ ] Determine if they're actually a W-2 employee or a legitimate 1099 contractor
- [ ] Register for state unemployment insurance
- [ ] Get workers' compensation insurance (required in almost every state)
- [ ] Set up payroll and withhold federal/state taxes
- [ ] I-9 verification for every employee (within 3 days of hire)
- [ ] Post required workplace posters (federal + state)
- [ ] Create an employee handbook covering required policies
**Privacy (if you collect customer data — you probably do):**
- [ ] Privacy policy on your website (required by law in most states + CCPA if CA customers)
- [ ] Cookie consent banner (if you use analytics or advertising pixels)
- [ ] Data processing agreements with vendors who handle your customer data
- [ ] Process for handling consumer data requests
**Marketing (if you send emails, texts, or make calls):**
- [ ] CAN-SPAM compliance for emails (unsubscribe link, physical address, honest subject lines)
- [ ] TCPA consent for any SMS or phone marketing
- [ ] DNC list scrubbing if you do outbound calling
This is not legal advice — it's a compliance consulting checklist. If you want help with any of this, Performance West handles all of these as fixed-price services. Check out performancewest.net for specific pricing and turnaround times.
-- Justin
---
## Post 11: r/smallbusiness — When to Worry About TCPA
**Title:** If your business sends promotional text messages, you need to know about TCPA before it costs you $500–$1,500 per text
I'm seeing more and more small businesses get hit with TCPA demand letters, so here's the quick version of what you need to know:
**TCPA (Telephone Consumer Protection Act) applies if you:**
- Send promotional text messages to customers or prospects
- Make marketing calls using an autodialer or prerecorded voice
- Send faxes (yes, this still happens and yes, it's still regulated)
**What you need:**
1. **Prior express written consent** for marketing texts/calls — this means the person specifically agreed to receive messages from you, in writing (digital is fine), with a clear disclosure
2. **Opt-out mechanism** — every message must include a way to stop. STOP must work.
3. **Time restrictions** — no texts or calls before 8 AM or after 9 PM in the recipient's time zone
4. **Identification** — messages must identify who's sending them
**What gets businesses in trouble:**
- Texting people who filled out a contact form (that's not consent for marketing texts)
- Buying a phone list and blasting it
- Not honoring opt-outs quickly enough
- Texting people at 6 AM because your system uses your time zone, not theirs
- Using a platform that auto-sends without proper consent documentation
**The cost:** $500 per violation (per text). $1,500 per willful violation. Class actions are common. A 1,000-person text blast without proper consent = $500K–$1.5M exposure.
Free compliance check: performancewest.net/tools/tcpa-check — 8 questions, instant risk assessment, penalty calculator.
-- Justin
---
## Post 12: r/Entrepreneur — Why Fixed-Price Compliance Beats Hourly Attorney Rates
**Title:** I spent $4,200 on a lawyer to file a state registration that should have cost $249 — here's what I learned about compliance vs. legal work
This isn't a knock on lawyers — you need one for litigation, contracts, and legal opinions. But a lot of what business owners pay attorneys $300–$500/hour for is procedural compliance work: filing forms, registering with state agencies, reviewing handbooks against checklists.
**Things that are compliance/administrative work:**
- Filing annual reports with the Secretary of State
- Registering your LLC in a new state (foreign qualification)
- Filing FCC Form 499-A
- Reviewing your employee handbook against current federal/state law
- Auditing your privacy policy against CCPA requirements
- Checking contractor classification against IRS/DOL tests
**Things that require an actual attorney:**
- Drafting complex contracts
- Responding to lawsuits
- Representing you in regulatory proceedings
- Providing legal opinions on ambiguous situations
- Tax strategy and planning
The difference matters because compliance work has predictable scope. An annual report filing is the same process every time. A contractor classification review uses published IRS and DOL criteria. There's no reason to pay someone $400/hour to do something that has a fixed process and a known deliverable.
That's why I started Performance West — fixed-price compliance services with defined deliverables and turnaround times. State registration: $249, 1-4 weeks. Handbook review: $999, 5-7 business days. CCPA audit: $2,499, 7-10 business days. No billable hours, no surprise invoices.
Not a replacement for a lawyer. A complement to one.
-- Justin
---
## Post 13: r/Bookkeeping — 1099 Red Flags Your Clients Might Be Missing
**Title:** Quick 1099 checklist I use when a client says "they're all contractors"
Every tax season I hear this from at least a few clients: "Don't worry, they're all 1099." And every time I ask the same follow-up questions that usually reveal at least one person who probably shouldn't be on a 1099.
Here's the short list I run through:
1. Does the worker set their own hours, or does the client set a schedule?
2. Does the worker use their own tools and equipment?
3. Does the worker provide similar services to other businesses?
4. Is there a written independent contractor agreement?
5. Can the client terminate the relationship without cause?
6. Does the worker have their own business insurance?
7. Does the worker invoice for their services?
If the answer to 3+ of these is "no," that's a conversation worth having with the client before filing season. The IRS 20-factor test and the DOL economic reality test both look at the actual working relationship, not what the contract says.
The penalties for misclassification include back employment taxes, unpaid overtime, and potentially liquidated damages. Some states have it even worse — California's PAGA allows per-pay-period penalties.
I know it's not our job to be the compliance police, but flagging potential misclassification issues early can save a client from a very expensive problem down the road.
-- Justin
---
## Post 14: r/QuickBooks — Setting Up 1099 Contractors Correctly in QB
**Title:** Before you add that 1099 contractor in QuickBooks, make sure they're actually a contractor
QB makes it easy to set someone up as a 1099 vendor and start cutting checks. But the IRS doesn't care how you categorize them in your accounting software — they care about the actual working relationship.
Quick sanity check before you hit "Save":
- Does this person work a set schedule that you control? → Might be an employee
- Do they only work for your company? → Red flag
- Do you provide their tools, software, or workspace? → Red flag
- Are they doing the same work as your W-2 employees? → Big red flag
QuickBooks will happily generate 1099-NEC forms for anyone you classify as a vendor. But if the IRS or your state labor board disagrees with that classification, you're looking at back taxes, penalties, and potentially years of unpaid benefits and overtime.
The "I'll just 1099 everyone" approach is the most common payroll compliance mistake I see. It's also one of the easiest to fix if you catch it early.
If you're not sure about any of your workers, there's a free classification quiz at performancewest.net/tools/contractor-quiz that walks through the IRS criteria. Takes about 2 minutes.
-- Justin
---
## Post 15: r/antiwork — Your employer calling you a "contractor" doesn't make it true
**Title:** If your employer controls your schedule, provides your tools, and you only work for them — you're probably an employee no matter what they call you
I see a lot of posts here about being paid as a 1099 when the working relationship looks nothing like independent contracting. Here's the thing: it doesn't matter what the contract says or what your employer calls you. The IRS and Department of Labor look at the actual working relationship.
Key factors that point toward employee (not contractor):
- Your employer sets your schedule or requires specific hours
- They provide your tools, equipment, software, or workspace
- You can't work for competitors or other clients
- You receive training from them on how to do the work
- The work you do is a core function of their business
- The relationship is ongoing with no defined end date
If most of these describe your situation, you may have a valid misclassification claim. This matters because as an employee you'd be entitled to overtime pay, minimum wage protections, unemployment insurance, workers' comp, and employer-paid FICA taxes.
Employers do this to save 20-30% on labor costs — they avoid payroll taxes, benefits, overtime, and workers' comp insurance. But it's illegal, and enforcement is increasing. The DOL has been actively auditing, and state agencies (especially California, New York, and New Jersey) are cracking down hard.
You can file a complaint with your state labor board or the DOL — there's no cost and protections exist against retaliation.
-- Justin
---
## Post 16: r/IRS — How misclassifying contractors can snowball fast
**Title:** PSA for business owners: misclassifying one worker as 1099 instead of W-2 can cost more than you think
Seeing a lot of posts about IRS notices related to worker classification. Here's a breakdown of what's actually at stake:
**If the IRS reclassifies your 1099 workers as employees, you owe:**
- Back FICA taxes (employer share: 7.65% of wages)
- FUTA taxes
- Interest on unpaid taxes from the date they should have been paid
- Penalties for failure to file (W-2s instead of 1099s)
- Potential Section 3509 penalty assessments
**And that's just the IRS.** Your state may also come after you for:
- State unemployment insurance taxes (SUTA)
- State withholding taxes
- Workers' compensation insurance premiums
**And then there's the DOL side:**
- Back overtime pay (time-and-a-half for all hours over 40/week)
- Liquidated damages (double the back-pay)
- Up to 3 years of back wages
The total cost per misclassified worker can easily hit $50,000+ depending on how long they've been misclassified and whether overtime is involved.
The good news: voluntary reclassification programs exist and the IRS's Section 3509 gives reduced rates if you proactively fix the issue before an audit. Fixing it early is always cheaper than getting caught.
-- Justin
---
## Post 17: r/payroll — The compliance side of payroll that software doesn't handle
**Title:** Your payroll software runs payroll. It doesn't tell you if your classifications are wrong.
QuickBooks, Gusto, ADP, Paychex — they all process payroll correctly once you tell them who's exempt, who's non-exempt, and who's a contractor. But none of them tell you whether those classifications are right in the first place.
Common issues I see that payroll software won't catch:
1. **Exempt employees who don't actually qualify for exemption.** The salary threshold is one piece — they also need to meet the duties test. An "Office Manager" making $55K isn't automatically exempt.
2. **1099 contractors who look like employees.** The software generates 1099-NEC forms for anyone you mark as a vendor. It doesn't verify the working relationship.
3. **State-specific requirements.** Several states have different overtime rules, meal break requirements, and classification tests than federal law. Your payroll software uses whatever you configured.
4. **Multi-state employees.** Remote workers create tax withholding and registration obligations in their home state, not just yours.
The payroll software is the engine — but you still need to make sure you're putting the right fuel in it. Getting the classification and exemption decisions right upfront prevents expensive corrections later.
-- Justin
---
## Post 18: r/EmploymentLaw — Contractor misclassification from the employer's perspective
**Title:** For employers reading here: the cost of misclassification vs. the cost of doing it right
I see a lot of posts here from employees who think they're misclassified. Here's the employer-side math that explains why this happens — and why fixing it proactively is almost always cheaper.
**Why employers misclassify (the perceived savings):**
- No FICA employer share (saves ~7.65%)
- No unemployment insurance (saves 2-6%)
- No workers' comp premiums (saves 1-5%)
- No overtime obligations
- No benefits obligations
Total perceived savings: 15-30% of labor costs per worker.
**What it actually costs when caught:**
- Back FICA taxes (7.65% × all wages × all years)
- Back SUTA and FUTA taxes
- Back overtime for all hours over 40
- Liquidated damages (double the overtime owed)
- IRS penalties and interest
- State penalties
- Attorney fees (if employee sues)
- Potential class action if multiple workers are affected
A single misclassified worker earning $50K/year over 3 years can easily generate $50-$100K+ in back-pay, taxes, and penalties. Multiply that by the number of workers affected.
The fix: get a professional classification review done. The cost is a fraction of the exposure. And if you need to reclassify, doing it voluntarily before an audit is much cheaper than getting caught.
-- Justin
---
## Post 19: r/telecom — Why small carriers are moving voice operations to Canada
**Title:** The regulatory math for moving your carrier to Canada is getting hard to ignore
If you're running a small voice carrier or VoIP operation in the US, here's what your annual regulatory burden looks like in 2026:
- Section 214 license: $1,895 filing fee + $5-15K in attorney fees
- FCC Form 499-A: annual filing + USF contributions at 36.6% of interstate/international revenue
- STIR/SHAKEN: $3-5K/yr for SBC compliance
- CALEA: $50-500K+ for intercept infrastructure (yes, even for small resellers)
- RMD: must file or downstream carriers block your traffic
- State PUCs: $50-750 per state where you have customers
- Annual FCC regulatory fees: $460-1,000+
- Telecom taxes on customer invoices: 15-40% in surcharges (USF, excise, E911, TRS, state)
And now the FCC is proposing to limit DID reselling to a single level (FCC 26-17, March 2026).
Compare that to registering as a carrier in Canada:
- CRTC registration: letter to the Secretary General, published in a public notice
- No CALEA equivalent for resellers (upstream provider handles intercept)
- No USF equivalent
- No state-level telecom registrations (federal only)
- No telecom surcharges on customer invoices (just standard GST/HST on Canadian sales, and international B2B is zero-rated)
- No FBI background checks or Team Telecom review
- BC small business tax rate: 11% combined (vs. 21%+ in the US)
Canada and the US share country code +1. Canadian DIDs are indistinguishable from US numbers. Latency from Toronto or Vancouver to US cities is sub-10ms — same as domestic. VoIP.ms has been doing this from Montreal for years.
I work with carriers setting up Canadian operations. The typical Year 1 savings vs. maintaining a US 214 license are $50-500K+ depending on your CALEA situation.
Not legal advice — talk to a US and Canadian telecom attorney about your specific situation. But the regulatory math is getting increasingly one-sided.
-- Justin
---
## Post 20: r/VoIP — Has anyone set up a Canadian carrier to avoid FCC 214 headaches?
**Title:** Thinking about registering as a Canadian carrier instead of dealing with 214/499A/CALEA — anyone done this?
Looking at the numbers and I'm curious if anyone here has gone the Canadian route.
Context: I run a small wholesale voice operation. My 214 compliance costs me roughly $25-30K/yr between USF contributions, STIR/SHAKEN, RMD maintenance, annual regulatory fees, and the accountant who prepares my 499-A. And that's before CALEA — I'm using a safe harbor solution that runs about $5K/yr.
Meanwhile I keep seeing Canadian companies like VoIP.ms selling US DIDs and SIP trunking without any of this overhead. They're operating under CRTC jurisdiction, not FCC.
From what I've researched:
- You incorporate a BC corporation (no Canadian citizenship required for resellers)
- Register with the CRTC as a domestic reseller + file BITS for international
- Get published in a CRTC public notice
- Your Canadian carrier can purchase US DIDs from wholesale providers like Flowroute/Iristel
- Same +1 country code, sub-10ms latency to US, customers can't tell the difference
The CRTC doesn't have:
- 214 license requirement
- CALEA mandate for resellers
- USF contributions
- State PUC registrations
- The DID reselling restrictions the FCC just proposed
Has anyone here actually made this move? What was your experience? Any gotchas I'm missing?
-- Justin

774
docs/multi-province-plan.md Normal file
View file

@ -0,0 +1,774 @@
# Multi-Province, Canadian Formation & Universal Compliance — Implementation Plan
**Created:** 2026-04-05
**Status:** Planning — dev-only implementation, not yet in production
**Triggers:**
- Ontario removed Canadian resident director requirement (Bill 213, July 2021)
- Formation page frontend already supports 10 Canadian provinces (backend does not)
- Compliance calendar system built for CRTC but not used by other order types
---
## Goal
Three interconnected features:
1. **Multi-province CRTC** — Extend the $3,899 CRTC Carrier Package from BC-only to
multi-province. Ontario first; architecture supports any Canadian province.
2. **Standalone Canadian formation** — Offer Canadian province incorporation (C$449
+ gov fees) on the existing formation page WITHOUT telecom registration. Separate flow from CRTC.
3. **Universal compliance calendar** — Create compliance entries for ALL orders (US formations,
Canadian formations, CRTC carriers). Formation maintenance bundle at $199/yr.
Service fee stays at $3,899 USD for CRTC regardless of province. US formation: $179 Basic /
$399 Complete. Canadian formation: C$449 + gov fees (single tier). Government fees passed
through at cost for all products.
**Dev-only gate:** Ontario and Canadian formation options visible only in dev
(`import.meta.env.DEV` / `NODE_ENV !== 'production'`). Production continues unchanged
until everything is tested end-to-end.
---
## Research Findings
### Ontario Director Residency — Confirmed Removed
Bill 213 (Better for People, Smarter for Business Act, 2020) removed OBCA s.118(3)
requiring 25% of directors to be Canadian residents. Proclaimed in force July 5, 2021.
Both BC and Ontario now have no Canadian residency requirement — the key enabler for
our foreign (non-Canadian) clients.
### Ontario vs BC Comparison
| Factor | BC | Ontario |
|--------|----|----|
| Director residency | None required | None required |
| Incorporation fee | ~C$350 | ~C$360 |
| Annual return/report | C$42.71/yr | C$25/yr |
| Portal | BC Corporate Online (anonymous) | Ontario Business Registry (requires login) |
| Entity format | "1234567 B.C. Ltd." | "1234567 Ontario Inc." |
| Legal endings | Ltd., Inc., Corp., Limited, etc. | Inc., Corp., Ltd., Ltee (+ French) |
| Sales tax | GST 5% + PST 7% = 12% | HST 13% (combined) |
| Workers comp | WorkSafeBC | WSIB |
| DID area codes | 604/778/236/250 | 416/647/437/905/289/365/519/613 |
| AMB locations | 4 (Vancouver) | 30+ (Toronto, Mississauga, Ottawa, etc.) |
| AMB pricing | ~C$13-20/mo | from C$7.99/mo |
| Corporate tax (small biz) | 11% combined | 12.2% combined |
| Language | English only | English or French |
### Province-Agnostic Components (Zero Changes Needed)
These are federal or infrastructure-level and work identically for any province:
- CRTC domestic carrier registration (letter to Secretary General)
- BITS international registration (Form 503 + affidavit)
- CCTS membership registration
- GCKey provisioning (for CRTC filings)
- .ca domain registration via Porkbun (CIRA CPR satisfied by any Canadian corp)
- HestiaCP email/hosting provisioning
- eSign portal flow
- MinIO document storage
- Corporate binder compilation (pikepdf + reportlab)
- Payment processing (Stripe/PayPal/SHKeeper)
### Key Difference: OBR Requires Login
BC Corporate Online is anonymous — no account needed. The Ontario Business Registry
requires an Ontario Business Account (OBA) login. Plan: create a Performance West
"house account" on the OBR and test whether it's suitable for filing multiple
incorporations. If not, fall back to admin ToDo with manual incorporation.
### Formation Page — Existing Canada Support
The formation order page (`site/src/pages/order/formation.astro`) already has:
- Country selector (US / CA)
- `CA_PROVINCES` array with all 10 provinces + fees + live FX conversion
- Entity type swap: LLC->Ltd., Corporation->Inc., S-Corp->Corp.
- Province dropdown with dual CAD/USD pricing
- CRTC callout linking to the CRTC order page (separate flows)
**What's missing:** The backend (`formations.ts` route) only validates US entity types
and the `formation_orders` table has `entity_type CHECK (llc, corporation, s_corp)`.
Canadian types (ltd, inc, corp) are rejected. No Canadian province adapter is dispatched.
### Codebase Coupling (CRTC Pipeline)
~100+ hardcoded "BC" references across:
- Order form (`site/src/pages/order/canada-crtc.astro`) — ~40 references
- Pipeline (`scripts/workers/services/canada_crtc.py`) — ~50 references
- API route (`api/src/routes/canada-crtc.ts`) — ~10 references
- AMB scraper, Flowroute DID, compliance calendar
No `province` column in `canada_crtc_orders` table. Pipeline hardcodes `BCPortal` import.
Good abstraction points exist: `StatePortal` base class, `amb_locations.province` column,
`own_ca_province` DB column, `FormationOrder.state_code` parameter.
---
## Architecture
### Product Matrix
| Product | Price | Pipeline | Compliance Entries | Maintenance |
|---------|-------|----------|-------------------|-------------|
| US Formation Basic | $179 + state fees | US state adapter | 1-3 (annual report, franchise tax) | $179/yr bundle |
| US Formation Complete | $399 + state fees | US state adapter | 2-4 (+ RA renewal) | $179/yr bundle |
| CA Formation | C$449 + gov fees + AMB | CanadianIncorporationHandler | 7-8 (annual return + tax + AMB) | $179/yr bundle |
| CRTC Carrier Package | $3,899 + gov fees | CanadaCRTCHandler (composes CanadianIncorporationHandler) | 15-17 (+ telecom obligations) | $349/yr |
### Pipeline Decomposition
The CRTC pipeline is currently monolithic. We decompose it into shared incorporation
steps and telecom-only steps.
**Shared steps** (used by BOTH formation-only AND CRTC):
| Step | Action | Formation Basic | Formation Complete | CRTC |
|------|--------|----|----|----|
| AMB mailbox setup | Registered office | No | Yes | Yes |
| Name reservation | Registry filing | If named | If named | If named |
| Incorporation | COLIN / OBR | Yes | Yes | Yes |
| Trade name registration | Registry filing | If requested | If requested | If requested |
| CRA Business Number | BN from CRA | Add-on ($49) | Add-on ($49) | No (not needed) |
| Organizational minutes | Document gen | No | Yes | Yes |
| Corporate binder | PDF compilation | Digital only | Yes | Yes |
| Delivery email | Send docs | Yes | Yes | Yes |
| Compliance calendar | Create entries | Yes (corporate) | Yes (corporate + AMB) | Yes (corporate + telecom) |
**CRTC-only steps** (NOT in formation pipeline):
| Step | Action |
|------|--------|
| DID provisioning | Canadian phone number via Flowroute |
| .ca domain + HestiaCP | Domain, email, 14 mailboxes, hosting |
| CRTC letter generation | DOCX template -> MinIO -> DocServer PDF |
| eSign | Client signs CRTC letter in portal |
| CRTC submission | Mail letter to Secretary General |
| BITS registration | GCKey provisioning + BITS filing |
| CCTS membership | Registration + client obligations email |
| GCKey provisioning | Government credential for CRTC filings |
| Telecom compliance entries | CRTC, BITS, CCTS, ATS surveys, DID/domain/mailbox renewals |
### ProvinceConfig Protocol
```python
class ProvinceConfig(TypedDict):
# Identity
code: str # "BC", "ON", "AB", "QC", ...
name: str # "British Columbia", "Ontario"
abbreviation: str # "B.C.", "Ont."
# Corporate law
act_name: str # "BC Business Corporations Act", "OBCA"
legal_endings: list[str] # Province-specific corporate name suffixes
numbered_entity_template: str # "{number} B.C. Ltd.", "{number} Ontario Inc."
# Portal
portal_name: str # "BC Corporate Online", "Ontario Business Registry"
portal_url: str
requires_login: bool # False (BC), True (ON)
selectors: dict # Playwright CSS selectors for portal
# Fees (CAD cents)
incorporation_fee_cad: int # 35000 (BC), 36000 (ON)
annual_return_fee_cad: int # 4271 (BC), 2500 (ON)
annual_return_name: str # "Annual Report" (BC), "Annual Return" (ON)
name_reservation_fee_cad: int
# Tax
sales_tax: dict # {type: "GST+PST", gst: 5, pst: 7} or {type: "HST", rate: 13}
workers_comp_name: str # "WorkSafeBC", "WSIB"
# Infrastructure
area_codes: list[str] # DID area codes for Flowroute
default_city: str # "Vancouver", "Toronto"
timezone: str # "America/Vancouver", "America/Toronto"
amb_scrape_slug: str # "british-columbia", "ontario"
registered_office_addresses: list
# Compliance
corporate_obligations: list # Province-specific tax/filing requirements
supports_formation_only: bool # Whether we offer standalone formation
cra_bn_automatable: bool # Whether BN registration can be automated
# Templates
articles_template: str # Path to province-specific Articles template
minutes_template: str # Path to organizational minutes template
```
### Universal Compliance Calendar
A shared module called by ALL pipelines:
```python
# scripts/formation/compliance.py
def create_compliance_entries(
order_type: str, # "crtc" | "ca_formation" | "us_formation"
jurisdiction: str, # "BC", "ON", "WY", "DE", etc.
country: str, # "CA" | "US"
order_reference: str, # Sales Order or order number
entity_name: str,
incorporation_date: date,
add_ons: dict, # {ra: bool, amb: bool, domain: bool, did: bool, ein: bool}
) -> list[dict]:
"""Create compliance calendar entries based on order type and jurisdiction."""
```
The function reads obligations from province/state config and filters by order_type.
The `renewal_worker.py` already handles the lifecycle regardless of origin.
### File Structure
```
scripts/formation/
province_config.py # ProvinceConfig TypedDict + get_province(code)
compliance.py # NEW: Universal create_compliance_entries()
canadian_incorporation.py # NEW: CanadianIncorporationHandler (shared steps)
base.py # StatePortal base class (existing)
states/
__init__.py # State registry (add CA provinces)
bc/config.py # BC ProvinceConfig (refactored)
bc/adapter.py # BCPortal(StatePortal) (existing)
on/__init__.py # NEW
on/config.py # NEW: Ontario ProvinceConfig
on/adapter.py # NEW: ONPortal(StatePortal)
wy/config.py # WY config (add compliance obligations)
... (50 more US states)
scripts/workers/
services/
canada_crtc.py # MODIFIED: Composes with CanadianIncorporationHandler
cra_bn.py # NEW: CRA Business Number registration
flowroute.py # MODIFIED: provision_canadian_did(province)
renewal_worker.py # Unchanged (already handles any compliance entry)
amb_location_scraper.py # MODIFIED: Multi-province scraping
```
---
## Pricing
### CRTC Carrier Package (unchanged)
| Item | Price |
|------|-------|
| CRTC Telecom Registration (one-time) | $3,899 USD |
| Annual Maintenance & Compliance | $349/yr |
| Consulting | $75/hr |
| Government fees | Passed through at cost (province-specific) |
### Canadian Formation (new)
| Item | Price | Notes |
|------|-------|-------|
| Canadian Formation | C$449 + gov fees | Incorporation + org minutes + binder + compliance calendar. AMB mailbox billed separately (annual, ~C$96-240/yr depending on location). |
| Government fees | BC ~C$350, ON ~C$360 | Passed through (BoC rate + 10% buffer) |
| Add-on: CRA BN | $49 | Business Number registration with CRA |
| Add-on: Named company | +gov fee | Name reservation (BC: C$30, ON: varies) |
| Free DID | Included | With formation + RA renewal (stub — not yet active) |
### Maintenance Bundles (new)
| Bundle | Price | Includes |
|--------|-------|---------|
| US Formation Maintenance | $179/yr | Annual report filing ($99 value) + RA renewal ($99 value) |
| CA Formation Maintenance | $179/yr | Annual return filing ($99 value) + AMB/RA renewal ($99 value) |
| CRTC Maintenance (existing) | $349/yr | All of CA maintenance + CRTC + CCTS + domain/email + DID |
### ERPNext Items Needed
| Item Code | Name | Rate (USD) | Used By |
|-----------|------|-----------|---------|
| `CRTC-MAINT-ANNUAL` | CRTC Annual Maintenance | $349/yr | CRTC orders |
| `FORMATION-MAINT-US` | US Formation Maintenance Bundle | $179/yr | US formation (Complete) |
| `FORMATION-MAINT-CA` | CA Formation Maintenance Bundle | $179/yr | CA formation |
| `RA-RENEWAL` | Registered Agent Renewal | $99/yr ($49 WY) | All formations (if RA) |
| `FREE-DID` | Free DID (with formation + RA) | $0 | Stub — not yet active |
| `ANNUAL-REPORT` | Annual Report/Return Filing | $99/yr | All formations |
| `CRA-BN` | CRA Business Number Registration | $49 | CA formation add-on |
| `MAILBOX-RENEWAL` | Mailbox Renewal (AMB) | $199/yr | CRTC + CA Complete |
| `DOMAIN-RENEWAL-CA` | .ca Domain + Hosting Renewal | $25/yr | CRTC only |
---
## Phases
### Phase 0: OBR + CRA Playwright Recon
**Model: Opus 4.6** — Complex unknown-portal reconnaissance requiring judgment.
**0a. Ontario Business Registry recon:**
1. Navigate to `business.ontario.ca`, map account creation flow
2. Walk through incorporation wizard — record form fields, selectors, inputs
3. Document: login method, MFA, CAPTCHA, bot detection
4. Record: payment step (credit card selectors)
5. Test if one house account can file multiple incorporations
6. Record: name search flow (part of wizard or separate?)
7. Output: selector map + screenshots saved to MinIO
**0b. CRA Business Number recon:**
1. Navigate to CRA Business Registration Online
2. Map the BN registration form fields
3. Document: does it require an existing corp number? Identity verification?
4. Can we register using our house account or does the client need to do it?
5. Determine if automatable or admin ToDo
**Files:**
- `scripts/recon_obr.py` — NEW: OBR Playwright recon script
- `scripts/recon_cra_bn.py` — NEW: CRA BN recon script
**Effort:** 2-2.5 hours
---
### Phase 1: ProvinceConfig + Compliance Module Design
**Model: Opus 4.6** — Architecture with future-proofing for any province and all order types.
**Files:**
- `scripts/formation/province_config.py` — NEW: ProvinceConfig TypedDict + `get_province(code)` registry
- `scripts/formation/compliance.py` — NEW: `create_compliance_entries()` universal function
- `scripts/formation/states/bc/config.py` — MODIFY: conform to ProvinceConfig
- `scripts/formation/states/__init__.py` — MODIFY: register CA provinces, add compliance fields to US states
The compliance module design must handle:
- CRTC orders: 15-17 entries (telecom + corporate + renewals)
- CA formation: 6-8 entries (corporate obligations only)
- US formation: 1-4 entries (annual report + RA + franchise tax)
- Filtering by order type and purchased add-ons
- Province/state-specific deadlines, fees, and filing names
**Effort:** 3-4 hours
---
### Phase 2: Database Migrations
**Model: Sonnet 4.6** — Mechanical SQL.
**Files:**
- `api/src/migrations/036_multi_province.sql` — NEW
```sql
-- === CRTC table changes ===
ALTER TABLE canada_crtc_orders ADD COLUMN province TEXT NOT NULL DEFAULT 'BC';
ALTER TABLE canada_crtc_orders RENAME COLUMN bc_incorporation_number TO incorporation_number;
CREATE INDEX idx_crtc_orders_province ON canada_crtc_orders(province);
-- === Formation table changes ===
ALTER TABLE formation_orders ADD COLUMN country CHAR(2) NOT NULL DEFAULT 'US';
ALTER TABLE formation_orders DROP CONSTRAINT formation_orders_entity_type_check;
ALTER TABLE formation_orders ADD CONSTRAINT formation_orders_entity_type_check
CHECK (entity_type IN ('llc', 'corporation', 's_corp', 'ltd', 'inc', 'corp'));
CREATE INDEX idx_formation_orders_country ON formation_orders(country);
```
**Effort:** 45 minutes
---
### Phase 3: Ontario Adapter + Infrastructure + Shared Handlers
**3a. Ontario config** — **Sonnet 4.6**
`scripts/formation/states/on/config.py` — Full Ontario ProvinceConfig:
- OBR URLs, fees (C$360 incorp, C$25 annual return)
- Legal endings: Inc., Corp., Ltd., Ltee, Cie (+ French equivalents)
- Area codes: 416/647/437/905/289/365/519/613/705
- HST 13%, WSIB, Toronto default
- Selectors from Phase 0 recon
- Corporate obligations (Ontario Annual Return, T2, GST/HST, WSIB — no PST)
**3b. Ontario adapter** — **Sonnet 4.6**
`scripts/formation/states/on/adapter.py` — `ONPortal(StatePortal)`:
- `search_name()`: OBR free search
- `file_incorporation()`: initially admin ToDo, OBR automation stubbed
- `file_llc()` / `file_corporation()`: route to `file_incorporation()` (Canadian entity types)
**3c. AMB scraper extension** — **Sonnet 4.6**
`scripts/workers/amb_location_scraper.py`:
- Parameterize province in scrape function
- Add Ontario scraping (Toronto, Mississauga, Ottawa, Hamilton, etc.)
- Run for both BC + ON in daily cron
**3d. Flowroute DID generalization** — **Sonnet 4.6**
`scripts/workers/services/flowroute.py`:
- Rename `provision_bc_did()` -> `provision_canadian_did(province)`
- Area code mapping: BC=[604,778,236,250], ON=[416,647,437,905,289,365]
**3e. CanadianIncorporationHandler** — **Opus 4.6**
`scripts/formation/canadian_incorporation.py` — NEW:
- Shared incorporation pipeline used by BOTH formation-only AND CRTC
- Steps: AMB setup (if Complete), name reservation (if named), incorporation,
trade name (if requested), CRA BN (if add-on), binder compilation, delivery email,
compliance calendar creation
- `CanadaCRTCHandler` composes with this (calls it for incorporation, then
continues with telecom steps)
- Formation-only orders dispatch here directly from the job server
**3f. CRA BN registration** — **Sonnet 4.6**
`scripts/workers/services/cra_bn.py` — NEW:
- Initially stubbed as admin ToDo
- CRA Business Number registration automation added after Phase 0b recon
**3g. Universal compliance creator** — **Opus 4.6**
`scripts/formation/compliance.py` — NEW:
- `create_compliance_entries()` function
- Reads obligations from province/state config
- Filters by order_type and purchased add-ons
- Creates entries in ERPNext Compliance Calendar DocType
- Called by: CanadianIncorporationHandler, CanadaCRTCHandler, US formation job handler
**Effort:** 7-8 hours total (3a-d: 3-4 hrs, 3e: 2-3 hrs, 3f: 30 min, 3g: 1-2 hrs)
---
### Phase 4: Service Page Province Comparison Table + FAQ
**Model: Sonnet 4.6** (table HTML) + **Opus 4.6** (FAQ)
**4a. Province comparison table** (Sonnet) — Add to CRTC service page between the
corporate tax table (line ~1205) and M&A section (line ~1262):
New table: "Choose your province: incorporation comparison"
| Factor | British Columbia | Ontario | Alberta* | Federal (CBCA)* |
|--------|-----------------|---------|----------|----------------|
| Resident director | No | No | No | 25% Canadian |
| Incorporation fee | ~C$350 | ~C$360 | ~C$300 | ~C$200 |
| Annual return/report | C$42.71/yr | C$25/yr | C$20/yr | C$12/yr |
| Portal | Anonymous | Requires account | Requires account | Requires account |
| Processing time | 1-2 days | Same day | 1-2 days | 1-5 days |
| Numbered format | 1234567 B.C. Ltd. | 1234567 Ontario Inc. | 1234567 Alberta Ltd. | 1234567 Canada Inc. |
| Sales tax | GST+PST 12% | HST 13% | GST 5% | Depends |
| Small biz tax rate | 11% | 12.2% | 11% | Depends |
| Language | English | English/French | English | English/French |
| Best for | Pacific gateway | Largest market | Low cost | Multi-province |
*Alberta and Federal shown as "Coming soon".
**4b. FAQ rewrite** (Opus) — In `canada-crtc.json`:
- Rewrite Q23: "Which province should I choose?" — BC vs ON pros/cons
- New FAQ: "Can I switch provinces later?" — extra-provincial registration
**Effort:** 1-2 hours
---
### Phase 5: Order Form Multi-Province
**5a. CRTC order form** — **Opus 4.6**
Modify `site/src/pages/order/canada-crtc.astro` (2,550 lines):
- Province selector at Step 1 (radio: BC | Ontario, dev-only gate)
- `PROVINCE_DATA` JS object + `setProvince(code)` function
- Swaps: entity format, legal endings, fees, AMB locations, DID area codes, act references
- `province` hidden field in form submission
**5b. Formation page backend wiring** — **Sonnet 4.6**
The frontend already works for Canada. Backend changes only:
- Ensure the CRTC callout remains (separate flows)
- Verify entity type mapping sends correct values (ltd/inc/corp)
- Verify province fee display works with API
**Effort:** 4-5 hours total (5a: 3-4 hrs, 5b: 1 hr)
---
### Phase 6: API Routes + Pipeline Refactors
**6a. CRTC API route** — **Sonnet 4.6**
`api/src/routes/canada-crtc.ts`:
- Accept `province` parameter
- Province-specific fee calculation via lookup
- Dev gate: reject ON if `NODE_ENV=production`
- Store province in `canada_crtc_orders`
**6b. CRTC pipeline refactor** — **Opus 4.6**
`scripts/workers/services/canada_crtc.py` (2,179 lines):
- Constructor accepts `province` from Sales Order
- Composes with `CanadianIncorporationHandler` for incorporation steps
- Dynamic province adapter: `get_province(code)` replaces hardcoded `BCPortal`
- All messages use `province_config["name"]` instead of "BC"
- Compliance entries dispatched to universal `create_compliance_entries()`
**6c. Formation API route** — **Sonnet 4.6**
`api/src/routes/formations.ts`:
- Accept `country` parameter ("US" default, "CA")
- Validate Canadian entity types (ltd, inc, corp) when country=CA
- Province-specific fee calculation (CAD->USD via FX)
- Dev gate: reject country=CA if `NODE_ENV=production`
- Dispatch to `CanadianIncorporationHandler` job for CA orders
- ERPNext Formation Order: add Ltd./Inc./Corp. to entity_type Select
**Effort:** 5.5-6.5 hours total (6a: 1 hr, 6b: 3-4 hrs, 6c: 1.5-2 hrs)
---
### Phase 7: Compliance Configs — All Jurisdictions
**Model: Sonnet 4.6** — Data entry into established config structure.
**7a. Canadian province compliance configs:**
BC corporation (non-telecom):
| Entry | Fee | Deadline | Billable |
|-------|-----|----------|----------|
| BC Annual Report | C$42.71 | 2 months after anniversary | Yes ($99) |
| T2 Corporate Income Tax | $0 (accountant) | June 30 | No |
| Corporate Tax Payment | $0 (accountant) | March 31 | No |
| GST/HST Return | $0 (accountant) | March 31 (if registered) | No |
| T4/T4A Slips | $0 (accountant) | February 28 (if employees) | No |
| BC PST | $0 (accountant) | Volume-based (if applicable) | No |
| WorkSafeBC | $0 | March 1 (if BC employees) | No |
| AMB Renewal | ~C$199/yr | Anniversary | Yes ($99) |
Ontario corporation (non-telecom):
| Entry | Fee | Deadline | Billable |
|-------|-----|----------|----------|
| Ontario Annual Return | C$25 | 6 months after anniversary | Yes ($99) |
| T2 Corporate Income Tax | $0 (accountant) | June 30 | No |
| Corporate Tax Payment | $0 (accountant) | March 31 | No |
| HST Return | $0 (accountant) | March 31 (HST 13% combined) | No |
| T4/T4A Slips | $0 (accountant) | February 28 (if employees) | No |
| WSIB | $0 | Quarterly (if ON employees) | No |
| AMB Renewal | ~C$96/yr | Anniversary | Yes ($99) |
Note: Ontario has fewer entries (no separate PST — HST is combined).
**7b. US state compliance configs — all 51 jurisdictions:**
Add `compliance_obligations` to each state config in `scripts/formation/states/`.
Data sourced from `docs/state-annual-fees-complete.md`.
**States with annual report fees ($7-$810):**
| State | Code | Annual Fee | Deadline | Filing Name |
|-------|------|-----------|----------|-------------|
| California | CA | $810 | Apr 15 (1st year: 90 days) | Statement of Information + Franchise Tax |
| Massachusetts | MA | $500 | Anniversary | Annual Report |
| Nevada | NV | $350 | Anniversary | Annual List + Business License |
| Delaware | DE | $300 | Jun 1 | Franchise Tax |
| Maryland | MD | $300 | Apr 15 | Annual Report + PPT Return |
| Tennessee | TN | $300 | Anniversary (1st quarter) | Annual Report |
| North Carolina | NC | $200 | Apr 15 | Annual Report |
| DC | DC | $150/yr | Anniversary (biennial $300) | Biennial Report |
| Arkansas | AR | $150 | May 1 | Franchise Tax Report |
| Florida | FL | $138.75 | May 1 | Annual Report |
| New Hampshire | NH | $100 | Apr 1 | Annual Report |
| Oregon | OR | $100 | Anniversary | Annual Report |
| Alaska | AK | $50/yr | Jan 2 (biennial $100) | Biennial Report |
| Maine | ME | $85 | Jun 1 | Annual Report |
| Connecticut | CT | $80 | Anniversary | Annual Report |
| Illinois | IL | $75 | Anniversary month | Annual Report |
| New Jersey | NJ | $75 | Anniversary month | Annual Report |
| Georgia | GA | $60 | Apr 1 | Annual Registration |
| Washington | WA | $60 | Anniversary | Annual Report |
| Wyoming | WY | $60 min | Anniversary month | Annual Report |
| South Dakota | SD | $55 | Anniversary month | Annual Report |
| Alabama | AL | $50 min | Apr 15 | Business Privilege Tax |
| Kansas | KS | $50 | Apr 15 | Annual Report |
| North Dakota | ND | $50 | Nov 15 | Annual Report |
| Rhode Island | RI | $50 | Anniversary | Annual Report |
| Virginia | VA | $50 | Anniversary month (last day) | Annual Registration |
| Vermont | VT | $45 | Anniversary quarter | Annual Report |
| Hawaii | HI | $35 | Anniversary | Annual Report + GET License |
| Louisiana | LA | $35 | Anniversary | Annual Report |
| Colorado | CO | $25 | Anniversary month | Periodic Report |
| Michigan | MI | $25 | Feb 15 | Annual Statement |
| Oklahoma | OK | $25 | Anniversary | Annual Certificate |
| West Virginia | WV | $25 | Jul 1 | Annual Report |
| Wisconsin | WI | $25 | Anniversary quarter | Annual Report |
| Montana | MT | $20 | Apr 15 | Annual Report |
| Utah | UT | $18 | Anniversary | Annual Renewal |
| Indiana | IN | $15/yr | Anniversary month (biennial $30) | Business Entity Report |
| Iowa | IA | $15/yr | Apr 1 odd years (biennial $30) | Biennial Report |
| Kentucky | KY | $15 | Jun 30 | Annual Report |
| Pennsylvania | PA | $7 | Anniversary (new as of 2025) | Annual Report |
| New York | NY | $4.50/yr | Anniversary (biennial $9) | Biennial Statement |
| Nebraska | NE | $6.50/yr | Apr 1 odd years (biennial $13) | Biennial Report |
**States with $0 annual fees (9 states):**
| State | Code | Notes |
|-------|------|-------|
| Arizona | AZ | No annual report required, no fee |
| Idaho | ID | Annual report required but $0 fee |
| Minnesota | MN | Annual renewal required but $0 fee |
| Mississippi | MS | No annual report ($0); privilege tax only for S-Corps |
| Missouri | MO | No annual report required, no fee |
| New Mexico | NM | No annual report required, no fee |
| Ohio | OH | No annual report; Commercial Activity Tax only if revenue >$150K |
| South Carolina | SC | No annual report unless LLC elects S-Corp treatment |
| Texas | TX | Public Information Report ($0); franchise tax only if revenue >$2.47M |
**Note:** Even $0-fee states get a compliance calendar entry as a REMINDER — the
client may still need to file a $0 report to maintain good standing (ID, MN, TX).
**Franchise tax states (additional entry beyond annual report):**
| State | Franchise Tax | Threshold | Deadline |
|-------|--------------|-----------|----------|
| California | $800/yr minimum | All LLCs | Apr 15 |
| Delaware | $300/yr minimum | All LLCs | Jun 1 |
| Texas | 0.375%/0.75% of revenue | >$2.47M revenue | May 15 |
| Tennessee | $300/member min | All LLCs | Anniversary |
| Alabama | $0.25 per $1K net worth | Min $50, max $15K | Apr 15 |
**Effort:** 3-4 hours total (7a: 1 hr, 7b: 2-3 hrs)
---
### Phase 8: Dev Stack E2E Tests
**Model: Debugger agent**
**8a. Multi-province CRTC test:**
1. Verify province selector shows BC + ON on dev
2. Create Ontario CRTC order, verify fees adjust
3. Verify DID search returns 416/647 numbers
4. Verify mailbox picker shows Toronto locations
5. Verify pipeline runs with ON adapter
6. Verify compliance calendar: 15-17 ON entries (WSIB not WorkSafeBC, no PST, HST)
7. Verify emails use "Ontario" language
8. Regression: verify BC orders still work
**8b. Canadian formation-only test:**
1. Select Canada + Ontario on formation page
2. Verify entity types show Ltd./Inc./Corp.
3. Verify fees show CAD + USD
4. Submit formation-only order
5. Verify CanadianIncorporationHandler dispatched (no telecom steps)
6. Verify compliance calendar: 6-8 ON entries (corporate only, no telecom)
7. Verify binder compilation works without CRTC letter
**8c. US formation compliance test:**
1. Create a WY formation order
2. Verify compliance calendar entry created: WY Annual Report ($60, anniversary month)
3. Create a DE formation order (with RA)
4. Verify entries: DE Franchise Tax ($300, Jun 1) + RA renewal ($99)
5. Verify renewal_worker processes these entries correctly
**Effort:** 2-3 hours
---
## Model Assignment Summary
| Model | Phases | Why |
|-------|--------|-----|
| **Opus 4.6** | 0, 1, 3e, 3g, 4b, 5a, 6b | Architecture, unknown portal recon, pipeline decomposition, complex refactoring, persuasive content |
| **Sonnet 4.6** | 2, 3a-d, 3f, 4a, 5b, 6a, 6c, 7a, 7b | Mechanical edits, known patterns, SQL, HTML tables, data entry, config population |
| **Debugger** | 8 | Build verification, regression testing, E2E validation |
---
## Effort Summary
| Phase | Effort | Model |
|-------|--------|-------|
| Phase 0: OBR + CRA Recon | 2-2.5 hrs | Opus |
| Phase 1: ProvinceConfig + compliance design | 3-4 hrs | Opus |
| Phase 2: DB Migrations | 45 min | Sonnet |
| Phase 3a-d: ON adapter + AMB + DID | 3-4 hrs | Sonnet |
| Phase 3e: CanadianIncorporationHandler | 2-3 hrs | Opus |
| Phase 3f: CRA BN stub | 30 min | Sonnet |
| Phase 3g: Universal compliance creator | 1-2 hrs | Opus |
| Phase 4: Service page table + FAQ | 1-2 hrs | Sonnet + Opus |
| Phase 5a: CRTC order form | 3-4 hrs | Opus |
| Phase 5b: Formation page wiring | 1 hr | Sonnet |
| Phase 6a: CRTC API route | 1 hr | Sonnet |
| Phase 6b: CRTC pipeline refactor | 3-4 hrs | Opus |
| Phase 6c: Formation API route | 1.5-2 hrs | Sonnet |
| Phase 7a: CA province compliance configs | 1 hr | Sonnet |
| Phase 7b: US state compliance (51 jurisdictions) | 2-3 hrs | Sonnet |
| Phase 8: Dev E2E tests | 2-3 hrs | Debugger |
| **Total** | **28-36 hours** | **5-6 sessions** |
Parallelizable: Phases 0, 1, 2, 4, and 7b have no dependencies on each other.
Phase 4 (service page table) can ship to production immediately — no backend needed.
---
## Files Changed Summary
### New Files (10)
| File | Phase | Purpose |
|------|-------|---------|
| `scripts/formation/province_config.py` | 1 | ProvinceConfig TypedDict + registry |
| `scripts/formation/compliance.py` | 3g | Universal compliance entry creator |
| `scripts/formation/canadian_incorporation.py` | 3e | Shared Canadian incorporation handler |
| `scripts/formation/states/on/__init__.py` | 3a | Ontario package init |
| `scripts/formation/states/on/config.py` | 3a | Ontario ProvinceConfig |
| `scripts/formation/states/on/adapter.py` | 3b | ONPortal(StatePortal) |
| `scripts/workers/services/cra_bn.py` | 3f | CRA Business Number registration |
| `scripts/recon_obr.py` | 0 | OBR Playwright recon (disposable) |
| `scripts/recon_cra_bn.py` | 0 | CRA BN recon (disposable) |
| `api/src/migrations/036_multi_province.sql` | 2 | Province + country columns |
### Modified Files (16)
| File | Phase | Change |
|------|-------|--------|
| `site/src/pages/services/telecom/canada-crtc.astro` | 4a | Province comparison table |
| `site/src/pages/order/canada-crtc.astro` | 5a | Province selector + dynamic content |
| `site/src/content/services/canada-crtc.json` | 4b | FAQ rewrite |
| `api/src/routes/canada-crtc.ts` | 6a | Accept province parameter |
| `api/src/routes/formations.ts` | 6c | Accept CA provinces + entity types |
| `scripts/workers/services/canada_crtc.py` | 6b | Compose with CanadianIncorporationHandler |
| `scripts/workers/services/flowroute.py` | 3d | `provision_canadian_did(province)` |
| `scripts/workers/amb_location_scraper.py` | 3c | Multi-province scraping |
| `scripts/workers/job_server.py` | 3e | Add CA formation job handlers |
| `scripts/formation/states/bc/config.py` | 1 | Conform to ProvinceConfig |
| `scripts/formation/states/__init__.py` | 1 | Register CA provinces |
| `scripts/formation/states/*/config.py` (51 files) | 7b | Add compliance_obligations to each US state |
| `erpnext/doctypes/formation_order/formation_order.json` | 6c | Add Canadian entity types |
| `docs/go-live-todo.md` | — | Add multi-province + formation items |
| `docs/product-facts.md` | — | Add CA formation product |
| `docs/billing.md` | — | Add maintenance bundles |
---
## AMB Ontario Locations
From Anytime Mailbox Ontario page (30+ locations):
| City | Address | Starting Price |
|------|---------|---------------|
| Toronto - Dundas St | 2967 Dundas St. W., Toronto, ON M6P 1Z2 | C$7.99/mo |
| Toronto - Davenport Rd | 1463 Davenport Rd, Toronto, ON M6H 2H6 | C$13.99/mo |
| Mississauga | 1065 Canadian Pl, Mississauga, ON L4W 0C2 | C$8.99/mo |
| + 25 more cities | Acton, Ajax, Bolton, Brampton, Cambridge, Cornwall, Etobicoke, Georgetown, Hamilton, Markham, North York, Oakville, Ottawa, etc. | Varies |
**Recommendation:** Default to a downtown Toronto location for prestige.
---
## Open Questions
| Question | Context | Decision Needed |
|----------|---------|-----------------|
| OBR house account viability? | Phase 0 will answer. If one account can't file multiple corps, fall back to admin ToDo. | After Phase 0 |
| CRA BN automation viability? | Phase 0b will answer. If not automatable, admin ToDo with instructions. | After Phase 0 |
| Alberta / Federal — when? | Architecture supports from day one. Add when demand warrants. | Post-launch |
| Ontario AMB default location? | Toronto has 6+ locations. Downtown for prestige? | Phase 3 |
| ON numbered entity suffix? | "Ontario Inc." or "Ontario Ltd."? Verify against OBR. | Phase 0 |
| French-language support? | OBCA allows French endings (Ltee, Cie). Offer on form? | Phase 5 |
| US state compliance — all at once or incremental? | 51 configs is a lot. Could do top 10 first. Decision: all 51 now. | Phase 7b |
| Formation maintenance auto-enrollment? | Auto-enroll in $179/yr bundle? Or opt-in? | Phase 6c |

253
docs/plan.md Normal file
View file

@ -0,0 +1,253 @@
# Performance West — Build Plan
**Last updated:** 2026-04-05
**Status:** Pre-launch. CRTC pipeline ~95% built (14 steps, BITS/CCTS/compliance calendar implemented). DocServer provisioned. US formation plumbing exists but no state has been filed end-to-end. Payment flow is wired but gateways not yet configured in ERPNext UI.
> **See also:** [`docs/multi-province-plan.md`](multi-province-plan.md) — Plan to extend CRTC to multi-province + standalone Canadian formation + universal compliance calendar. 28-36 hours, 16 sub-phases.
> **See also:** [`docs/competitive-pricing.md`](competitive-pricing.md) — Competitor pricing analysis: US formation, Canadian formation, registered agents. Updated 2026-04-05.
---
## How to Read This Plan
Tracks are independent workstreams. Within each track, items are ordered by dependency — complete them top-to-bottom. Across tracks, work in parallel where possible.
**Labels:**
- `[BLOCKER]` — nothing ships until this is done
- `[CRTC]` — affects the $3,899 flagship product
- `[FORMATION]` — affects US LLC/Corp product
- `[INFRA]` — server/ops
- `[PLUMBING]` — backend wiring, no user-facing change
---
## Track 1 — CRTC Pipeline (Flagship Revenue)
The Canada CRTC Carrier Package is the highest-value product. Get one real order through end-to-end before doing anything else.
### 1.1 ERPNext Payment Config `[BLOCKER][CRTC]`
ERPNext gateways exist as code but are not configured in the UI — no payment can complete.
- [ ] Configure Crypto Payment Settings: URL = `https://pay.performancewest.net`, SHKeeper API key
- [ ] Create Payment Gateway Account `Crypto-Crypto` in ERPNext
- [ ] Configure Adyen Settings (5 instances: Card, ACH, Klarna, CashApp, AmazonPay) — pending Adyen account approval
- [ ] Create 5 Adyen Payment Gateway Accounts
- [ ] Configure ERPNext SMTP for outbound email (invoices, notifications)
- [ ] Test: place a $1 test order, confirm Payment Request is created, confirm redirect to checkout, confirm webhook fires back to Express API
### 1.2 COLIN Selector Verification `[BLOCKER][CRTC]`
The BC incorporation adapter (`frappe_ca_registry/provinces/bc/adapter.py`) has 13 steps mapped but selectors are unverified against the live portal. No real BC incorporation can complete until this is tested.
- [ ] Place a real test incorporation order against COLIN (corporateonline.gov.bc.ca)
- [ ] Verify/fix selectors for: Step 6 Director, Step 7 Office Addresses, Step 8 Share Structure, Step 9 Notification, Step 12 Payment
- [ ] Verify payment step: COLIN accepts Visa/MC — use `relay-filing-card` via `get_filing_card` API
- [ ] Implement multiple-directors loop (currently only first director is inserted)
- [ ] Confirm that BC sends certificate email to `filings@performancewest.net`
- [ ] End-to-end smoke test: `frappe_ca_registry` creates Filing Request → COLIN automation completes → certificate arrives
### 1.3 CRTC Pipeline Remaining Stubs `[CRTC]`
- [ ] **Anytime Mailbox automation hardening** — provider has no API, but Playwright flow now exists. Validate selectors against live UI and stabilize OTP retrieval via Carbonio IMAP, then keep admin handoff as fallback.
- [ ] **CCTS registration** — Step 11 is a stub. Research CCTS online registration form, implement Playwright or keep as admin ToDo with instructions.
- [ ] **eSign workflow for CRTC letter** — Step 6 generates the DOCX letter but customer signature is not collected. Use ERPNext built-in eSign (drawing pad). Wire: generate letter → send for eSign → on signed → continue pipeline.
- [ ] **CRTC letter email submission** — After eSign, email the signed letter to CRTC from the customer's provisioned `.ca` address (`regulatory@{domain}.ca`). Requires IMAP send via HestiaCP provisioned mailbox.
- [ ] **BITS affidavit** — BITS requires a notarized affidavit confirming the company is a US carrier (or Canadian equivalent). Provider: NotaryLive ($59/mo platform + $23/session). Implement: generate affidavit DOCX → send NotaryLive session invite → on completion → attach to binder.
- [ ] **Order confirmation email** — After payment, send customer a confirmation email with order summary, expected timeline, and next steps checklist. Currently nothing is sent at payment time.
- [ ] **Branded HTML email templates** — 15 ERPNext Email Notifications are plain text. Design and import HTML templates (header logo, PW brand colors, footer with unsubscribe).
### 1.4 Customer Portal Auth `[CRTC]`
Portal pages (`/portal/domain-search`, `/portal/manage-services`) exist but have no authentication. Any URL visitor can access any order.
- [ ] Implement portal authentication via ERPNext portal login (ERPNext has a built-in portal user system)
- [ ] Generate a signed JWT or ERPNext portal token and embed in the email links sent to customers
- [ ] Add auth middleware to all `/portal/*` API routes — validate token, scope to customer's own orders only
- [ ] Add session expiry (24h) and re-send link flow
### 1.5 End-to-End CRTC Test `[CRTC]`
- [ ] Place a real CRTC order (numbered company, test customer)
- [ ] Walk through all 12 pipeline steps
- [ ] Confirm: DID provisioned, COLIN automation runs, domain registered, CRTC letter generated + eSigned, binder compiled, MinIO upload, customer emails received
- [ ] Document any failures and fix before first real customer order
---
## Track 2 — US Formation (Second Revenue Stream)
### 2.1 Wyoming End-to-End `[FORMATION]`
WY is the highest-priority state — selectors verified on name search, no CAPTCHA, cheapest filing fee.
- [ ] Implement WY filing automation: walk the WYO SOS filing wizard step-by-step with Playwright, map all form field selectors
- [ ] Wire payment step: WY SOS accepts credit card — use `relay-filing-card`
- [ ] Test: place a real WY LLC order, confirm name search works, confirm filing completes, confirm confirmation number saved to DB
- [ ] Wire formation worker to create ERPNext Formation Order + Sales Invoice on order receipt
- [ ] Wire formation worker to send order confirmation email after payment
### 2.2 Colorado End-to-End `[FORMATION]`
CO name search is already working (Socrata API). Need filing automation.
- [ ] Research CO SOS filing wizard (sos.state.co.us), map selectors
- [ ] Implement CO LLC filing automation
- [ ] Test end-to-end
### 2.3 Server-Side Fee Validation `[FORMATION][PLUMBING]`
Currently the API trusts client-submitted `state_fee_cents`. This is a billing vulnerability.
- [ ] Add server-side lookup: on order receipt, look up `state_fee_cents` from `state_filing_fees` DB table using `state` code
- [ ] Reject any order where client-submitted fee does not match DB value
- [ ] Audit and fix the 12+ known fee discrepancies between the frontend hardcoded array and DB (identified last session)
### 2.4 Operating Agreement + EIN `[FORMATION]`
- [ ] Test operating agreement DOCX generation end-to-end (template → DocxBuilder → PDF → MinIO)
- [ ] Test EIN obtainment worker (IRS Playwright) on a real WY entity after filing
- [ ] Confirm both documents are attached to the ERPNext Formation Order and emailed to customer
### 2.5 DocServer (Windows VM) `[FORMATION][INFRA]`
LibreOffice fallback produces lower-quality PDFs. Office 2021 on Windows is required for production-quality DOCX→PDF conversion.
- [ ] Provision Windows Server 2022 VM in Proxmox (2 vCPU, 4 GB RAM, 40 GB SSD)
- [ ] Install Microsoft Office 2021
- [ ] Deploy DocServer Flask app on port 5050
- [ ] Configure `DOCSERVER_URL` env var to point workers at Windows VM
- [ ] Verify: workers use DocServer when available, fall back to LibreOffice when not
### 2.6 Remaining State Adapters `[FORMATION]`
Priority order based on formation volume. Each requires: portal inspection, selector extraction, Playwright implementation, payment wiring.
- [ ] Delaware (DE) — CAPTCHA. Integrate 2captcha or AntiCaptcha solving service first.
- [ ] Florida (FL) — High demand. Playwright needed, no CAPTCHA expected.
- [ ] Texas (TX) — SOSDirect account needed for search. Get account first.
- [ ] Nevada (NV) — WAF. Use stealth Playwright (playwright-extra + puppeteer-stealth).
- [ ] Utah (UT) — Name search works without login. Filing needs UtahID OAuth.
- [ ] New Mexico, Ohio, Montana — Untested, research portals.
- [ ] Remaining 37 states — Batch: inspect portals, extract selectors, implement in priority order.
---
## Track 3 — Infrastructure & Ops
### 3.1 Production Deployment `[INFRA][BLOCKER]`
The rsync to production timed out. Get the current codebase deployed.
- [ ] Fix rsync: run with `--timeout=30` and `--compress`, or use a staged approach (`tar | ssh`)
- [ ] On server: `docker compose build && docker compose up -d`
- [ ] Update ERPNext Docker image: rebuild `performancewest-erpnext:latest` with latest `frappe_ca_registry` + `performancewest_erpnext` changes
- [ ] Run any pending DB migrations on production
### 3.2 Environment Variables `[INFRA]`
Several env vars are not yet set in production `.env`.
- [ ] `PORKBUN_API_KEY` / `PORKBUN_SECRET_KEY`
- [ ] `FLOWROUTE_ACCESS_KEY` / `FLOWROUTE_SECRET_KEY`
- [ ] `HESTIA_HOST` / `HESTIA_USER` / `HESTIA_PASSWORD`
- [ ] `SHKEEPER_API_KEY`
- [ ] `ADYEN_API_KEY` / `ADYEN_MERCHANT_ACCOUNT` / `ADYEN_CLIENT_KEY` (when account approved)
- [ ] `DOCSERVER_URL` (when Windows VM is provisioned)
- [ ] `CUSTOMER_JWT_SECRET` (for portal auth)
### 3.3 Monitoring & Alerts `[INFRA]`
- [ ] Set up UptimeRobot (free) to monitor: performancewest.net, api.performancewest.net, crm.performancewest.net, pay.performancewest.net
- [ ] Configure alert email to `ops@performancewest.net`
- [ ] Set up weekly automated DB backup to MinIO (pg_dump → minio/backups/)
- [ ] Verify ERPNext daily backup is configured and uploading to MinIO
---
## Track 4 — Payment & Billing Completion
### 4.1 Bundle / Compliance Checkout `[PLUMBING]`
The Express API returns `null` for bundle and compliance service checkout. These are broken.
- [ ] Implement bundle checkout in `api/src/routes/checkout.ts`: look up bundle from `service_bundles` table, create Sales Order + Invoice with correct line items and 20% bundle discount
- [ ] Implement compliance service checkout (CCPA audit, FLSA audit, etc.): create Sales Invoice with correct item and turnaround date
- [ ] Test both flows end-to-end through payment
### 4.2 Subscription / Renewal Billing `[PLUMBING]`
Annual renewals (RA $99/yr ($49 WY), Annual Report $99/yr, CRTC Maintenance $349/yr) exist as ERPNext Subscription Plans but the renewal worker is not wired to trigger them.
- [ ] Wire `renewal_handler.py`: on subscription due date (from Compliance Calendar), create ERPNext Sales Invoice + Payment Request, send renewal email with payment link
- [ ] Test: manually trigger a renewal for a test customer, confirm invoice created, confirm email sent, confirm payment marks subscription renewed
### 4.3 Refund Flow `[PLUMBING]`
- [ ] Verify ERPNext Credit Note flow works end-to-end
- [ ] Test: issue a partial refund on a test invoice, confirm Adyen processes the refund, confirm customer email is sent
- [ ] Document refund policy in customer-facing portal
---
## Track 5 — Docs Update
All 15 docs have stale content. These need to be rewritten to match current state before bringing on any contractors or making architectural decisions.
**Critical (do first):**
- [x] `docs/architecture.md` — Replaced Mautic with Listmonk. Added DocServer, workers, portal. Updated container count to 15.
- [x] `docs/go-live-todo.md` — Marked completed items. Added multi-province priority 11. Updated pricing.
- [x] `docs/formation-system.md` — Updated BC section with BITS/CCTS/GCKey/compliance. Updated DocServer.
- [x] `docs/crm.md` — Replaced Mautic Integration → Listmonk. Added CRTC campaign.
**High priority:**
- [x] `docs/product-facts.md` — Added Canada annual maintenance ($349), consulting ($75/hr), Canadian formation (C$449), maintenance bundles ($179/yr). Updated CRTC pipeline to 14 steps.
- [x] `docs/billing.md` — Added renewal billing, compliance calendar billing, maintenance bundles, Canadian formation pricing.
- [x] `docs/infrastructure.md` — Replaced Mautic/MySQL with Listmonk. Updated container count to 15. Added portal nginx config.
**Medium priority:**
- [ ] `docs/marketing.md` — Add FCC RMD as primary lead gen channel. Add Listmonk drip campaign details. Add 3 campaign descriptions.
- [x] `docs/state-automation-status.md` — Updated BC section with all new capabilities + GCKey automation table.
- [ ] `docs/document-generation.md` — Update DocServer section (MinIO transport, not HTTP). Add template list.
---
## Track 6 — frappe_registry Migration (Future)
This is a significant refactor — ~24 hours of work. Do not start until CRTC pipeline is working end-to-end and at least WY formation is live.
- [ ] Rename `frappe_ca_registry` → `frappe_registry`
- [ ] Generalize `CA Filing Request` DocType to `Registry Filing Request` (55 jurisdictions)
- [ ] Add `Registry Settings` DocType: NWRA defaults, per-state RA override, CA mailbox config
- [ ] Move 51 US state adapters from `scripts/formation/states/` into Frappe app
- [ ] Add extra-provincial registration support (10 Canadian provinces)
- [ ] Add foreign state qualification support (US foreign entity)
- [ ] Define `BaseAdapter` interface with auto-discovery by jurisdiction code
- [ ] Build fee scraper framework:
- [ ] `base_scraper.py` — abstract scraper class with rate limiting, retry, user-agent rotation
- [ ] `pdf_scraper.py` — Tesseract OCR for scanned fee schedule PDFs, pdfplumber for text PDFs
- [ ] `fee_change_detector.py` — compares scraped values against DB, generates diff report
- [ ] Admin email alert when any fee changes (does NOT auto-update — human review required)
- [ ] Monthly cron job in workers container (`0 6 1 * *` — 1st of each month, 6am)
- [ ] Store scraped results in `state_fee_scrape_history` table with timestamp + source URL + old/new values
- [ ] Implement US state fee scrapers (51 jurisdictions):
- [ ] Tier 1 (top 10 by formation volume): WY, DE, FL, TX, NV, CA, CO, NY, GA, IL
- [ ] Tier 2 (remaining 41 states + DC)
- [ ] Handle: annual report fees, franchise taxes, business license fees, privilege taxes, personal property returns
- [ ] Reference: `docs/state-annual-fees-complete.md` for current verified values + source URLs
- [ ] Implement Canadian province fee scrapers (10 provinces):
- [ ] BC, AB, ON, QC, MB, SK, NS, NB, PE, NL
- [ ] Scrape in CAD, convert to USD via `fx.ts` Bank of Canada rate + 10% buffer
- [ ] Fix fee data integrity: DB as single source of truth, frontend fetches from API, server-side validation (see 2.3)
---
## Launch Readiness Checklist
Before accepting the first paying customer:
- [ ] ERPNext payment gateways configured (Track 1.1)
- [ ] CRTC end-to-end test passes (Track 1.5)
- [ ] Portal authentication implemented (Track 1.4)
- [ ] Order confirmation email sends after payment (Track 1.3)
- [ ] Production deployed with current codebase (Track 3.1)
- [ ] All env vars set in production (Track 3.2)
- [ ] UptimeRobot monitoring configured (Track 3.3)
Formation orders can follow ~2 weeks after CRTC is live (WY first).
---
## Open Questions / Decisions Needed
| Question | Context | Deadline |
|----------|---------|----------|
| Adyen account approval status? | Without Adyen, card/ACH payments are blocked. Only crypto works. | Before first customer |
| NotaryLive account — go or no-go? | $59/mo + $23/session for BITS affidavit notarization. Alternative: partner with a Canadian notary. | Before first CRTC delivery |
| Anytime Mailbox credential handoff policy? | Provider confirmed no API; Playwright signup uses shared inbox OTP. Decide whether to bootstrap with `filings@performancewest.net` then transfer to client, or require client email from the start. | Before first customer |
| Portal auth strategy? | ERPNext portal login vs. signed JWT in email link. Signed JWT is simpler, no password needed. | Before first customer uses portal |
| Canadian accountant? | 3 hours free accounting support is promised in the CRTC package. Need to onboard a freelance Canadian accountant. | Before first delivery |

232
docs/product-facts.md Normal file
View file

@ -0,0 +1,232 @@
# Performance West Inc. — Product Facts for LLM Responses
This document is the authoritative source of truth for what Performance West actually does and does not
provide. All monitor scripts load this at runtime to ensure accurate, honest replies. Never claim a
capability that is not listed here.
**Last updated:** 2026-04-05
**Website:** https://performancewest.net
**Phone:** 1-888-411-0383
**MCP Server:** `npx @performancewest/mcp-server` (10 tools for AI agents)
---
## Company Overview
- **What it is:** Compliance consulting firm offering fixed-price regulatory compliance services
- **What it is NOT:** A law firm. We do NOT provide legal advice, legal representation, or attorney-client relationships
- **Location:** 525 Randall Ave Ste 100-1195, Cheyenne, WY 82001
- **Entity:** Performance West Inc. (Wyoming corporation)
- **Pricing model:** Fixed-price services with defined deliverables and turnaround times (no billable hours)
---
## Payment Methods
| Method | Surcharge | Notes |
|--------|-----------|-------|
| ACH Direct Debit | 0% | Recommended — lowest cost ($0.40 flat fee absorbed by us) |
| Credit / Debit Card | 3% | Visa, Mastercard, Amex + Apple Pay + Google Pay |
| Klarna (Pay in 4) | 5% | ~$975/mo x 4 for CRTC package |
| Cash App Pay | 3% | |
| Amazon Pay | 3% | |
| Crypto (BTC/ETH/USDC/USDT/MATIC/TRX/BNB/LTC/DOGE) | 0% | Self-hosted SHKeeper — zero fees |
All payments route through ERPNext via Adyen (cards/ACH/Klarna/CashApp/AmazonPay) or SHKeeper (crypto).
---
## Discount & Referral Rules
- **Service bundles:** 20% off when purchasing all services in a category
- **Discount codes** apply to service fees ONLY — state fees and registered agent fees are NOT discountable in bundles
- **RA fees** are NOT discountable in bundles, but YES with discount codes
- **Sales agent referral program:** Agents receive a REF-XXXXX code. Client gets 5% off service fee; agent earns flat commission ($300 CRTC, $50 formation, $100 bundle)
- Commission paid 14 days after order delivery via Relay ACH
---
## Services
### Canada CRTC Telecom Carrier Package — $3,899 USD (Flagship Service)
**Turnaround:** 6–10 weeks
**What's included:**
- Provincial corporation incorporation (BC or Ontario — customer selects)
- CRTC domestic telecom carrier registration
- BITS (Basic International Telecommunications Service) international carrier registration
- .ca domain name + business email + web hosting provisioned via HestiaCP
- Canadian DID (phone number) via Flowroute
- CCTS (Commission for Complaints for Telecom-television Services) registration
- Corporate binder with all formation and regulatory documents
- Canadian business banking referral
- 3 hours of free Canadian accounting support included
**Government fees (passed through at cost, converted CAD→USD daily):**
- BC: ~C$350 (numbered), ~C$380 (named), ~C$390 (numbered + trade name)
- Ontario: ~C$360 (numbered), ~C$385 (named), ~C$400 (numbered + trade name)
**Annual maintenance:** $349 USD/yr
- Registered office mailbox (Anytime Mailbox) renewal
- Provincial annual report/return filing
- CRTC compliance monitoring (17-entry compliance calendar with automated reminders)
- .ca domain renewal + hosting + email
- Canadian DID renewal
- CCTS membership renewal
- Annual Telecommunications Survey (REP-T/T1) preparation assistance
**Consulting:** $75 USD/hr (ad-hoc CRTC/BITS questions beyond included scope)
**Add-on — FCC 499-A + STIR/SHAKEN for Canadian carriers:** $999 USD
- For Canadian carriers that also need US interconnection compliance
- Includes 499-A filing + SPC token + STI-CA integration
- CAN do: Incorporate in BC or Ontario, register with CRTC and BITS, provision .ca domain/email/hosting, obtain Canadian DID, register with CCTS, provision GCKey account for CRTC filings, assemble corporate binder, create 17-entry compliance calendar with automated renewal tracking, refer to Canadian banking partner, file annual provincial reports, prepare ATS survey data, maintain CRTC compliance
- CANNOT do: Provide Canadian legal advice, represent you before CRTC in proceedings, guarantee CRTC approval timelines, provide tax advice, act as your Canadian legal counsel, file tax returns (T2/GST/T4 — client's accountant handles)
### Telecom Compliance (US)
- **FCC Form 499-A Filing Support** — $799/annual filing, 5–7 business days
- CAN do: Prepare and file 499-A, review prior-year filings, handle USAC correspondence
- CANNOT do: Represent you in FCC proceedings, provide legal defense
- **STIR/SHAKEN Implementation** — Custom quote, 2–4 weeks
- CAN do: Obtain SPC token, configure CA integration, implement signing/verification, file RMD entry
- CANNOT do: Modify your switch software, provide ongoing network engineering
- **IPES & ISP Registrations** — $1,299/registration package, 2–3 weeks
- CAN do: FCC CORES registration, FRN, Form 477, state registrations, NECA membership
- CANNOT do: Obtain spectrum licenses, build network infrastructure
- **Telecom Database Management** — $499/quarter
- CAN do: Manage NECA, SMS/800, LERG, OCN records
- CANNOT do: Provision telephone numbers, manage network routing
- **State PUC/PSC Filings** — $399/state, 2–8 weeks
- CAN do: File registrations, annual reports, compliance certifications in all 50 states
- CANNOT do: Represent you in state regulatory hearings
### Employment Compliance *(hidden in production — available in dev only)*
- **FLSA / Wage & Hour Audit** — $1,499 (up to 50 employees), 5–7 business days
- CAN do: Review classifications, audit overtime, analyze breaks/off-clock work, check recordkeeping
- CANNOT do: Provide legal defense, represent in DOL proceedings, calculate exact back-pay owed
- **Contractor Classification Review** — $499/contractor, 3–5 business days
- CAN do: Apply IRS 20-factor test, DOL economic reality test, state tests, provide risk assessment
- CANNOT do: Provide legal opinion, guarantee classification outcome, represent in IRS audit
- **Employee Handbook Review** — $999, 5–7 business days
- CAN do: Review against federal/state laws, identify gaps, provide revision recommendations
- CANNOT do: Provide legal interpretation, draft legally binding documents, give legal opinions
- **Workplace Policy Development** — Custom quote, 2–3 weeks
- CAN do: Draft custom policies for your business, cover all operating states
- CANNOT do: Create legally binding employment contracts, provide legal advice
### Data Privacy
- **CCPA/CPRA Compliance Audit** — $2,499, 7–10 business days
- CAN do: Map data practices, review notices, test opt-out, audit vendor contracts, assess security
- CANNOT do: Provide legal interpretation of CCPA, represent in CPPA proceedings
- **Privacy Policy Generation & Review** — $499, 5–7 business days
- CAN do: Draft comprehensive privacy policy, create CCPA disclosures, cookie policies
- CANNOT do: Provide legal opinions on edge cases, GDPR compliance
- **Data Mapping & Inventory** — Custom quote, 1–3 weeks
- CAN do: Catalog data by category, map flows, document vendors, create visual diagrams
- CANNOT do: Implement technical data controls, conduct penetration testing
- **Breach Response Planning** — $1,999, 2–3 weeks
- CAN do: Develop response plan, map notification obligations, draft templates, run tabletop exercises
- CANNOT do: Handle actual breach response, provide legal counsel during breach
### TCPA Compliance
- **SMS/Call Consent Audit** — $1,299, 5–7 business days
- CAN do: Review consent practices, check one-to-one consent, audit lead gen, test opt-out
- CANNOT do: Provide legal defense in TCPA lawsuits, guarantee compliance
- **DNC List Compliance Review** — $799, 3–5 business days
- CAN do: Review scrubbing procedures, audit internal DNC, check state compliance
- CANNOT do: Scrub your calling lists, manage your DNC operations
- **Marketing Campaign Compliance Review** — $599/campaign, 2–3 business days
- CAN do: Review consent, content, opt-out, timing, disclosure, pre-launch certification
- CANNOT do: Send campaigns for you, monitor ongoing compliance
### Corporate Services (US)
- **Business Formation — Basic** — $179, 3–5 business days
- CAN do: Evaluate entity type, file formation documents with the state
- CANNOT do: Provide tax advice, guarantee tax treatment
- **Business Formation — Complete** — $399, 3–5 business days
- Includes: EIN obtainment ($49 value), Operating Agreement ($99 value), 1st year Registered Agent ($99 value)
- CAN do: Everything in Basic + obtain EIN, draft operating agreement, set up registered agent
- CANNOT do: Provide tax advice, guarantee tax treatment, create shareholder agreements
- **State Registration & Foreign Qualification** — $249/state, 1–4 weeks
- CAN do: Determine requirements, file applications, obtain certificates, set up registered agent
- CANNOT do: Determine tax nexus, file state tax returns
- **Annual Report Filing** — $99/state/year
- CAN do: Track deadlines, prepare and file reports, maintain good standing
- CANNOT do: Prepare tax returns, file franchise taxes
- **Registered Agent Service** — $99/state/year (Wyoming: $49/year)
- CAN do: Maintain physical address, receive/forward legal notices, same-day forwarding
- CANNOT do: Respond to lawsuits, provide legal representation
- **Free DID** — Included with any formation + RA renewal (stub — not yet active)
- A local US phone number provided free when you form a company and maintain RA service
- **US Formation Maintenance Bundle** — $179/year
- Includes: Annual Report filing ($99 value) + Registered Agent renewal ($99 value) + compliance calendar monitoring
- CAN do: Track all deadlines, file annual reports, maintain RA, alert on compliance changes
- CANNOT do: File tax returns, provide legal representation
### Corporate Services (Canada) — Standalone Formation (Not CRTC)
- **Canadian Formation** — C$449 + provincial government fees (BC ~C$350, ON ~C$360), 3–7 business days
- Includes: Province incorporation (numbered or named), organizational minutes, corporate binder (digital PDF), compliance calendar with automated reminders
- AMB registered office mailbox billed separately (annual, ~C$96-240/yr depending on city — required for incorporation, we set it up)
- CAN do: Incorporate in BC or Ontario, set up registered office, draft organizational minutes, compile binder, track compliance deadlines
- CANNOT do: Provide Canadian tax advice, file Canadian tax returns, provide legal advice
- No Canadian residency required for directors — foreigners welcome (US passport, EU passport, any valid government ID)
- Banking: Venn.ca accepts non-resident directors (confirmed — business address uses AMB mailbox)
- **Add-on: CRA Business Number** — $49
- CAN do: Register your corporation with CRA for a Business Number (BN)
- CANNOT do: File GST/HST returns, handle CRA correspondence, provide tax advice
- **Add-on: Named Company** — government fee only (BC: C$30, ON: varies)
- Name reservation with the provincial registry
- **Free DID** — Included with formation + RA renewal (stub — not yet active)
- A local Canadian phone number provided free when you form a company and maintain registered office
- **CA Formation Maintenance Bundle** — $179/year
- Includes: Annual Return/Report filing ($99 value) + AMB/RA renewal ($99 value) + compliance calendar monitoring
- CAN do: Track all deadlines, file annual returns, maintain registered office, alert on changes
- CANNOT do: File tax returns, provide accounting services, provide legal representation
- Government fees passed through at cost (converted at Bank of Canada daily rate + 10% buffer)
- No Canadian residency required for directors (BC or Ontario)
- Separate product from CRTC Carrier Package — no telecom registration included
---
## Free Tools (Lead Magnets)
- **Formation Guide** — /tools/formation-guide (interactive entity selection walkthrough)
- **Contractor Classification Quiz** — /tools/contractor-quiz (10 yes/no questions, instant result)
- **Privacy Policy Compliance Check** — /tools/privacy-check (8-item self-assessment)
- **TCPA SMS Compliance Check** — /tools/tcpa-check (8-item assessment with penalty calculator)
---
## MCP Server for AI Agents
- **Package:** `npx @performancewest/mcp-server`
- **Transport:** stdio
- **10 tools available:** service lookup, pricing queries, state fee lookup, formation guide, contractor quiz, privacy check, TCPA check, order status, consultation booking, knowledge base search
- AI agents can integrate this to answer Performance West questions programmatically
---
## Reply Guidelines for LLM Monitors
1. **Only mention a service if it directly addresses the person's problem**
2. **Always note we provide compliance consulting, NOT legal advice**
3. **Be specific about pricing** — mention the exact fixed price and any surcharges
4. **Reference the free tools** when the person is exploring/unsure
5. **Be honest about limitations** — we can't represent them in court, can't give legal opinions
6. **SKIP if the question requires legal advice or representation**
7. **SKIP if the person already has a lawyer handling it** (don't compete with attorneys)
8. **Sign off as Justin**
9. **Never claim we are cheaper or better than hiring a lawyer — different service**
10. **Mention the turnaround time** — it differentiates us from attorneys
11. **For Canadian carrier inquiries, lead with the CRTC package** — it is the flagship offering
12. **Mention payment flexibility** — crypto (0% surcharge), ACH (0%), card available with 3% surcharge, Klarna Pay in 4 available with 5% surcharge
13. **For referral agents**, provide their REF-XXXXX code details: client gets 5% off, agent earns flat commission
14. **Do NOT mention employment services** — they are hidden in production and not currently offered publicly

273
docs/production-runbook.md Normal file
View file

@ -0,0 +1,273 @@
# Production Runbook — FCC Filing + Treasury Stack
This runbook covers what an operator has to provision before the FCC filing
automation and crypto-treasury pipeline can run in production. Each section
lists the specific env vars, portal credentials, and one-time setup steps.
---
## 1. Admin dashboard auth (Blocker 1)
The admin dashboard and every `/api/v1/admin/*` endpoint is guarded by a JWT
signed with `ADMIN_JWT_SECRET`. The API refuses to boot in production if the
secret is still the built-in placeholder.
### One-time setup
1. Generate a strong random secret:
openssl rand -base64 48
2. Set on the API process (Docker / systemd env file):
ADMIN_JWT_SECRET=<paste output>
3. Provision an admin user:
psql "$DATABASE_URL" <<SQL
INSERT INTO admin_users (username, password_hash, display_name, email, active)
VALUES (
'justin',
crypt('<strong-password>', gen_salt('bf', 12)),
'Justin Tyson',
'ops@performancewest.net',
TRUE
);
SQL
(Use `bcryptjs` from Node to hash if `pgcrypto` is unavailable.)
4. Verify login:
curl -s -X POST https://api.performancewest.net/api/v1/admin/login \
-H 'Content-Type: application/json' \
-d '{"username":"justin","password":"<strong-password>"}'
### Related env vars
- `ADMIN_JWT_SECRET` — JWT signing secret. Required in production.
- `WEBHOOK_SECRET` — shared secret for ERPNext → API formation/CRTC webhooks.
- `SHKEEPER_API_KEY` — header used by SHKeeper to authenticate its callback.
- `STRIPE_WEBHOOK_SECRET` — verified by Stripe's HMAC signature check.
The startup guard in `api/src/config.ts` (`refuseInsecureProduction`) blocks
boot if any of the above are unset or still set to `change-this-in-production`.
---
## 2. USAC E-File storage state (Blocker 2)
USAC's E-File portal (https://www2.usac.org/cr/) requires a logged-in session
cookie to submit Form 499-A. We drive it via Playwright. The filer's session
(login cookies + MFA state) must be provisioned once per filing entity.
### One-time setup per telecom entity
1. Log in manually to E-File using the entity's FRN + the assigned
E-File administrator account.
2. Complete MFA (USAC MFA is TOTP-based as of 2026).
3. Export the session state to MinIO:
bucket: `playwright-storage`
key: `usac/<telecom_entity_id>/storage_state.json`
The filer reads this key at the start of each `fcc-499a` /
`fcc-499-initial` job. If missing or expired, the handler logs a
ToDo for the admin.
4. Renewal: USAC session expires ~14 days idle; the filer re-uses it as long
as it's valid, and the scheduled `usac_session_refresh` cron (every
7 days) re-logs in and re-exports. The cron requires a stored TOTP
secret:
ERPNext Sensitive ID: `usac-totp-<telecom_entity_id>`
### Env vars
- `PLAYWRIGHT_STORAGE_BUCKET=playwright-storage`
- `USAC_MFA_VIA=totp` (alternative: `sms` — not supported in automation)
### Related docs
- See `scripts/workers/services/form_499a.py` for the filer entry point.
- See `docs/fcc-references/499a-filing.md` for screen-by-screen form notes.
---
## 3. Relay debit card (Blocker 4)
Filing portal charges settle on `RELAY_FILING_CARD_ID` — a Relay debit card
whose balance is the Relay business account balance. Once Bridge offramps
crypto USD to Relay, the same balance funds the card.
### One-time setup
1. In the Relay dashboard → Cards → Issue card.
2. Virtual, unlimited (no per-transaction cap); lock to "Online purchases only".
3. Whitelist MCCs 9399 (government services) and 7372 (computer services).
4. Copy the card's internal id from Relay (visible in URL of the card detail
page) and set:
RELAY_FILING_CARD_ID=<card-id>
5. Fallback chain in `scripts/workers/relay_integration.py`:
CRYPTO_FILING_CARD_ID → STRIPE_FILING_CARD_ID →
PAYPAL_FILING_CARD_ID → RELAY_FILING_CARD_ID
For crypto-funded orders, set `PREFERRED_FUNDING_CARD=RELAY_FILING_CARD_ID`
so the Playwright filer charges Relay first.
### Statement reconciliation
- Daily: `scripts/workers/relay_deposit_monitor.py` parses Relay IMAP alerts
into `relay_deposits`. Offramp deposits have `source_kind='offramp_bridge'`;
vendor charges appear as outgoing card transactions.
- Monthly: export Relay statement CSV, import into `bookkeeping/imports/`, and
reconcile against `filing_fee_reservations.status='spent'` rows.
---
## 4. Webhook → worker dispatch chain
Confirmed wiring as of this commit:
1. `POST /api/v1/webhooks/stripe` → verifies Stripe HMAC →
`handlePaymentComplete(order_id, order_type, session_id)`.
2. `POST /api/v1/webhooks/shkeeper` → verifies `X-Shkeeper-Api-Key` →
enqueues `crypto_payment_jobs` + calls `handlePaymentComplete`.
3. For compliance orders, `handlePaymentComplete`:
- Flips ERPNext Sales Order `workflow_state` to `Service Queued`.
- **Dispatches directly to the worker** at `${WORKER_URL}/jobs` with
`action=process_compliance_service` (no dependency on an ERPNext
Webhook fixture).
4. `POST /api/v1/webhooks/service/queued` (ERPNext-driven) remains as a
backup path — if you configure a Frappe Webhook on Sales Order
`workflow_state → Service Queued`, it fires the same worker action.
5. Worker `job_server.py:748` `handle_process_compliance_service` routes
to the handler from `SERVICE_HANDLERS[service_slug]`.
### Env vars
- `WORKER_URL=http://workers:8090` (internal Docker network name)
- `WEBHOOK_SECRET=<shared-with-ERPNext>`
- `SHKEEPER_API_KEY=<configured-in-SHKeeper-admin>`
- `STRIPE_WEBHOOK_SECRET=whsec_...` (from dashboard.stripe.com/webhooks)
### Verification
After deploying, confirm with:
# trigger a compliance test checkout
# then tail the API logs for these three lines per order:
[checkout] Payment confirmed: compliance CO-xxx via <method>
[checkout] Advanced compliance Sales Order SAL-xxx to Service Queued
[checkout] Worker dispatched: CO-xxx (<service-slug>)
# and the worker logs for:
[worker] process_compliance_service: CO-xxx (<handler>)
---
## 5. Crypto treasury env (manual mode)
Until Bridge is approved, treasury runs in **manual** mode — admin approves
every offramp before it touches Bridge.
CRYPTO_TREASURY_MODE=manual # default; flip to "auto" when Bridge is live
# Bridge (when approved):
BRIDGE_API_KEY=
BRIDGE_API_URL=https://api.bridge.xyz
BRIDGE_RELAY_EXTERNAL_ACCOUNT_ID=
BRIDGE_DEVELOPER_FEE_USD=0
RELAY_BANK_MEMO_PREFIX=PW-ORDER-
MAX_SLIPPAGE_BPS=300
# Cold wallet (Bridge approval not required to sweep — hardware wallet is live)
COLD_WALLET_BTC_ADDR=
COLD_WALLET_ETH_ADDR=
COLD_WALLET_USDC_ADDR=
COLD_WALLET_USDT_ADDR=
COLD_WALLET_HOT_FLOAT_USD_CENTS=50000
COLD_WALLET_AUTO_SWEEP_CEILING_USD_CENTS=500000
CRYPTO_SWEEP_ADMIN_EMAIL=ops@performancewest.net
In manual mode the `crypto_payment_worker` parks every `received` job at
`state='manual'` and an admin approves via
`POST /api/v1/admin/crypto-payments/:order_id/retry-offramp`.
---
## 6. Scheduled worker jobs (systemd timers)
Deployed by the `worker-crons` ansible role
(`infra/ansible/roles/worker-crons/`). Each timer runs
`docker compose exec -T workers python -m <module>` on its schedule.
| Timer | Cadence | Module |
|---|---|---|
| `pw-usf-factor-monitor.timer` | daily 09:00 CT | `scripts.workers.usf_factor_monitor` |
| `pw-deminimis-factor-check.timer` | daily 03:00 UTC | `scripts.workers.deminimis_factor_check` |
| `pw-cold-wallet-sweep.timer` | every 30 min | `scripts.workers.cold_wallet_sweeper` |
| `pw-crypto-payment-worker.timer` | every 60 s | `scripts.workers.crypto_payment_worker` |
| `pw-relay-deposit-monitor.timer` | every 5 min | `scripts.workers.relay_deposit_monitor` |
| `pw-commission-worker.timer` | daily 02:00 UTC | `scripts.workers.commission_worker` |
| `pw-renewal-worker.timer` | daily 04:00 UTC | `scripts.workers.renewal_worker` |
| `pw-cdr-retention.timer` | daily 05:00 UTC | `scripts.workers.cdr_retention_sweeper` |
| `pw-cdr-unlock-nudge.timer` | daily 10:00 CT | `scripts.workers.cdr_unlock_nudge` |
| `pw-payment-reminder.timer` | daily 11:00 CT | `scripts.workers.payment_reminder` |
| `pw-fcc-rmd-removed.timer` | weekly Wed 08:00 CT | `scripts.workers.fcc_rmd_removed_scraper` |
### Verification
# list active timers
systemctl list-timers 'pw-*'
# tail a specific job's history
journalctl -u pw-usf-factor-monitor.service --since '1 day ago'
# trigger a job ad-hoc for testing
systemctl start pw-deminimis-factor-check.service
### Adding a new cron
Add an entry to `infra/ansible/roles/worker-crons/defaults/main.yml`:
```yaml
- name: pw-my-new-job
description: What it does
module: scripts.workers.my_new_job
on_calendar: "*-*-* 06:00:00 UTC"
persistent: true # run on boot if missed
```
Then re-run `ansible-playbook playbooks/site.yml`.
---
## 7. Smoke tests
Run before every release:
# Service handler registry + CPNI/CALEA variant mapping
docker compose exec workers python -m scripts.tests.test_cpni_calea_variants
# Form 499 Initial handler guards
docker compose exec workers python -m scripts.tests.test_form_499_initial_smoke
Both return exit 0 on pass. Wire into CI.
---
## 8. Boot-time health checks
The API and worker services each expose:
- `GET /health` — returns 200 when config loaded + DB reachable.
- `GET /health/deep` — returns 200 only when ERPNext, MinIO, and the worker
message channel all respond.
Set these as the Docker HEALTHCHECK / K8s liveness probe so deploys fail fast
when secrets are missing.

181
docs/relay-integration.md Normal file
View file

@ -0,0 +1,181 @@
# Relay Financial Integration
**Last updated:** 2026-03-19
## Overview
Relay (relayfi.com) is our business banking platform. We use a dedicated
Relay virtual debit card to pay state filing fees during automated business
formation. Relay does NOT have a public developer API, so integration is
via encrypted card storage + Playwright automation + Plaid for read-only
transaction data.
## Architecture
```
ERPNext (Sensitive ID) Playwright State Portal
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Relay card details│────►│ Formation worker │────►│ Payment form │
│ (AES encrypted) │ │ enters card into │ │ Card charged │
│ card_number │ │ state portal form │ │ Filing confirmed │
│ exp_month/year │ └──────────────────┘ └──────────────────┘
│ cvv │ │
│ billing_zip │ ▼
└──────────────────┘ ┌──────────────────┐
│ filing_payments │
│ table (PostgreSQL)│
│ card_last4, amount│
│ confirmation # │
└──────────────────┘
│
▼ (reconcile)
┌──────────────────┐
│ Relay dashboard │
│ or Plaid read-only│
│ transaction match │
└──────────────────┘
```
## Card Details Storage
Card details are stored in ERPNext's **Sensitive ID** DocType using the
Frappe Password fieldtype, which provides AES encryption at rest.
### Setup (One-time)
1. Log into ERPNext at crm.performancewest.net
2. Navigate to Sensitive ID → New
3. Set:
- **Name:** `relay-filing-card`
- **ID Type:** `DEBIT_CARD`
- **Encrypted Value:** (paste JSON below)
```json
{
"number": "4000123456789012",
"exp_month": "12",
"exp_year": "28",
"cvv": "123",
"name": "Performance West Inc",
"zip": "82001"
}
```
4. Save — the value is encrypted by Frappe's Password field
### Runtime Flow
1. Job server receives a `file_entity` job
2. `relay_integration.populate_order_payment()` loads card from ERPNext
3. Card details are held in memory only (never logged, never written to disk)
4. Playwright enters card details into state portal payment form
5. After filing, card details are cleared from memory
6. `record_filing_payment()` logs the payment (card_last4 only) for reconciliation
## Payment Reconciliation
After each filing, a record is created in the `filing_payments` table:
| Field | Value |
|-------|-------|
| formation_order_id | Links to the order |
| state_code | Which state was paid |
| amount_cents | How much was charged |
| card_last4 | Last 4 digits for matching |
| portal_confirmation | State portal confirmation # |
| reconciled | FALSE until matched |
### Matching Relay Transactions
**Option A — Manual (current):**
Export Relay transactions as CSV, compare against `filing_payments` table.
**Option B — Plaid (future):**
Connect Relay to Plaid, then connect Plaid to ERPNext via the community
Plaid integration. This gives read-only access to Relay transactions for
automatic reconciliation.
**Option C — QuickBooks bridge (future):**
Relay → QuickBooks Online sync → ERPNext QBO integration. Transactions
flow: Relay → QBO → ERPNext → auto-match against filing_payments.
## Commission Payouts via ACH
Sales agent commissions are tracked in the `commission_ledger` table in
PostgreSQL and reconciled with ERPNext.
### Agent Setup
Sales agents are created via `POST /api/v1/admin/agents`, which:
1. Creates the agent record with an auto-generated `REF-XXXXX` referral code
2. Creates a linked discount code (5% off service fee) tied to the agent
3. Agent shares their referral link or discount code with prospects
### Commission Amounts
Commissions are configurable per service type:
| Service | Commission |
|---------|-----------|
| Canada CRTC registration | $300 |
| Business formations | $50 |
| Compliance services | 10% of service fee |
| Service bundles | $100 |
### Commission Lifecycle
```
pending → eligible → approved → processing → paid
```
1. **Pending:** Commission record created when referred order is placed
2. **Eligible:** 14-day holdback after order delivery has passed
3. **Approved:** Admin reviews and approves in ERPNext
4. **Processing:** ACH payment initiated via Relay dashboard
5. **Paid:** ACH confirmed, `commission_ledger` updated with `paid_at` and `relay_transaction_id`
### Automation
- `commission_worker.py` runs as a daily cron job
- Scans `commission_ledger` for commissions past the 14-day holdback
- Transitions qualifying records from `pending` → `eligible`
- Sends admin notification in ERPNext for batch approval
- After admin approval, payment is made via Relay ACH (manual — no Relay API)
### Future: ACH API
If Relay adds API support (or we switch to a banking-as-a-service provider
like Mercury, Brex, or Column), we can automate ACH payouts. The
`commission_ledger` table is designed for this — the `status` field
tracks the full lifecycle from pending through paid.
## Virtual Card Security
- Card only funded to the amount needed for the next filing
- Separate Relay checking account dedicated to filing fees
- Card number stored AES-encrypted in ERPNext (Frappe Password field)
- Card details only in memory during Playwright automation
- Never logged, never written to disk, never in screenshots
- `filing_payments` table stores only last4 digits
- If card is compromised, max exposure = current balance (minimal)
## Relay Account Structure
Recommended Relay account organization (Profit First method):
| Account | Purpose |
|---------|---------|
| **Operating** | Main revenue account |
| **Filing Fees** | Dedicated to state filing fee payments (virtual card attached) |
| **Profit** | Retained earnings |
| **Tax** | Tax reserves |
| **Commissions** | Referral partner payouts (ACH from here) |
| **Owner Pay** | Owner distributions |
## Environment Variables
```
RELAY_FILING_CARD_ID=relay-filing-card # ERPNext Sensitive ID name
```
No Relay API credentials needed (there is no API).

407
docs/state-annual-fees-complete.md Normal file
View file

@ -0,0 +1,407 @@
# Complete LLC Annual Maintenance Costs by State (2026)
> **Purpose:** Comprehensive reference of ALL mandatory state-level fees to maintain an LLC in good standing.
> Goes beyond "annual report fees" to include franchise taxes, business licenses, privilege taxes,
> personal property returns, and other hidden/stacked fees.
>
> **Sources:** LLC University (2026 data), individual state SOS/DoR websites, CA FTB, TX Comptroller,
> NV Secretary of State SilverFlume, MD SDAT, TN Secretary of State.
>
> **Last updated:** 2026-04-01
---
## Master Fee Table
All amounts in USD. "Effective Annual" normalizes biennial fees to per-year equivalents.
"Total Annual (min)" is the minimum a single-member LLC with no revenue pays per year.
| State | Annual Report / Filing Fee | Franchise Tax | Business License | Other Mandatory Fees | Total Annual (min) | Due Date | Form Name |
|-------|---------------------------|---------------|-----------------|---------------------|-------------------|----------|-----------|
| **AL** | $0 (included in BPT) | $0 | $0 | Business Privilege Tax: **$50 min** (based on net worth; max $15,000) | **$50** | Apr 15 | Business Privilege Tax Return |
| **AK** | **$100** (biennial) | $0 | $0 | $0 | **$50/yr** | Jan 2 (even years) | Biennial Report |
| **AZ** | **$0** | $0 | $0 | $0 | **$0** | N/A | N/A (no report required) |
| **AR** | $0 (combined) | **$150** | $0 | $0 | **$150** | May 1 | Franchise Tax Report |
| **CA** | **$20** (SOI, biennial) | **$800** | $0 | LLC Fee if revenue >$250K (see below) | **$810** | Tax: Apr 15; SOI: biennial | Form 3522 + Statement of Information |
| **CO** | **$25** | $0 | $0 | $0 | **$25** | Anniversary month (5-month window) | Periodic Report |
| **CT** | **$80** | $0 | $0 | Business Entity Tax: **$250** (biennial, corps only — LLCs exempt) | **$80** | Mar 31 | Annual Report |
| **DE** | $0 (no separate report) | **$300** | $0 | $0 | **$300** | Jun 1 | Annual Franchise Tax |
| **DC** | **$300** (biennial) | $0 | $0 | $0 | **$150/yr** | Apr 1 (odd years) | Biennial Report |
| **FL** | **$138.75** | $0 | $0 | $0 | **$138.75** | May 1 | Annual Report |
| **GA** | **$60** (Annual Registration) | $0 | $0 | $0 | **$60** | Apr 1 | Annual Registration |
| **HI** | **$15** | $0 | General Excise Tax license: **$20/yr** | $0 | **$35** | Anniversary quarter | Annual Report + GET License |
| **ID** | **$0** (report required, no fee) | $0 | $0 | $0 | **$0** | Anniversary month | Annual Report (no fee) |
| **IL** | **$75** | $0 | $0 | $0 | **$75** | Anniversary month | Annual Report |
| **IN** | **$30** (biennial) | $0 | $0 | $0 | **$15/yr** | Anniversary month | Business Entity Report |
| **IA** | **$30** (biennial) | $0 | $0 | $0 | **$15/yr** | Apr 1 (odd years) | Biennial Report |
| **KS** | **$50** | $0 | $0 | $0 | **$50** | Apr 15 | Annual Report |
| **KY** | **$15** | $0 | $0 | $0 | **$15** | Jun 30 | Annual Report |
| **LA** | **$35** | $0 | $0 | $0 | **$35** | Anniversary month | Annual Report |
| **ME** | **$85** | $0 | $0 | $0 | **$85** | Jun 1 | Annual Report |
| **MD** | **$300** (combined AR + PPT) | $0 | $0 | Personal property tax if LLC holds tangible property in MD | **$300** | Apr 15 | Annual Report & Personal Property Tax Return |
| **MA** | **$500** | $0 | $0 | $0 | **$500** | Anniversary month | Annual Report |
| **MI** | **$25** | $0 | $0 | $0 | **$25** | Feb 15 | Annual Report |
| **MN** | **$0** (report required, no fee) | $0 | $0 | $0 | **$0** | Dec 31 | Annual Renewal |
| **MS** | **$0** | $0 | $0 | Privilege tax for S-Corps only; LLCs exempt | **$0** | N/A | N/A |
| **MO** | **$0** | $0 | $0 | $0 | **$0** | N/A | N/A (no report required) |
| **MT** | **$20** | $0 | $0 | $0 | **$20** | Apr 15 | Annual Report |
| **NE** | **$13** (biennial) | $0 | $0 | $0 | **$6.50/yr** | Apr 1 (odd years) | Biennial Report |
| **NV** | **$150** (Annual List) | $0 | **$200** (State Business License) | $0 | **$350** | Anniversary month | Annual List + Business License Renewal |
| **NH** | **$100** | $0 | $0 | $0 | **$100** | Apr 1 | Annual Report |
| **NJ** | **$75** | $0 | $0 | $0 | **$75** | Anniversary month | Annual Report |
| **NM** | **$0** | $0 | $0 | $0 | **$0** | N/A | N/A (no report required) |
| **NY** | **$9** (biennial) | $0 | $0 | $0 | **$4.50/yr** | Anniversary month | Biennial Statement |
| **NC** | **$200** | $0 | $0 | $0 | **$200** | Apr 15 | Annual Report |
| **ND** | **$50** | $0 | $0 | $0 | **$50** | Nov 15 | Annual Report |
| **OH** | **$0** | $0 | $0 | Commercial Activity Tax if revenue >$150K (0.26%) | **$0** | N/A | N/A (no report required) |
| **OK** | **$25** | $0 | $0 | $0 | **$25** | Anniversary month | Annual Certificate |
| **OR** | **$100** | $0 | $0 | $0 | **$100** | Anniversary month | Annual Report |
| **PA** | **$7** | $0 | $0 | $0 | **$7** | Sep 30 | Annual Report (new in 2025) |
| **RI** | **$50** | $0 | $0 | $0 | **$50** | Feb 1 - May 1 | Annual Report |
| **SC** | **$0** | $0 | $0 | $0 | **$0** | N/A | N/A (unless LLC elects S-Corp) |
| **SD** | **$55** (domestic) | $0 | $0 | $0 | **$55** | Anniversary month | Annual Report |
| **TN** | **$300 min** ($300/yr for 1-6 members) | $0 | $0 | +$50/member over 6 (no cap) | **$300** | Apr 1 | Annual Report |
| **TX** | **$0** (PIR filing, no fee) | Franchise tax only if revenue >$2.47M | $0 | Must file Public Information Report (no fee) | **$0** | May 15 | Public Information Report |
| **UT** | **$18** | $0 | $0 | $0 | **$18** | Anniversary month | Annual Report |
| **VT** | **$45** | $0 | $0 | $0 | **$45** | Mar 15 | Annual Report |
| **VA** | **$50** | $0 | $0 | $0 | **$50** | Anniversary month | Annual Registration Fee |
| **WA** | **$60** | $0 | $0 | B&O tax is revenue-based, not a compliance fee | **$60** | Anniversary month | Annual Report |
| **WV** | **$25** | $0 | $0 | $0 | **$25** | Jul 1 | Annual Report |
| **WI** | **$25** | $0 | $0 | $0 | **$25** | Anniversary quarter | Annual Report |
| **WY** | **$60 min** | $0 | $0 | Based on assets in WY (>$300K assets = higher fee) | **$60** | Anniversary month | Annual Report |
---
## States Ranked by Total Annual Cost (Minimum)
| Rank | State | Min Annual Cost | Notes |
|------|-------|----------------|-------|
| 1 | CA | **$810** | $800 franchise tax + $10/yr SOI; can reach $12,610 with LLC fee |
| 2 | MA | **$500** | Flat $500, no exemptions |
| 3 | NV | **$350** | $150 Annual List + $200 Business License |
| 4 | DE | **$300** | Flat $300 franchise tax |
| 5 | MD | **$300** | Combined AR + Personal Property Tax Return |
| 6 | TN | **$300** | $300/member (min $300); scales with members |
| 7 | NC | **$200** | Flat $200 |
| 8 | DC | **$150/yr** | $300 biennial |
| 9 | AR | **$150** | Franchise Tax Report |
| 10 | FL | **$138.75** | Includes processing fee |
| 11 | NH | **$100** | |
| 12 | OR | **$100** | |
| 13 | AK | **$50/yr** | $100 biennial |
| 14 | ME | **$85** | |
| 15 | CT | **$80** | |
| 16 | IL | **$75** | Reduced from $250 in 2023 |
| 17 | NJ | **$75** | |
| 18 | GA | **$60** | |
| 19 | WA | **$60** | |
| 20 | WY | **$60** | Minimum; scales with WY assets |
| 21 | SD | **$55** | |
| 22 | AL | **$50** | Minimum BPT; scales with net worth |
| 23 | KS | **$50** | |
| 24 | ND | **$50** | |
| 25 | RI | **$50** | |
| 26 | VA | **$50** | |
| 27 | VT | **$45** | |
| 28 | HI | **$35** | $15 AR + $20 GET license |
| 29 | LA | **$35** | |
| 30 | CO | **$25** | |
| 31 | MI | **$25** | |
| 32 | OK | **$25** | |
| 33 | WV | **$25** | |
| 34 | WI | **$25** | |
| 35 | MT | **$20** | |
| 36 | UT | **$18** | |
| 37 | IN | **$15/yr** | $30 biennial |
| 38 | IA | **$15/yr** | $30 biennial |
| 39 | KY | **$15** | |
| 40 | PA | **$7** | New annual report as of 2025 |
| 41 | NY | **$4.50/yr** | $9 biennial |
| 42 | NE | **$6.50/yr** | $13 biennial |
| 43-51 | AZ, ID, MN, MS, MO, NM, OH, SC, TX | **$0** | No fee / no report or report with $0 fee |
---
## Deep Dive: States with Hidden / Stacked Fees
### California — Most Expensive ($810 minimum, up to $12,610+)
California has THREE separate mandatory filings for LLCs:
| Filing | Fee | Due | Form |
|--------|-----|-----|------|
| Annual Franchise Tax | **$800/yr** | April 15 | Form 3522 |
| Statement of Information | **$20** (biennial) | Every 2 years | SI-LLC |
| LLC Fee (revenue-based) | **$0-$11,790** | June 15 | Form 3536 |
**LLC Fee schedule (Form 3536) — based on total annual gross receipts:**
| Gross Receipts | Additional LLC Fee |
|---------------|--------------------|
| Under $250,000 | $0 |
| $250,000 - $499,999 | $900 |
| $500,000 - $999,999 | $2,500 |
| $1,000,000 - $4,999,999 | $6,000 |
| $5,000,000+ | $11,790 |
**Exemptions:**
- ~~First-year franchise tax waiver (AB85) — expired December 31, 2023~~
- No revenue exemptions for the $800 franchise tax — it is owed regardless of income or activity
- LLC Fee only applies if gross receipts exceed $250K
- LLCs that are dormant/inactive still owe $800/yr until formally dissolved
**Total cost examples:**
- Dormant LLC: $800 + $10/yr SOI = **$810/yr**
- LLC with $300K revenue: $800 + $900 + $10 = **$1,710/yr**
- LLC with $2M revenue: $800 + $6,000 + $10 = **$6,810/yr**
- LLC with $6M revenue: $800 + $11,790 + $10 = **$12,600/yr**
---
### Nevada — Deceptively Expensive ($350/yr)
Nevada markets itself as "no state income tax" but has one of the highest LLC maintenance costs:
| Filing | Fee | Due |
|--------|-----|-----|
| Annual List of Managers/Members | **$150/yr** | Anniversary month |
| State Business License Renewal | **$200/yr** | Anniversary month |
Both are filed together as a single combined filing through SilverFlume portal. Total: **$350/yr**.
**What's NOT charged:**
- No state income tax
- No franchise tax
- No gross receipts tax for most businesses
**Exemptions:**
- None. Both filings are mandatory regardless of revenue or activity.
- Failure to file: $150 penalty on the Annual List + additional penalties on the license.
---
### Delaware — The "LLC Haven" ($300/yr)
Delaware is simple for LLCs — just one annual fee:
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Franchise Tax | **$300/yr** | June 1 |
**Key facts:**
- This is a flat $300 for ALL LLCs regardless of size, revenue, or members
- Delaware does NOT require LLCs to file an annual report (unlike corporations)
- No state income tax on out-of-state income
- The $300 is specifically an "Alternative Entity Tax" for LLCs, LPs, and GPs formed in Delaware
**Exemptions:**
- None. $300 is owed regardless of revenue or activity.
**Hidden costs for non-DE residents:**
- You MUST maintain a registered agent in Delaware (~$50-$300/yr from third parties)
- If you operate in another state, you also need to register as a foreign LLC there (additional fees)
---
### Texas — Cheapest Large State ($0 for most)
| Filing | Fee | Due |
|--------|-----|-----|
| Public Information Report (PIR) | **$0** | May 15 |
| Franchise Tax Return | **$0** if revenue < $2.47M | May 15 |
**Franchise Tax details (only if revenue > $2.47M):**
- 0.375% of taxable margin for wholesalers/retailers
- 0.75% of taxable margin for all other businesses
- 0.331% of total revenue (EZ computation method)
- Threshold adjusted every 2 years per TX Tax Code 171.006
**Exemptions:**
- LLCs with less than $2.47M annual revenue: **exempt from franchise tax** (just file PIR)
- No-tax-due threshold means most small LLCs pay $0
---
### Tennessee — Per-Member Pricing ($300 minimum)
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Report | **$300** (1-6 members) | April 1 |
| Annual Report | **$300 + $50/member over 6** | April 1 |
**Fee examples:**
- 1 member: $300
- 6 members: $300
- 7 members: $350
- 10 members: $500
- 20 members: $1,000
**Note:** There is NO statutory cap on the per-member fee. An LLC with 100 members would pay $300 + (94 x $50) = **$5,000/yr**.
---
### Maryland — The Personal Property Trap ($300/yr)
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Report + Personal Property Tax Return | **$300** | April 15 |
**Key facts:**
- The "Annual Report" in Maryland is actually a **Personal Property Tax Return** filed with the State Department of Assessments and Taxation (SDAT)
- ALL Maryland LLCs must file the Annual Report
- The Personal Property Tax Return portion is required if the LLC owns, uses, or leases personal property in Maryland, OR has a trader's license
- Additional personal property taxes may be owed beyond the $300 filing fee depending on the value of tangible personal property
---
### Massachusetts — Highest Flat Report Fee ($500/yr)
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Report | **$500** | Anniversary month |
**Key facts:**
- $500 is the highest flat annual report fee in the nation
- No exemptions, no reduced rate for small businesses
- Penalty for failure to register a foreign LLC: additional $500/yr per year not registered
- There is no escape: forming in WY/NV and operating in MA requires foreign LLC registration ($500/yr to MA) PLUS the home state's fees
---
### Alabama — Variable Privilege Tax ($50 minimum)
| Filing | Fee | Due |
|--------|-----|-----|
| Business Privilege Tax | **$50 minimum** | April 15 |
**How it works:**
- Tax is based on LLC's net worth apportioned to Alabama
- Rate: $0.25 per $1,000 of net worth
- Minimum: $50
- Maximum: $15,000
- Most small LLCs with minimal net worth pay only $50
---
### Wyoming — Asset-Based Scaling ($60 minimum)
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Report | **$60 minimum** | Anniversary month |
**How it works:**
- $60 flat fee if LLC assets in Wyoming are $300,000 or less
- If assets exceed $300,000, fee increases (calculated based on asset value)
- No state income tax
- Popular for holding companies and asset protection LLCs
---
### Illinois — Recently Reduced ($75/yr)
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Report | **$75** | Anniversary month |
**History:** Illinois reduced its LLC annual report fee from $250 to $75 effective January 1, 2023. This made Illinois significantly more competitive.
---
### North Carolina — Quietly High ($200/yr)
| Filing | Fee | Due |
|--------|-----|-----|
| Annual Report | **$200** | April 15 |
NC's $200 annual report is one of the higher flat fees but doesn't get the same attention as CA or MA. No additional franchise tax for LLCs.
---
## States with $0 Annual Cost
These 9 states have NO mandatory annual fees for LLCs:
| State | Details |
|-------|---------|
| **Arizona** | No annual report required, no fee |
| **Idaho** | Must file annual information report, but $0 fee |
| **Minnesota** | Must file annual renewal, but $0 fee |
| **Mississippi** | No annual report required ($0); privilege tax applies only to S-Corps, not LLCs |
| **Missouri** | No annual report required, no fee |
| **New Mexico** | No annual report required, no fee |
| **Ohio** | No annual report required; Commercial Activity Tax only applies if revenue >$150K |
| **South Carolina** | No annual report unless LLC elects S-Corp tax treatment |
| **Texas** | Must file Public Information Report ($0 fee); franchise tax only if revenue >$2.47M |
---
## Fee Type Glossary
| Fee Type | Description | States That Charge It |
|----------|-------------|----------------------|
| **Annual Report** | Basic filing to update state records (name, address, members, RA) | Most states |
| **Franchise Tax** | Tax on the privilege of existing as an entity in the state; NOT based on income | CA ($800), DE ($300), AR ($150) |
| **Business License** | State-level license to operate any business | NV ($200) |
| **Annual List** | Filing listing members/managers; separate from annual report in some states | NV ($150) |
| **Business Privilege Tax** | Tax on privilege of doing business; calculated on net worth | AL ($50 min) |
| **Personal Property Tax Return** | Return declaring tangible property owned; required even if $0 owed | MD ($300) |
| **LLC Fee** | Additional fee based on gross receipts / revenue | CA ($0-$11,790) |
| **Public Information Report** | Informational filing with no fee | TX ($0) |
| **Periodic Report** | Same as annual report, just named differently | CO ($25) |
---
## Exemptions Summary
### Revenue-Based Exemptions
- **Texas**: Franchise tax exempt if revenue < $2.47M (threshold adjusted biennially)
- **California**: LLC Fee (Form 3536) exempt if gross receipts < $250K (but $800 franchise tax always applies)
- **Ohio**: Commercial Activity Tax exempt if revenue < $150K
- **Alabama**: Minimum $50 BPT regardless of revenue; scales with net worth not revenue
### Entity Type Exemptions
- **Connecticut**: Business Entity Tax ($250 biennial) applies to corps only, NOT LLCs
- **Mississippi**: Privilege tax applies to S-Corps only; LLCs taxed as partnerships/sole props are exempt
- **South Carolina**: Annual report only required if LLC elects S-Corp tax treatment
### First-Year Exemptions
- **California**: First-year franchise tax waiver (AB85) **expired December 31, 2023** — no longer available
- Most states do NOT offer first-year waivers
### New Business / Small Business Exemptions
- No states offer blanket small business exemptions for annual compliance fees
- Fees are generally owed regardless of revenue, profit, or activity level
- The only "exemptions" are revenue thresholds (TX, CA, OH) that waive ADDITIONAL taxes, not the base filing
---
## Data for PW Annual Reports Service Pricing
Our Annual Reports service charges **$99/yr per state** as a service fee. State fees are pass-through.
### Client total cost = $99 (PW service) + state fee (from table above)
| Cost Tier | States | Client Total (PW + state) |
|-----------|--------|--------------------------|
| $99 only (no state fee) | AZ, ID, MN, MS, MO, NM, OH, SC, TX | $99 |
| Under $150 total | NY, NE, PA, IN, IA, KY, HI, MT, UT, CO, MI, OK, WV, WI, LA | $103.50 - $134 |
| $150-$199 total | VT, KS, AK, ND, RI, VA, SD, WA, GA, WY, IL | $144 - $174 |
| $200-$299 total | CT, ME, NJ, OR, NH, FL, AR, DC | $179 - $249 |
| $300+ total | NC, DE, MD, TN, NV, MA, CA | $299 - $909 |
### High-Cost State Warnings for Clients
When a client selects annual report service for these states, display a cost breakdown:
- **CA**: "$99 service + $800 franchise tax + $20 SOI = $919 minimum"
- **MA**: "$99 service + $500 state fee = $599"
- **NV**: "$99 service + $350 state fees = $449"
- **DE**: "$99 service + $300 franchise tax = $399"
- **MD**: "$99 service + $300 state fee = $399"
- **TN**: "$99 service + $300 state fee = $399 (1-6 members)"
- **NC**: "$99 service + $200 state fee = $299"
---
## Changelog
- **2026-04-01**: Initial comprehensive version with all fee categories, exemptions, and hidden fees
- Source data from LLC University (updated July 2025 for 2026 fees), cross-referenced with state SOS websites

233
docs/state-automation-status.md Normal file
View file

@ -0,0 +1,233 @@
# State-by-State Automation Status — 52 Jurisdictions (50 States + DC + BC Canada)
**Last updated:** 2026-04-05
This document tracks the implementation status of name search and entity filing
automation for all 52 jurisdictions (50 states + DC + BC Canada).
## Status Legend
| Symbol | Meaning |
|--------|---------|
| WORKING | Tested and functional |
| READY | Selectors verified, needs Playwright testing |
| BLOCKED-CAPTCHA | Portal has CAPTCHA, needs solving service or manual step |
| BLOCKED-LOGIN | Portal requires account/login before search or filing |
| BLOCKED-WAF | Portal has Web Application Firewall blocking automation |
| BLOCKED-PAYMENT | Automation works up to payment step |
| NEEDS-RESEARCH | Portal not yet inspected |
| API | Uses REST API, no browser needed |
---
## Tier 1: API-Based Name Search (No Browser Needed)
| State | Code | Name Search | Filing | Portal | Notes |
|-------|------|-------------|--------|--------|-------|
| **Colorado** | CO | **WORKING (API)** | NEEDS-RESEARCH | data.colorado.gov | Socrata SODA API. Dataset 4ykn-tg5h. Free, no auth. Confirmed working with live test. |
### Other Potential Socrata States (Untested)
These states have open data portals that MAY have business entity datasets:
| State | Code | Socrata Domain | Dataset ID | Status |
|-------|------|---------------|------------|--------|
| Alaska | AK | data.alaska.gov | Unknown | NEEDS-RESEARCH |
| Connecticut | CT | data.ct.gov | Unknown | NEEDS-RESEARCH |
| Illinois | IL | data.illinois.gov | Unknown | NEEDS-RESEARCH |
| Iowa | IA | data.iowa.gov | Unknown | NEEDS-RESEARCH |
| Michigan | MI | data.michigan.gov | Unknown | NEEDS-RESEARCH |
| New York | NY | data.ny.gov | Unknown | NEEDS-RESEARCH |
| Oregon | OR | data.oregon.gov | Unknown | NEEDS-RESEARCH |
| Pennsylvania | PA | data.pa.gov | Unknown | NEEDS-RESEARCH |
| Vermont | VT | data.vermont.gov | Unknown | NEEDS-RESEARCH |
| Washington | WA | data.wa.gov | Unknown | NEEDS-RESEARCH |
**Action needed:** Search each Socrata domain for business entity datasets. If found, these states can use API-based name search like Colorado.
---
## Tier 2: Selectors Verified (Ready for Playwright Testing)
| State | Code | Name Search | Filing | Portal | Key Selectors | Barriers |
|-------|------|-------------|--------|--------|---------------|----------|
| **Wyoming** | WY | **READY** | NEEDS-RESEARCH | wyobiz.wyo.gov | Name: `#MainContent_txtFilingName`, Search: `#MainContent_cmdSearch`, Contains: `#MainContent_chkSearchIncludes` | ASP.NET WebForms postback. No CAPTCHA on name search. |
| **Delaware** | DE | **BLOCKED-CAPTCHA** | BLOCKED-CAPTCHA | icis.corp.delaware.gov | Name: `#ctl00_ContentPlaceHolder1_frmEntityName`, FileNo: `#ctl00_ContentPlaceHolder1_frmFileNumber`, Submit: `#ctl00_ContentPlaceHolder1_btnSubmit`, CAPTCHA panel: `#ctl00_ContentPlaceHolder1_pnlCaptcha` | **CAPTCHA on every search.** Anti-scraping warning: "Use of automated tools may result in suspension." CAPTCHA image at `/Ecorp/CaptchaHandler.ashx`. Solving service (2captcha/anticaptcha) needed. |
| **Utah** | UT | **READY** | BLOCKED-LOGIN | secure.utah.gov | Entity search at `/EntitySearch/OnlineEntitySearch` (no login). Name availability at `/NameAvailabilitySearch` (no login). Filing requires UtahID login (OAuth). | Name search accessible without login. Modern web app (not ASP.NET). Filing requires UtahID OAuth. |
---
## Tier 3: Portal Requires Account/Login
| State | Code | Portal | Login Type | What's Needed |
|-------|------|--------|------------|---------------|
| **Texas** | TX | direct.sos.state.tx.us | SOSDirect account (client_id + password) | Regular subscription for filing. Temporary login available for searches (credit card required). Need to create SOSDirect account. Password expires every 90 days. |
| **Utah** | UT | secure.utah.gov | UtahID (OAuth) | Filing requires creating a UtahID account. Name search works without login. |
---
## Tier 4: Portal Blocks Non-Browser Requests (Need Playwright)
These portals returned 403 or similar when fetched without a real browser.
Playwright with stealth settings should work for these.
| State | Code | Portal URL | HTTP Status | Notes |
|-------|------|-----------|-------------|-------|
| **Florida** | FL | search.sunbiz.org | 403 | Blocks curl/fetch. Playwright should work. |
| **Ohio** | OH | businesssearch.ohiosos.gov | 403 | Same — blocks non-browser requests. |
| **California** | CA | businesssearch.sos.ca.gov | Connection refused | URL may have changed. Try bizfileonline.sos.ca.gov. |
---
## Tier 5: WAF/Anti-Bot Protection
| State | Code | Portal | Protection | What's Needed |
|-------|------|--------|-----------|---------------|
| **Nevada** | NV | esos.nv.gov | Incapsula/Imperva WAF | Returns Incapsula challenge page. Need Playwright with advanced stealth (random delays, mouse movements, browser fingerprint randomization). May need residential proxy. |
---
## Tier 6: Not Yet Researched (37 States)
| State | Code | Known Portal URL | Priority |
|-------|------|-----------------|----------|
| Alabama | AL | sos.alabama.gov | Low |
| Alaska | AK | commerce.alaska.gov | Medium (check Socrata) |
| Arizona | AZ | ecorp.azcc.gov | Medium |
| Arkansas | AR | biz.sos.arkansas.gov | Low |
| Connecticut | CT | service.ct.gov | Medium (check Socrata) |
| Georgia | GA | ecorp.sos.ga.gov | Medium |
| Hawaii | HI | hbe.ehawaii.gov | Low |
| Idaho | ID | sosbiz.idaho.gov | Low |
| Illinois | IL | apps.ilsos.gov | Medium (check Socrata) |
| Indiana | IN | bsd.sos.in.gov | Low |
| Iowa | IA | sos.iowa.gov | Medium (check Socrata) |
| Kansas | KS | kansas.gov/bess | Low |
| Kentucky | KY | app.sos.ky.gov | Low |
| Louisiana | LA | coraweb.sos.la.gov | Low |
| Maine | ME | icrs.informe.org | Low |
| Maryland | MD | egov.maryland.gov | Low |
| Massachusetts | MA | corp.sec.state.ma.us | Low |
| Michigan | MI | cofs.lara.state.mi.us | Medium (check Socrata) |
| Minnesota | MN | mblsportal.sos.state.mn.us | Low |
| Mississippi | MS | corp.sos.ms.gov | Low |
| Missouri | MO | bsd.sos.mo.gov | Low |
| Montana | MT | biz.sosmt.gov | Low |
| Nebraska | NE | sos.nebraska.gov | Low |
| New Hampshire | NH | quickstart.sos.nh.gov | Low |
| New Jersey | NJ | njportal.com/dor | Low |
| New Mexico | NM | portal.sos.state.nm.us | Medium |
| New York | NY | appext20.dos.ny.gov | Medium (check Socrata) |
| North Carolina | NC | sosnc.gov | Low |
| North Dakota | ND | firststop.sos.nd.gov | Low |
| Oklahoma | OK | sos.ok.gov | Low |
| Oregon | OR | egov.sos.state.or.us | Medium (check Socrata) |
| Pennsylvania | PA | file.dos.pa.gov | Medium (check Socrata) |
| Rhode Island | RI | business.sos.ri.gov | Low |
| South Carolina | SC | businessfilings.sc.gov | Low |
| South Dakota | SD | sosenterprise.sd.gov | Low |
| Tennessee | TN | tnbear.tn.gov | Low |
| Vermont | VT | bizfilings.vermont.gov | Medium (check Socrata) |
| Virginia | VA | cis.scc.virginia.gov | Medium |
| Washington | WA | ccfs.sos.wa.gov | Medium (check Socrata) |
| West Virginia | WV | apps.wv.gov | Low |
| Wisconsin | WI | apps.dfi.wi.gov | Low |
| DC | DC | corponline.dcra.dc.gov | Low |
---
## BC (British Columbia, Canada)
| State | Code | Name Search | Filing | Portal | Notes |
|-------|------|-------------|--------|--------|-------|
| **BC** | BC | Stubbed | Stubbed | corporateonline.gov.bc.ca | Part of Canada CRTC Carrier Package ($3,899). BC Registry uses Corporate Online portal (anonymous — no login required). Name reservation via bcregistrynames.gov.bc.ca. COLIN selectors need live session verification (Steps 5-12). |
BC adapter also handles (14-step pipeline in `services/canada_crtc.py`):
- Anytime Mailbox setup (329 Howe St, Vancouver) — implemented (Playwright + IMAP OTP)
- .ca domain provisioning via HestiaCP (cp.carrierone.com) — implemented
- Canadian DID via Flowroute — implemented
- CRTC registration letter — implemented (DOCX → MinIO → DocServer PDF)
- eSign portal — implemented (canvas signature, JWT auth, 72h expiry)
- BITS registration — implemented (Step 11: GCKey provisioning + admin ToDo)
- CCTS membership — implemented (Step 12: admin ToDo + client obligations email)
- Compliance calendar — implemented (Step 13: 17 entries — regulatory + tax + ATS)
- Corporate binder compilation — implemented (pikepdf + reportlab)
- GCKey provisioning — implemented (Playwright 5-step wizard, hCaptcha handling)
- Renewal lifecycle — implemented (renewal_worker.py daily cron)
### GCKey Automation Details
| Step | Status | Notes |
|------|--------|-------|
| Step 1 — Terms | **Verified** | `input[name=_eventId_accept]`, no CAPTCHA |
| Step 2 — Username | **Verified** | `input[name=uid][id=userID]`, hCaptcha invisible (sitekey mapped) |
| Step 3 — Password | Inferred | `input[type=password]` fields, hCaptcha likely |
| Step 4 — Security Q&A | Inferred | `select` dropdowns + text answer fields |
| Step 5 — Email/Confirm | Inferred | email field + submit |
hCaptcha solver integration stubbed — needs 2captcha/CapSolver API key for production.
---
## Filing Barriers (Universal)
These barriers apply to ALL states once name search is working:
1. **Payment processing** — Every state requires payment for filing. Most accept credit card via web form. Automating credit card entry requires PCI considerations. Options:
- Pre-funded SOSDirect-style accounts (TX, some others)
- Credit card entry via Playwright (risky, PCI compliance concern)
- Manual payment step (admin enters card in browser, automation fills rest)
2. **Document upload** — Some states require uploading signed Articles of Organization as PDF. Others have online forms that generate the document.
3. **Registered agent acceptance** — Some states require the RA to accept/confirm before filing completes. NW RA may handle this automatically for their wholesale partners.
4. **Publication requirements** — AZ and NY require newspaper publication after filing. This is a manual/semi-manual step that cannot be fully automated.
---
## Priority Implementation Order
Based on formation volume and customer demand:
1. **Wyoming** (WY) — Selectors verified, highest priority. No CAPTCHA.
2. **Colorado** (CO) — API working for name search. Need filing automation.
3. **Delaware** (DE) — Selectors verified but CAPTCHA blocks automation. Need solving service.
4. **Florida** (FL) — High demand. Needs Playwright (403 from curl). No CAPTCHA expected.
5. **Texas** (TX) — High demand. Need SOSDirect account. Temporary login for searches.
6. **Nevada** (NV) — High demand for privacy. WAF blocks. Need stealth Playwright.
7. **Utah** (UT) — Name search without login. Cheapest state. Filing needs UtahID.
8. **New Mexico** (NM) — Cheap, no annual fees. Untested portal.
9. **Ohio** (OH) — No annual fees. Needs Playwright (403).
10. **Montana** (MT) — Cheapest LLC ($35). Untested portal.
---
## Next Steps
### Immediate (this session)
- [x] Verify Colorado Socrata API (CONFIRMED WORKING)
- [x] Extract Delaware selectors from live HTML
- [x] Extract Texas login requirements
- [x] Document Utah portal structure
- [ ] Test Wyoming name search via Playwright
- [ ] Search Socrata domains for more API-accessible states
### Short-term (next session)
- [ ] Set up 2captcha or anticaptcha integration for Delaware
- [ ] Create SOSDirect account for Texas
- [ ] Create UtahID account for Utah
- [ ] Fetch and extract selectors for FL, NV, CA, OH via Playwright
- [ ] Test name search on WY, UT, FL, OH via Playwright
### Medium-term
- [ ] Implement filing automation for WY (first state to go live)
- [ ] Implement filing automation for CO (second, API head start)
- [ ] Set up CAPTCHA solving for DE
- [ ] Research and extract selectors for remaining 37 states
### Long-term
- [ ] Complete all 52 jurisdiction name search implementations (50 states + DC + BC)
- [ ] Complete all 52 jurisdiction filing implementations
- [ ] Handle payment step for each state
- [ ] Set up monitoring for portal changes (selectors break when states update their sites)

150
docs/ticketing.md Normal file
View file

@ -0,0 +1,150 @@
# Support Ticketing — ERPNext Helpdesk
**Last updated:** 2026-03-29
## Overview
ERPNext's Issue DocType provides all helpdesk ticketing. There is no separate
ticketing system — everything runs inside the same CRM that manages orders
and invoices.
- Web widget on performancewest.net -> Express API -> ERPNext Issue
- Contact form -> Express API -> ERPNext Issue
- Monitor script alerts -> ERPNext Issue
- Formation worker errors -> ERPNext Issue
- Customer portal: clients can view/reply to their issues
## How Tickets Are Created
### 1. Website Support Widget (SupportWidget.astro)
The floating help button on every page submits to `POST /api/v1/tickets`.
The Express API creates an ERPNext Issue with the ticket data.
Categories map to ERPNext Issue Types:
| Widget Category | ERPNext Issue Type |
|----------------|-------------------|
| question | Sales Inquiry |
| support | Support |
| issue | Bug |
| service_request | Feature Request |
| quote | Sales Inquiry |
### 2. Contact Page Form
Same flow as the support widget — submits to `POST /api/v1/tickets`.
### 3. Monitor Script Alerts (alert.py)
When Reddit monitors, formation workers, or other scripts encounter errors,
they call `alert_account_broken()` which creates an ERPNext Issue with
priority "High" and issue_type "Bug".
### 4. Formation Worker Errors
When automation fails (state portal down, CAPTCHA, payment failure), the
worker creates an ERPNext Issue linking to the Formation Order.
## ERPNext Issue Fields
| Field | Description |
|-------|-------------|
| subject | Ticket title |
| description | Full message |
| issue_type | Sales Inquiry, Support, Bug, Feature Request |
| priority | Low, Medium, High, Urgent |
| status | Open, Replied, Resolved, Closed |
| customer | Linked Customer (if known) |
| raised_by | Email of the person who submitted |
## Ticket Workflow
```
Open -> Replied -> Resolved -> Closed
^ |
+-- Reopened +
```
- Admin views open issues in ERPNext desk
- Responds via ERPNext (email sent to customer automatically)
- Customer can reply via email (auto-linked to issue)
- Admin resolves when done
- Auto-close after 7 days with no reply
## DNS
There is no separate `support.performancewest.net` domain.
Tickets are managed at `crm.performancewest.net` (ERPNext).
## Configuration
No separate ticketing configuration needed. ERPNext Issue is a core
DocType — just needs email integration for customer notifications:
1. ERPNext -> Settings -> Email Account -> configure outgoing email
2. ERPNext -> Settings -> Email Account -> configure incoming email (for auto-reply-to-issue)
3. ERPNext -> Desk -> Issue -> create Issue Types if needed
## Canada CRTC Client Email Monitoring
`client_email_processor.py` monitors inbound email for each Canada CRTC
client domain. Each client gets 14 standard mailboxes provisioned via
HestiaCP on cp.carrierone.com:
| Mailbox | Priority |
|---------|----------|
| regulatory@ | High |
| crtc@ | High |
| ccts@ | High |
| corpadmin@ | Medium |
| registeredoffice@ | Medium |
| accounting@ | Medium |
| billing@ | Medium |
| abuse@ | High |
| noc@ | High |
| postmaster@ | Medium |
| info@ | Low |
| admin@ | Medium |
| sales@ | Low |
| support@ | Low |
### How It Works
1. `client_email_processor.py` connects to each mailbox via IMAP
2. New messages are parsed (sender, subject, body, attachments)
3. An ERPNext Issue is created with:
- Subject from the email
- Priority based on the mailbox type (see table above)
- Customer linked to the CRTC client
- Issue Type: "CRTC Correspondence"
4. **High-priority items** (regulatory@, crtc@, ccts@, abuse@, noc@)
trigger an immediate alert to both the client and the PW admin team
5. Lower-priority items are batched into a daily digest for the client
The processor runs on a 5-minute polling interval via cron.
## Accounting Support Conversation Monitor
`conversation_monitor.py` scans active accounting support Issue threads in
ERPNext for bypass attempts — situations where a client tries to move the
conversation off-platform or bypass payment.
### Detection Patterns
The monitor flags messages containing:
- **Personal contact info:** phone numbers, personal email addresses,
physical addresses shared in thread
- **Messaging platforms:** references to WhatsApp, Telegram, Signal,
Discord, Slack DMs, or similar
- **Payment bypass:** requests to pay outside the platform, mentions of
Venmo, Zelle, Cash App, direct wire, or crypto wallet addresses
### Response Actions
1. **Warning injection:** An automated reply is posted to the Issue thread
reminding the client that all communication and payments must go through
the platform for their protection and ours
2. **Admin alert:** A separate ERPNext Issue is created (type: "Compliance
Alert", priority: High) notifying the admin team of the flagged message
3. **Escalation on repeat:** If the same client is flagged more than once,
the admin alert is marked Urgent and the client's accounting support
access is temporarily suspended pending review
The monitor runs as a background job every 15 minutes, scanning Issues
with type "Accounting Support" and status "Open" or "Replied".