Add trucking system documentation and architecture SVG
trucking-system.md: comprehensive doc covering data pipeline, compliance checker (14 checks), 21 service slugs, vendors, database tables, frontend pages, order flow, and campaign segmentation (29,792 eligible). trucking-architecture.svg: visual diagram of full system — data sources, processing layer, database, frontend, campaigns, and order flow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
justin
parent
f34df45e5f
commit
ba3eb30b58
2 changed files with 444 additions and 0 deletions
234
docs/trucking-architecture.svg
Normal file
234
docs/trucking-architecture.svg
Normal file
|
|
@ -0,0 +1,234 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 900" font-family="Inter, system-ui, sans-serif">
|
||||
<defs>
|
||||
<style>
|
||||
.title { font-size: 22px; font-weight: 700; fill: #1a2744; }
|
||||
.subtitle { font-size: 12px; fill: #64748b; }
|
||||
.box { rx: 8; ry: 8; stroke-width: 2; }
|
||||
.box-label { font-size: 13px; font-weight: 600; }
|
||||
.box-detail { font-size: 10px; fill: #475569; }
|
||||
.section-label { font-size: 14px; font-weight: 700; text-transform: uppercase; letter-spacing: 1px; }
|
||||
.arrow { stroke-width: 2; fill: none; marker-end: url(#arrowhead); }
|
||||
.dashed { stroke-dasharray: 6,4; }
|
||||
</style>
|
||||
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
|
||||
<polygon points="0 0, 10 3.5, 0 7" fill="#94a3b8"/>
|
||||
</marker>
|
||||
<marker id="arrowhead-orange" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
|
||||
<polygon points="0 0, 10 3.5, 0 7" fill="#f97316"/>
|
||||
</marker>
|
||||
</defs>
|
||||
|
||||
<!-- Background -->
|
||||
<rect width="1200" height="900" fill="#f8fafc"/>
|
||||
|
||||
<!-- Title -->
|
||||
<text x="600" y="35" text-anchor="middle" class="title">Trucking / DOT Compliance System Architecture</text>
|
||||
<text x="600" y="52" text-anchor="middle" class="subtitle">Performance West Inc. — 50-State Motor Carrier Compliance</text>
|
||||
|
||||
<!-- ═══ ROW 1: Data Sources ═══ -->
|
||||
<text x="50" y="85" class="section-label" fill="#f97316">DATA SOURCES</text>
|
||||
|
||||
<!-- FMCSA Socrata API -->
|
||||
<rect x="30" y="95" width="200" height="65" class="box" fill="#fff7ed" stroke="#f97316"/>
|
||||
<text x="130" y="118" text-anchor="middle" class="box-label" fill="#9a3412">FMCSA Socrata API</text>
|
||||
<text x="130" y="133" text-anchor="middle" class="box-detail">data.transportation.gov</text>
|
||||
<text x="130" y="148" text-anchor="middle" class="box-detail">2M+ carrier records</text>
|
||||
|
||||
<!-- FMCSA QCMobile API -->
|
||||
<rect x="260" y="95" width="200" height="65" class="box" fill="#fff7ed" stroke="#f97316"/>
|
||||
<text x="360" y="118" text-anchor="middle" class="box-label" fill="#9a3412">FMCSA QCMobile API</text>
|
||||
<text x="360" y="133" text-anchor="middle" class="box-detail">Real-time carrier lookup</text>
|
||||
<text x="360" y="148" text-anchor="middle" class="box-detail">7 federal compliance checks</text>
|
||||
|
||||
<!-- State Requirements DB -->
|
||||
<rect x="490" y="95" width="200" height="65" class="box" fill="#eff6ff" stroke="#3b82f6"/>
|
||||
<text x="590" y="118" text-anchor="middle" class="box-label" fill="#1e40af">State Requirements DB</text>
|
||||
<text x="590" y="133" text-anchor="middle" class="box-detail">51 jurisdictions seeded</text>
|
||||
<text x="590" y="148" text-anchor="middle" class="box-detail">IRP, IFTA, weight tax, MCP...</text>
|
||||
|
||||
<!-- ProcessAgent.com -->
|
||||
<rect x="720" y="95" width="200" height="65" class="box" fill="#fef2f2" stroke="#ef4444"/>
|
||||
<text x="820" y="118" text-anchor="middle" class="box-label" fill="#991b1b">ProcessAgent.com</text>
|
||||
<text x="820" y="133" text-anchor="middle" class="box-detail">BOC-3 filing ($25/yr)</text>
|
||||
<text x="820" y="148" text-anchor="middle" class="box-detail">Playwright automation</text>
|
||||
|
||||
<!-- CorpTools API -->
|
||||
<rect x="950" y="95" width="200" height="65" class="box" fill="#f0fdf4" stroke="#22c55e"/>
|
||||
<text x="1050" y="118" text-anchor="middle" class="box-label" fill="#166534">CorpTools API</text>
|
||||
<text x="1050" y="133" text-anchor="middle" class="box-detail">Northwest Registered Agent</text>
|
||||
<text x="1050" y="148" text-anchor="middle" class="box-detail">RA, formations, DC agent</text>
|
||||
|
||||
<!-- ═══ ROW 2: Processing Layer ═══ -->
|
||||
<text x="50" y="200" class="section-label" fill="#3b82f6">PROCESSING</text>
|
||||
|
||||
<!-- Census Downloader -->
|
||||
<rect x="30" y="210" width="220" height="70" class="box" fill="#ffffff" stroke="#d1d5db"/>
|
||||
<text x="140" y="233" text-anchor="middle" class="box-label" fill="#111827">Census Downloader</text>
|
||||
<text x="140" y="248" text-anchor="middle" class="box-detail">fmcsa_census_downloader.py</text>
|
||||
<text x="140" y="263" text-anchor="middle" class="box-detail">Bulk ingest → fmcsa_carriers table</text>
|
||||
|
||||
<!-- Deficiency Flagger -->
|
||||
<rect x="280" y="210" width="220" height="70" class="box" fill="#ffffff" stroke="#d1d5db"/>
|
||||
<text x="390" y="233" text-anchor="middle" class="box-label" fill="#111827">Deficiency Flagger</text>
|
||||
<text x="390" y="248" text-anchor="middle" class="box-detail">fmcsa_deficiency_flagger.py</text>
|
||||
<text x="390" y="263" text-anchor="middle" class="box-detail">29,792 campaign eligible</text>
|
||||
|
||||
<!-- DOT Lookup API -->
|
||||
<rect x="530" y="210" width="220" height="70" class="box" fill="#ffffff" stroke="#d1d5db"/>
|
||||
<text x="640" y="233" text-anchor="middle" class="box-label" fill="#111827">DOT Compliance API</text>
|
||||
<text x="640" y="248" text-anchor="middle" class="box-detail">dot-lookup.ts — 14 checks</text>
|
||||
<text x="640" y="263" text-anchor="middle" class="box-detail">+ state-requirements endpoint</text>
|
||||
|
||||
<!-- Service Handlers -->
|
||||
<rect x="780" y="210" width="220" height="70" class="box" fill="#ffffff" stroke="#d1d5db"/>
|
||||
<text x="890" y="233" text-anchor="middle" class="box-label" fill="#111827">Service Handlers</text>
|
||||
<text x="890" y="248" text-anchor="middle" class="box-detail">21 DOT + state service slugs</text>
|
||||
<text x="890" y="263" text-anchor="middle" class="box-detail">MCS150 / BOC3 / StateTrucking</text>
|
||||
|
||||
<!-- Arrows: Data Sources → Processing -->
|
||||
<path d="M130 160 L140 210" class="arrow" stroke="#94a3b8"/>
|
||||
<path d="M360 160 L390 210" class="arrow" stroke="#94a3b8"/>
|
||||
<path d="M590 160 L640 210" class="arrow" stroke="#94a3b8"/>
|
||||
<path d="M820 160 L890 210" class="arrow" stroke="#94a3b8"/>
|
||||
|
||||
<!-- ═══ ROW 3: Database ═══ -->
|
||||
<text x="50" y="320" class="section-label" fill="#8b5cf6">DATABASE</text>
|
||||
|
||||
<!-- PostgreSQL tables -->
|
||||
<rect x="30" y="330" width="170" height="80" class="box" fill="#faf5ff" stroke="#8b5cf6"/>
|
||||
<text x="115" y="353" text-anchor="middle" class="box-label" fill="#6b21a8">fmcsa_carriers</text>
|
||||
<text x="115" y="368" text-anchor="middle" class="box-detail">2M+ records</text>
|
||||
<text x="115" y="383" text-anchor="middle" class="box-detail">DOT#, name, email, state</text>
|
||||
<text x="115" y="398" text-anchor="middle" class="box-detail">flags, campaign_eligible</text>
|
||||
|
||||
<rect x="220" y="330" width="170" height="80" class="box" fill="#faf5ff" stroke="#8b5cf6"/>
|
||||
<text x="305" y="353" text-anchor="middle" class="box-label" fill="#6b21a8">state_trucking_reqs</text>
|
||||
<text x="305" y="368" text-anchor="middle" class="box-detail">51 jurisdictions</text>
|
||||
<text x="305" y="383" text-anchor="middle" class="box-detail">IRP, IFTA, weight tax</text>
|
||||
<text x="305" y="398" text-anchor="middle" class="box-detail">MCP, emissions, intrastate</text>
|
||||
|
||||
<rect x="410" y="330" width="170" height="80" class="box" fill="#faf5ff" stroke="#8b5cf6"/>
|
||||
<text x="495" y="353" text-anchor="middle" class="box-label" fill="#6b21a8">compliance_orders</text>
|
||||
<text x="495" y="368" text-anchor="middle" class="box-detail">All DOT + state orders</text>
|
||||
<text x="495" y="383" text-anchor="middle" class="box-detail">Stripe/PayPal/crypto</text>
|
||||
<text x="495" y="398" text-anchor="middle" class="box-detail">$0 bypass for promos</text>
|
||||
|
||||
<rect x="600" y="330" width="170" height="80" class="box" fill="#faf5ff" stroke="#8b5cf6"/>
|
||||
<text x="685" y="353" text-anchor="middle" class="box-label" fill="#6b21a8">admin_todos</text>
|
||||
<text x="685" y="368" text-anchor="middle" class="box-detail">Filing tasks</text>
|
||||
<text x="685" y="383" text-anchor="middle" class="box-detail">State-specific steps</text>
|
||||
<text x="685" y="398" text-anchor="middle" class="box-detail">Agency URLs, portal links</text>
|
||||
|
||||
<rect x="790" y="330" width="170" height="80" class="box" fill="#faf5ff" stroke="#8b5cf6"/>
|
||||
<text x="875" y="353" text-anchor="middle" class="box-label" fill="#6b21a8">carrier_op_states</text>
|
||||
<text x="875" y="368" text-anchor="middle" class="box-detail">Per-carrier states</text>
|
||||
<text x="875" y="383" text-anchor="middle" class="box-detail">Base + operating</text>
|
||||
<text x="875" y="398" text-anchor="middle" class="box-detail">From intake/census</text>
|
||||
|
||||
<!-- ═══ ROW 4: Frontend ═══ -->
|
||||
<text x="50" y="455" class="section-label" fill="#059669">FRONTEND</text>
|
||||
|
||||
<!-- DOT Compliance Checker -->
|
||||
<rect x="30" y="465" width="230" height="90" class="box" fill="#f0fdf4" stroke="#059669"/>
|
||||
<text x="145" y="488" text-anchor="middle" class="box-label" fill="#065f46">DOT Compliance Checker</text>
|
||||
<text x="145" y="503" text-anchor="middle" class="box-detail">/tools/dot-compliance-check/</text>
|
||||
<text x="145" y="518" text-anchor="middle" class="box-detail">DOT# lookup + name search</text>
|
||||
<text x="145" y="533" text-anchor="middle" class="box-detail">14 checks + state agency links</text>
|
||||
<text x="145" y="548" text-anchor="middle" class="box-detail">Insurance lead capture</text>
|
||||
|
||||
<!-- DOT Order Page -->
|
||||
<rect x="280" y="465" width="230" height="90" class="box" fill="#f0fdf4" stroke="#059669"/>
|
||||
<text x="395" y="488" text-anchor="middle" class="box-label" fill="#065f46">DOT Order Page</text>
|
||||
<text x="395" y="503" text-anchor="middle" class="box-detail">/order/dot-compliance/</text>
|
||||
<text x="395" y="518" text-anchor="middle" class="box-detail">8 federal + 13 state services</text>
|
||||
<text x="395" y="533" text-anchor="middle" class="box-detail">Auto-preselect from checker</text>
|
||||
<text x="395" y="548" text-anchor="middle" class="box-detail">Stripe test + $0 bypass</text>
|
||||
|
||||
<!-- State Landing Pages -->
|
||||
<rect x="530" y="465" width="230" height="90" class="box" fill="#f0fdf4" stroke="#059669"/>
|
||||
<text x="645" y="488" text-anchor="middle" class="box-label" fill="#065f46">State Landing Pages</text>
|
||||
<text x="645" y="503" text-anchor="middle" class="box-detail">/services/trucking/{state}/</text>
|
||||
<text x="645" y="518" text-anchor="middle" class="box-detail">CA, TX, OR, NY, FL</text>
|
||||
<text x="645" y="533" text-anchor="middle" class="box-detail">State-specific requirements</text>
|
||||
<text x="645" y="548" text-anchor="middle" class="box-detail">SEO + campaign landing</text>
|
||||
|
||||
<!-- Pricing Page -->
|
||||
<rect x="780" y="465" width="230" height="90" class="box" fill="#f0fdf4" stroke="#059669"/>
|
||||
<text x="895" y="488" text-anchor="middle" class="box-label" fill="#065f46">Pricing + Services</text>
|
||||
<text x="895" y="503" text-anchor="middle" class="box-detail">/pricing/ + /services/trucking/</text>
|
||||
<text x="895" y="518" text-anchor="middle" class="box-detail">11 services with pricing</text>
|
||||
<text x="895" y="533" text-anchor="middle" class="box-detail">Bundle CTA ($499)</text>
|
||||
<text x="895" y="548" text-anchor="middle" class="box-detail">Free DOT check CTA</text>
|
||||
|
||||
<!-- ═══ ROW 5: Campaign / Marketing ═══ -->
|
||||
<text x="50" y="600" class="section-label" fill="#dc2626">CAMPAIGNS</text>
|
||||
|
||||
<!-- Listmonk -->
|
||||
<rect x="30" y="610" width="280" height="80" class="box" fill="#fef2f2" stroke="#dc2626"/>
|
||||
<text x="170" y="633" text-anchor="middle" class="box-label" fill="#991b1b">Listmonk Email Campaigns</text>
|
||||
<text x="170" y="648" text-anchor="middle" class="box-detail">9 state-segmented lists</text>
|
||||
<text x="170" y="663" text-anchor="middle" class="box-detail">29,792 campaign-eligible carriers</text>
|
||||
<text x="170" y="678" text-anchor="middle" class="box-detail">Dynamic {{ .Subscriber.Attribs }} personalization</text>
|
||||
|
||||
<!-- Campaign segments -->
|
||||
<rect x="340" y="610" width="180" height="80" class="box" fill="#fff1f2" stroke="#f43f5e"/>
|
||||
<text x="430" y="630" text-anchor="middle" class="box-label" fill="#9f1239">Federal Segment</text>
|
||||
<text x="430" y="648" text-anchor="middle" class="box-detail">MCS-150 overdue: 19,176</text>
|
||||
<text x="430" y="663" text-anchor="middle" class="box-detail">For-hire: 19,811</text>
|
||||
<text x="430" y="678" text-anchor="middle" class="box-detail">Interstate IRP/IFTA: 19,761</text>
|
||||
|
||||
<rect x="540" y="610" width="180" height="80" class="box" fill="#fff1f2" stroke="#f43f5e"/>
|
||||
<text x="630" y="630" text-anchor="middle" class="box-label" fill="#9f1239">State Segment</text>
|
||||
<text x="630" y="648" text-anchor="middle" class="box-detail">CA MCP/CARB: 3,418</text>
|
||||
<text x="630" y="663" text-anchor="middle" class="box-detail">Weight tax: 6,289</text>
|
||||
<text x="630" y="678" text-anchor="middle" class="box-detail">Intrastate auth: 14,081</text>
|
||||
|
||||
<rect x="740" y="610" width="180" height="80" class="box" fill="#fff1f2" stroke="#f43f5e"/>
|
||||
<text x="830" y="630" text-anchor="middle" class="box-label" fill="#9f1239">Subscribe Modal</text>
|
||||
<text x="830" y="648" text-anchor="middle" class="box-detail">Interest: Telecom / Trucking</text>
|
||||
<text x="830" y="663" text-anchor="middle" class="box-detail"> / Formation</text>
|
||||
<text x="830" y="678" text-anchor="middle" class="box-detail">Routes to correct list</text>
|
||||
|
||||
<!-- ═══ ROW 6: Order Flow ═══ -->
|
||||
<text x="50" y="735" class="section-label" fill="#0891b2">ORDER FLOW</text>
|
||||
|
||||
<!-- Flow boxes -->
|
||||
<rect x="30" y="745" width="130" height="50" class="box" fill="#ecfeff" stroke="#0891b2"/>
|
||||
<text x="95" y="768" text-anchor="middle" class="box-label" fill="#0e7490">Free Check</text>
|
||||
<text x="95" y="783" text-anchor="middle" class="box-detail">14 compliance checks</text>
|
||||
|
||||
<rect x="190" y="745" width="130" height="50" class="box" fill="#ecfeff" stroke="#0891b2"/>
|
||||
<text x="255" y="768" text-anchor="middle" class="box-label" fill="#0e7490">Select Services</text>
|
||||
<text x="255" y="783" text-anchor="middle" class="box-detail">Pre-selected from CTA</text>
|
||||
|
||||
<rect x="350" y="745" width="130" height="50" class="box" fill="#ecfeff" stroke="#0891b2"/>
|
||||
<text x="415" y="768" text-anchor="middle" class="box-label" fill="#0e7490">Checkout</text>
|
||||
<text x="415" y="783" text-anchor="middle" class="box-detail">Stripe / $0 bypass</text>
|
||||
|
||||
<rect x="510" y="745" width="130" height="50" class="box" fill="#ecfeff" stroke="#0891b2"/>
|
||||
<text x="575" y="768" text-anchor="middle" class="box-label" fill="#0e7490">Confirmation</text>
|
||||
<text x="575" y="783" text-anchor="middle" class="box-detail">"We're on it" email</text>
|
||||
|
||||
<rect x="670" y="745" width="130" height="50" class="box" fill="#ecfeff" stroke="#0891b2"/>
|
||||
<text x="735" y="768" text-anchor="middle" class="box-label" fill="#0e7490">Worker</text>
|
||||
<text x="735" y="783" text-anchor="middle" class="box-detail">Handler dispatched</text>
|
||||
|
||||
<rect x="830" y="745" width="140" height="50" class="box" fill="#ecfeff" stroke="#0891b2"/>
|
||||
<text x="900" y="768" text-anchor="middle" class="box-label" fill="#0e7490">Filing Complete</text>
|
||||
<text x="900" y="783" text-anchor="middle" class="box-detail">Confirm to customer</text>
|
||||
|
||||
<!-- Flow arrows -->
|
||||
<path d="M160 770 L190 770" class="arrow" stroke="#0891b2" marker-end="url(#arrowhead)"/>
|
||||
<path d="M320 770 L350 770" class="arrow" stroke="#0891b2" marker-end="url(#arrowhead)"/>
|
||||
<path d="M480 770 L510 770" class="arrow" stroke="#0891b2" marker-end="url(#arrowhead)"/>
|
||||
<path d="M640 770 L670 770" class="arrow" stroke="#0891b2" marker-end="url(#arrowhead)"/>
|
||||
<path d="M800 770 L830 770" class="arrow" stroke="#0891b2" marker-end="url(#arrowhead)"/>
|
||||
|
||||
<!-- Revenue box -->
|
||||
<rect x="30" y="825" width="940" height="55" class="box" fill="#fefce8" stroke="#eab308"/>
|
||||
<text x="500" y="848" text-anchor="middle" class="box-label" fill="#854d0e">Revenue Model</text>
|
||||
<text x="500" y="868" text-anchor="middle" class="box-detail">Federal: $69-$499 | State: $99-$599 | BOC-3 margin: $64 ($89 retail - $25 wholesale) | CA MCP: $349 x 3,418 carriers = $1.19M potential | Est. $138K/mo at 0.05% conversion</text>
|
||||
|
||||
<!-- Version -->
|
||||
<text x="1170" y="893" text-anchor="end" font-size="9" fill="#94a3b8">v2.0 — 2026-05-29</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 15 KiB |
210
docs/trucking-system.md
Normal file
210
docs/trucking-system.md
Normal file
|
|
@ -0,0 +1,210 @@
|
|||
# Trucking / DOT Compliance System
|
||||
|
||||
**Last updated:** 2026-05-29
|
||||
|
||||
See also:
|
||||
- [Trucking Architecture Diagram](trucking-architecture.svg)
|
||||
- [FMCSA Product Plan](fmcsa-trucking-plan.md)
|
||||
- [System Architecture](architecture.md)
|
||||
|
||||
## Overview
|
||||
|
||||
Performance West's trucking vertical provides DOT/FMCSA compliance services to 2M+ US motor carriers. The system covers federal FMCSA requirements and state-level obligations across all 50 states + DC.
|
||||
|
||||
## Data Pipeline
|
||||
|
||||
```
|
||||
FMCSA Socrata API (data.transportation.gov)
|
||||
|
|
||||
v
|
||||
fmcsa_census_downloader.py ──> fmcsa_carriers table (2M+ records)
|
||||
| - dot_number, legal_name, email
|
||||
| - phy_state, fleet size, MCS-150 date
|
||||
| - carrier_operation (A=Interstate, B=Intra HM, C=Intra)
|
||||
v
|
||||
fmcsa_deficiency_flagger.py ──> deficiency_flags, campaign_eligible
|
||||
| - MCS-150 overdue/severe
|
||||
| - For-hire, hazmat, zero fleet
|
||||
| - Interstate IRP/IFTA needs
|
||||
| - State weight tax, carrier permit, emissions
|
||||
| - Intrastate authority
|
||||
v
|
||||
Listmonk lists ──> Email campaigns (state-segmented)
|
||||
- FMCSA MCS-150 Overdue Carriers
|
||||
- FMCSA State - California (MCP/CARB)
|
||||
- FMCSA State - Oregon (Weight-Mile Tax)
|
||||
- FMCSA State - New York (HUT)
|
||||
- FMCSA State - Kentucky (KYU)
|
||||
- FMCSA State - Texas
|
||||
- FMCSA State - Florida
|
||||
- FMCSA State - Connecticut (HUF)
|
||||
- FMCSA State - New Mexico (WDT)
|
||||
```
|
||||
|
||||
## Compliance Checker
|
||||
|
||||
**Endpoint:** `GET /api/v1/dot/lookup?dot=XXXXXX`
|
||||
|
||||
### Federal Checks (1-7) — from FMCSA QCMobile API
|
||||
| # | Check | Source | Colors |
|
||||
|---|-------|--------|--------|
|
||||
| 1 | Operating Status | FMCSA API `allowedToOperate` | Green/Red |
|
||||
| 2 | MCS-150 Biennial Update | Census + API `mcs150Outdated` | Green/Yellow/Red |
|
||||
| 3 | Insurance (BIPD/Cargo/Bond) | FMCSA API `*InsuranceOnFile` | Green/Red per type |
|
||||
| 4 | Safety Rating | FMCSA API `safetyRating` (S/C/U) | Green/Yellow/Red |
|
||||
| 5 | Operating Authority | FMCSA API `*AuthorityStatus` | Green/Red |
|
||||
| 6 | Out-of-Service Rate | FMCSA API `*OosRate` vs national avg | Green/Yellow/Red |
|
||||
| 7 | Crash Record | FMCSA API `crashTotal`/`fatalCrash` | Green/Yellow/Red |
|
||||
|
||||
### State Checks (8-14) — from state_trucking_requirements table
|
||||
| # | Check | Trigger | Color |
|
||||
|---|-------|---------|-------|
|
||||
| 8 | IRP Registration | Interstate (carrier_op=A) + IRP state | Yellow |
|
||||
| 9 | IFTA Fuel Tax | Interstate + IFTA state | Yellow |
|
||||
| 10 | Weight/Distance Tax | phy_state in OR/NY/KY/NM/CT | Yellow |
|
||||
| 11 | State Carrier Permit | State requires (CA MCP, etc.) | Yellow |
|
||||
| 12 | Emissions (CARB/ACT) | State has emissions program | Yellow |
|
||||
| 13 | Intrastate Authority | For-hire + state requires | Yellow |
|
||||
| 14 | State DOT Number | State requires (CA, TX) | Yellow |
|
||||
|
||||
**State Requirements API:** `GET /api/v1/dot/state-requirements?base_state=CA&operating_states=CA,OR,NV`
|
||||
|
||||
Returns structured requirements per state + recommended services with pricing.
|
||||
|
||||
## Services Catalog
|
||||
|
||||
### Federal DOT Services
|
||||
| Slug | Service | Price | Handler |
|
||||
|------|---------|-------|---------|
|
||||
| `mcs150-update` | MCS-150 Biennial Update | $69 | MCS150UpdateHandler (admin todo) |
|
||||
| `boc3-filing` | BOC-3 Process Agent Filing | $89 | BOC3FilingHandler (Playwright → processagent.com) |
|
||||
| `ucr-registration` | UCR Annual Registration | $69 + gov | MCS150UpdateHandler |
|
||||
| `dot-registration` | New USDOT Number | $89 | MCS150UpdateHandler |
|
||||
| `mc-authority` | MC Operating Authority | $349 + $300 | MCS150UpdateHandler |
|
||||
| `dot-drug-alcohol` | D&A Compliance Program | $149/yr | MCS150UpdateHandler |
|
||||
| `dot-audit-prep` | Safety Audit Prep | $399 | MCS150UpdateHandler |
|
||||
| `dot-full-compliance` | DOT Full Bundle | $499 | MCS150UpdateHandler |
|
||||
|
||||
### State Trucking Services
|
||||
| Slug | Service | Price | Handler |
|
||||
|------|---------|-------|---------|
|
||||
| `irp-registration` | IRP Registration | $199 | StateTruckingHandler |
|
||||
| `ifta-application` | IFTA Application + Decals | $149 | StateTruckingHandler |
|
||||
| `ifta-quarterly` | IFTA Quarterly Filing | $99 | StateTruckingHandler |
|
||||
| `or-weight-mile-tax` | Oregon Weight-Mile Tax | $199 | StateTruckingHandler |
|
||||
| `ny-hut-registration` | NY Highway Use Tax | $199 | StateTruckingHandler |
|
||||
| `ky-kyu-registration` | KY Weight-Distance Tax | $199 | StateTruckingHandler |
|
||||
| `nm-weight-distance` | NM Weight-Distance Tax | $199 | StateTruckingHandler |
|
||||
| `ct-highway-use-fee` | CT Highway Use Fee | $199 | StateTruckingHandler |
|
||||
| `ca-mcp-carb` | California MCP + CARB | $349 | StateTruckingHandler |
|
||||
| `state-dot-registration` | State DOT Registration | $149 | StateTruckingHandler |
|
||||
| `intrastate-authority` | Intrastate Authority | $249 | StateTruckingHandler |
|
||||
| `osow-permit` | Oversize/Overweight Permit | $99 | StateTruckingHandler |
|
||||
| `state-trucking-bundle` | State Compliance Bundle | $599 | StateTruckingHandler |
|
||||
|
||||
## Vendors
|
||||
|
||||
| Vendor | Service | Cost | Integration |
|
||||
|--------|---------|------|-------------|
|
||||
| **Process Agent LLC** (Registered Agents Inc) | BOC-3 blanket filing | $25/yr | Playwright on processagent.com |
|
||||
| **Northwest Registered Agent** (CorpTools API) | DC registered agent, formations | Varies | REST API (JWT auth) |
|
||||
| **National Drug Screening** | D&A testing programs | TBD | Reseller program (pending) |
|
||||
| **Tivly** | Insurance referrals | Commission | Affiliate (pending) |
|
||||
|
||||
## Database Tables
|
||||
|
||||
| Table | Migration | Purpose |
|
||||
|-------|-----------|---------|
|
||||
| `fmcsa_carriers` | 078 | 2M+ carrier census records |
|
||||
| `state_trucking_requirements` | 079 | 51-jurisdiction state requirements |
|
||||
| `carrier_operating_states` | 080 | Per-carrier operating state tracking |
|
||||
| `compliance_orders` | (existing) | All DOT + state orders |
|
||||
| `admin_todos` | (existing) | Admin filing tasks |
|
||||
|
||||
### Key Indexes on fmcsa_carriers
|
||||
- `dot_number` (PK)
|
||||
- `email_address`
|
||||
- `phy_state`
|
||||
- `mcs150_parsed`
|
||||
- `authorized_for_hire`
|
||||
- `campaign_eligible`
|
||||
|
||||
## Frontend Pages
|
||||
|
||||
| Page | Path | Type |
|
||||
|------|------|------|
|
||||
| DOT Compliance Check | `/tools/dot-compliance-check/` | Static HTML |
|
||||
| DOT Order Page | `/order/dot-compliance/` | Static HTML |
|
||||
| Trucking Services | `/services/trucking/` | Static HTML |
|
||||
| California Compliance | `/services/trucking/california/` | Static HTML |
|
||||
| Texas Compliance | `/services/trucking/texas/` | Static HTML |
|
||||
| Oregon Compliance | `/services/trucking/oregon/` | Static HTML |
|
||||
| New York Compliance | `/services/trucking/new-york/` | Static HTML |
|
||||
| Florida Compliance | `/services/trucking/florida/` | Static HTML |
|
||||
| Pricing (Trucking section) | `/pricing/` | Static HTML |
|
||||
| 8 DOT intake pages | `/order/{slug}/` | Astro (review-only) |
|
||||
|
||||
## Order Flow
|
||||
|
||||
```
|
||||
1. Carrier visits /tools/dot-compliance-check
|
||||
|
|
||||
2. Enters DOT# → API returns 14 checks (7 federal + 7 state)
|
||||
|
|
||||
3. CTA: "Fix My DOT Filings" → /order/dot-compliance?dot=X&services=Y&state=Z
|
||||
|
|
||||
4. Selects services (federal + state pre-selected from checker)
|
||||
|
|
||||
5. Stripe checkout ($0 bypass if promo covers total)
|
||||
|
|
||||
6. Confirmation email: "Order Confirmed — we're on it"
|
||||
|
|
||||
7. Worker dispatches to handler:
|
||||
├── BOC3FilingHandler → Playwright on processagent.com ($25)
|
||||
├── MCS150UpdateHandler → admin todo (Login.gov MFA)
|
||||
└── StateTruckingHandler → admin todo (state-specific steps)
|
||||
|
|
||||
8. Admin completes filing → sends confirmation to customer
|
||||
```
|
||||
|
||||
## Campaign Segmentation
|
||||
|
||||
| Segment | Count | Criteria |
|
||||
|---------|-------|----------|
|
||||
| All with email | 49,186 | email_address IS NOT NULL |
|
||||
| Campaign eligible | 29,792 | Has actionable flags, not stale |
|
||||
| Interstate (IRP/IFTA) | 19,761 | carrier_operation = 'A' |
|
||||
| MCS-150 overdue | 19,176 | mcs150_parsed < 2 years ago |
|
||||
| For-hire carriers | 19,811 | authorized_for_hire = TRUE |
|
||||
| Intrastate authority needed | 14,081 | For-hire in 29 states |
|
||||
| Emissions states | 12,424 | CARB/ACT states |
|
||||
| Weight-tax states | 6,289 | OR/NY/KY/NM/CT |
|
||||
| CA MCP/CARB needed | 3,418 | phy_state = CA |
|
||||
|
||||
Note: Census currently has 100K of 2M records. Full download will 5-10x these numbers.
|
||||
|
||||
## Key Files
|
||||
|
||||
```
|
||||
api/
|
||||
src/routes/dot-lookup.ts — compliance checker API (14 checks + state reqs)
|
||||
src/routes/compliance-orders.ts — 21 DOT service slugs in COMPLIANCE_SERVICES
|
||||
src/routes/checkout.ts — DOT_SLUGS set for "Order Confirmed" email
|
||||
migrations/078_fmcsa_carriers.sql
|
||||
migrations/079_state_trucking_requirements.sql
|
||||
migrations/080_carrier_operating_states.sql
|
||||
|
||||
scripts/workers/
|
||||
fmcsa_census_downloader.py — Socrata API bulk download
|
||||
fmcsa_deficiency_flagger.py — flag carriers + populate Listmonk lists
|
||||
services/mcs150_update.py — MCS-150 handler (admin todo)
|
||||
services/boc3_filing.py — BOC-3 handler (Playwright + admin fallback)
|
||||
services/boc3_playwright.py — processagent.com Playwright automation
|
||||
services/state_trucking.py — all state services (admin todo)
|
||||
|
||||
site/
|
||||
public/tools/dot-compliance-check/ — compliance checker frontend
|
||||
public/order/dot-compliance/ — batch order page
|
||||
public/services/trucking/ — landing pages (main + 5 states)
|
||||
src/lib/intake_manifest.ts — DOT + state service manifests
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue