justin/new-site
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
new-site/docs/trucking-architecture.svg
justin ba3eb30b58 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>
2026-05-29 14:10:57 -05:00

234 lines
15 KiB
XML
Raw Blame History

<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>
Reference in a new issue View git blame Copy permalink