# AxleWise.ai — Project Knowledge Map
> A mobile-first car-hauler load optimizer + safety/route/dispatch suite, plus a Cloudflare-hosted marketing site. This doc is my long-term memory: read it first whenever I'm picking the project back up.
**Tagline:** *Load Smart. Drive Safe.*
**Brand lockup:** AxleWise.ai LLC — amber accent `#F59E0B` on near-black `#0F0F0F`.
**Repo entity:** `AxleWise.ai LLC` (`app.rork.axlewise-truck-load-optimizer-hnektpz`).
---
## 1. The 30-second pitch
Car-hauler drivers (the guys moving 9 cars on a stinger or wedge from auction → dealer) live and die by axle weight, deck height, and bridge clearance. One bad load = $300–$10k fine, DOT violation, or a $50k bridge strike. AxleWise turns "draw it on a napkin + hope the scale agrees" into a one-tap solve: pick tractor → pick carrier → pick cars → it computes axle distribution, deck clearance, GVW, height, and tells you where each car goes.
Stretched into a platform: it's also their **safety co-pilot** (pre-trip inspection, incident log, compliance, damage diagrams), **route planner** (bridge DB, clearance check, hazard map), and **dispatcher comms** (messages + alerts).
Pro tier (RevenueCat): unlocks Fuel Level Adjustment (let drivers tell the calc they're running half-tank → reclaim weight headroom for one more car) + future power features.
---
## 2. Top-level tree
```
axlewise.ai/
├── expo/ ← the React Native app (Expo Router, SDK 54, RN 0.81)
│ ├── app/ ← file-based routes
│ │ ├── _layout.tsx ← provider stack + Stack nav (modal screens declared here)
│ │ ├── (tabs)/ ← 5 visible tabs + 4 hidden routes
│ │ │ ├── _layout.tsx ← tab bar (dark theme, amber accent)
│ │ │ ├── (home)/ ← Home dashboard (CTA, fleet stats, recent loads)
│ │ │ ├── optimizer/ ← THE core feature — 3-step wizard + results
│ │ │ ├── routes/ ← Route list, bridge DB, route detail
│ │ │ ├── safety/ ← Dashboard, inspection, incidents, compliance, damage
│ │ │ ├── profile/ ← User, history, settings, help, about
│ │ │ ├── vehicles/ ← Browse tractors/carriers/cars DB (hidden tab)
│ │ │ ├── measure/ ← Camera AR measure + 3D vehicle viewer (hidden)
│ │ │ ├── messages/ ← Chat + alerts (hidden)
│ │ │ └── shortcuts/ ← Saved setups (hidden)
│ │ ├── paywall.tsx ← RevenueCat paywall (Pro tier)
│ │ ├── request-specs.tsx ← User submits missing vehicle specs
│ │ ├── pitch-deck.tsx ←┐
│ │ ├── pitch-slides.tsx ← │ Investor / founder collateral
│ │ ├── financial-model.tsx ← │ (rendered as in-app modals — bake'd into the app
│ │ ├── expense-projections │ │ so I can demo the pitch on a phone)
│ │ ├── go-to-market.tsx ← │
│ │ ├── gtm-dashboard.tsx ← │
│ │ ├── launch-checklist ←┤
│ │ └── ad-scripts.tsx ←┘
│ ├── components/ ← Reusable UI (CarrierVisual, RouteMap, WeightGauge…)
│ ├── hooks/ ← Context hooks (state) — see §4
│ ├── mocks/ ← Static datasets (cars: 2k LOC, tractors: 1.7k, carriers: 2k, bridges, routes, safety, messages)
│ ├── types/ ← TS types (vehicles, routes, safety, messages)
│ ├── utils/ ← loadCalculator (the math brain), mapService, measurementEngine
│ ├── constants/colors.ts ← Single dark theme
│ ├── backend/ ← Hono + tRPC scaffold (mostly idle right now)
│ └── lib/trpc.ts ← tRPC client
│
├── landing/ ← Cloudflare Pages site (static HTML)
│ ├── index.html ← Hero w/ faux-video reel (Stage A done), features, fuel-pro card
│ ├── privacy.html
│ ├── sitemap.xml, robots.txt, og.jpg
│ ├── google0c5fe369f3192bdb.html ← Search Console verification file
│ └── worker/waitlist-worker.js ← Cloudflare Worker for waitlist signups
│
├── PLAN.md ← Active hero-video rollout plan
└── KNOWLEDGE.md ← (this file)
```
---
## 3. App map — every screen, what it does
### Tab bar (visible: 5)
| Tab | Route | Purpose |
|---|---|---|
| 🏠 Home | `(tabs)/(home)/index.tsx` | Hero CTA → Optimizer. Safety-score chip. Alert banner for open incidents. 2×2 quick grid (Routes, Safety, Vehicles, Dispatch). Fleet counts, load analytics (total/legal/success-rate), recent 3 loads, saved-setup shortcuts, "Request Missing Specs". |
| ⚖️ Optimizer | `(tabs)/optimizer/index.tsx` + `results.tsx` | 3-step accordion wizard: **Tractor → Carrier → Cars**. Each step has compact brand/style/category chip rows (horizontal scroll, "All" button), search bar, and model list. +/- qty per car, custom-vehicle modal. Cap = `carrier.totalPositions`. Shortcut button (Scale icon) jumps straight to "Calculate Optimal Load" from anywhere in the scroll. Results screen: deck grid with tap-empty-slot-to-add-car picker, swap/remove cars, rejected-car reasons, axle gauges, height/clearance violations. |
| 🛣 Routes | `(tabs)/routes/index.tsx` + `route-detail.tsx` + `bridge-database.tsx` | Route cards (status, hazards, distance/time, blocked-clearance badge). Map preview via `RouteMap`. New-route modal: origin/dest state pickers + 4 vehicle-height presets → runs `findBridgeHazards` against state-filtered bridge DB. |
| 🛡 Safety | `(tabs)/safety/index.tsx` + 4 sub | SafetyScoreRing, 4 stat cards, 4 quick actions (Pre-Trip Inspection / Incident Log / Compliance / Damage Assessment), badges (bronze→platinum), open-incidents banner, recent activity feed. |
| 👤 Profile | `(tabs)/profile/index.tsx` + 5 sub | Pro upgrade banner (if not subbed), avatar+stats, Badges row, sectioned menu: Activity • Tools • **Investor** • **Launch Command** • App. Brand footer. |
### Hidden tabs (`href: null`, reached via deep links/nav)
- `vehicles/` — browse tractors/carriers/cars DB with detail screen
- `measure/` — `camera-measure.tsx` (AR-style measure via `expo-camera` + sensors) + `vehicle-3d.tsx` (SVG 3D viewer in `Vehicle3DModel.tsx`, 973 LOC)
- `messages/` — chat + alerts (mock dispatcher comms)
- `shortcuts/` — saved load setups
### Modal screens (Stack-presented from root)
`request-specs`, `paywall`, `pitch-deck`, `pitch-slides`, `financial-model`, `expense-projections`, `go-to-market`, `gtm-dashboard`, `launch-checklist`, `ad-scripts`.
---
## 4. State architecture
Provider order in `app/_layout.tsx` (outer → inner):
```
trpc.Provider
└── QueryClientProvider (React Query)
└── GestureHandlerRootView
└── AppStateProvider (saved setups, custom cars, spec requests)
└── SafetyStateProvider (incidents, inspections, profile, damage)
└── MessagingProvider (conversations, alerts)
└── LoadHistoryProvider (every calc result)
└── RevenueCatProvider (isPro, offerings)
└── +
```
All hooks use `@nkzw/create-context-hook` + React Query + AsyncStorage. **Storage keys** (all prefixed `axlewise_`): `saved_setups`, `spec_requests`, `custom_cars`, `safety_incidents`, `inspections`, `driver_profile`, `load_assessments`, `damage_assessments`, plus load history + messaging.
| Hook | Owns |
|---|---|
| `useAppState` | savedSetups, customCars, specRequests + add/remove |
| `useSafetyState` | incidents, inspections, complianceRules, driverProfile, damageAssessments |
| `useRoutePlanner` | routes, `createRoute(NewRouteInput)` w/ bridge-hazard scan |
| `useMessaging` | conversations, alerts, unread counts |
| `useLoadHistory` | every saved calc (used for analytics on Home) |
| `useRevenueCat` | `isPro`, offerings, purchase, restore. Skips native Purchases module under Expo Go. |
| `useVehicleData` | thin selector over mocks |
---
## 5. The core math: `utils/loadCalculator.ts` (612 LOC)
Constants:
- `FEDERAL_GVW_LIMIT = 80,000 lb`
- `DRIVE_AXLE_LIMIT = 34,000 lb`
- `TRAILER_TANDEM_LIMIT = 34,000 lb`
- `MAX_HEIGHT_INCHES = 162` (13'6")
Inputs: tractor + carrier + cars[]. Outputs `LoadResult` with per-axle weight, % of limit, height check, deck-clearance violations, rejected cars, warnings.
**Key idea:** curb weight is the heaviest legal assumption (already includes a full fuel tank). The Pro "Fuel Level Adjustment" lets drivers shave headroom to fit one more car — it's an upside, not a safety override.
---
## 6. Data model TL;DR (`types/vehicles.ts`)
- **Car** — make, model, year(+optional yearRange), curbWeight, length/width/height, wheelbase, category (sedan/suv/truck/compact/van/coupe/sports).
- **Tractor** — gvwr, gcwr, fifth-wheel spec, axle config (4x2…8x6), engine/transmission, fuel type, emissions, *cabStyle*, *suspension*.
- **Carrier** — emptyWeight, maxPayload, totalPositions (upper+lower), per-deck max height, axle layout, `style` (open/enclosed/stinger/highmount/wedge), full `adjustments` block (sliding tandem, hydraulic decks, ramps, kingpin, drop pockets).
- **LoadPosition** — { position, level: upper/lower, car|null, label, facing }.
- **SavedSetup**, **SpecRequest** — user-generated.
Mock library is HEFTY: 2,031 lines of cars, 1,748 of tractors, 1,958 of carriers, 183 bridges, 714 of routes. This is the moat — real data drivers can search instantly.
---
## 7. Design language
- **Dark only.** `bg #0F0F0F`, surface ladder `#1A1A1A → #242424 → #2E2E2E`.
- **Accent:** amber `#F59E0B` (with `accentLight #FBBF24`, `accentDim #92400E`).
- **Semantic:** success `#10B981`, danger `#EF4444`, info `#3B82F6`.
- Type: heavy weights (700–900) for headlines, rounded (14–20 radius) cards, generous borders at `#2A2A2A`.
- Heavy use of haptics (`expo-haptics`) on every tap; animated scale on press; pulse animation on hero CTA.
---
## 8. Landing site (`landing/`)
- Static HTML on Cloudflare Pages at `rork-axlewise--truck-load-optimizer.pages.dev`.
- **Hero** shows the final **real AI-generated video** (Stage B complete): `hero_video_v2.mp4` (~24s) with voiceover, cinematic music, and 5 real scenes. Player chrome: REC pill, mute, animated scrubber, captions. Replaces the old OPTIMIZE button + Stage A CSS reel.
- Fuel Level Adjustment featured as a **PRO** card (amber tag). Features grid: 7 cards + 1 Pro. Old Way vs AxleWise comparison table. 3 driver testimonials. Dark theme with grain texture overlay + amber gradients.
- Meta + JSON-LD (`Organization`, `WebSite`, `MobileApplication`) for SEO.
- Inline SVG favicon (amber "A"). Custom domain `axlewise.ai` live on Cloudflare Pages.
- Google Search Console verified.
- Waitlist signups flow to `worker/waitlist-worker.js` (Cloudflare Worker) → Resend email.
- App Store + Google Play "Coming Soon" badges.
- Auto-deploys on every GitHub push (~30–60s).
---
## 9. Known nits & functional sanity check
✅ Type-safe everywhere, `as const` on style literals, optional chaining, React Query for server-shaped state.
✅ `RevenueCatProvider` correctly guards `react-native-purchases` under Expo Go.
✅ Provider order matches house rule (QueryClient/trpc on top).
✅ Vehicle images overhauled: 21 brand/style/category-level AI-generated photos replace broken placeholder URLs. Tractors use brand-level images (9 brands), carriers use style-level (5 styles), cars use category-level (7 categories). No more John Deere farm tractor confusion.
✅ Optimizer UX polished: compact horizontal chip rows with "All" filter, shortcut button jumps to Calculate, empty slots on results grid are tappable to add cars.
✅ `AXLEWISE_REFERENCE.md` created (652 LOC) — definitive single-file reference covering project structure, screens, state, data model, feature inventory, launch readiness checklist.
⚠️ `(tabs)/optimizer/index.tsx` is 1,275+ LOC — could be split into sub-components if it grows again.
⚠️ Backend (`backend/hono.ts` + tRPC) is scaffolded but not actively used by screens; routes/mocks are all client-side.
⚠️ Cars/tractors/carriers mocks are 1,700–2,000 LOC each — fine for now, but slow to scan; consider splitting by make when adding more.
⚠️ A few screens reference routes like `/profile/load-history` and `/safety/incidents` — make sure relative `./` paths stay consistent (some are absolute, some relative; I've seen both styles in the code).
---
## 10. Re-orientation checklist for future me
When picking this back up cold:
1. **Read this file first.** Then `PLAN.md` for active work.
2. **Open `expo/app/(tabs)/optimizer/index.tsx`** — that's the spine of the product.
3. **Open `expo/utils/loadCalculator.ts`** — that's the spine of the math.
4. **Open `landing/index.html`** — the marketing surface I'm tuning for conversions.
5. **Skim `expo/hooks/`** for state ownership before adding anything new.
6. Mocks live in `expo/mocks/` — never invent data, extend the existing pattern.
7. Brand assets: amber `#F59E0B` on `#0F0F0F`, "Load Smart. Drive Safe.", AxleWise.ai LLC.
8. The four taglines I've tested: *"Balance axles. Dodge fines. Haul more cars."* (current OG/meta) — keep this voice.
---
## 11. ASCII feature map
```
┌──────────────────────┐
│ HOME (CTA) │
└──────────┬───────────┘
│
┌────────┬──────────┬─────┴─────┬───────────┬──────────┐
▼ ▼ ▼ ▼ ▼ ▼
OPTIMIZER ROUTES SAFETY PROFILE VEHICLES MESSAGES
│ │ │ │ │ │
┌───┼──┐ ┌──┴───┐ ┌────┼────┐ ┌────┼────┐ detail chat
│ │ │ │ │ │ │ │ │ │ │ alerts
trac car list │ insp inc com load sett
carr bridge dam hist help
detail about
└→ Investor pack
(10 modal screens)
└→ Launch Command
(dashboard/checklist/ads)
└→ Paywall (RevenueCat)
└ PRO: Fuel Adjustment
```
---
*Last refreshed: 2026-06-01.*