Building the LS Swap Tool: A Data-Driven Engine Swap Planner

If you've ever stood in a garage staring at an engine bay and wondering "will this actually fit?", you know the pain. LS swaps are the most popular engine conversion in the world — but the compatibility matrix between engines, transmissions, oil pans, engine mounts, and vehicle chassis is a nightmare of tribal knowledge spread across forum threads, Facebook groups, and faded PDFs. The LS Swap Tool replaces that mess with a single source of truth.

Live at lsswap.solidrust.net, the tool is a full-stack web application that lets you browse 16 vehicle platforms, 15 LS engines, 16 transmissions, and 770+ components — all cross-referenced against 14 compatibility rules that prevent known bad combinations. It answers the one question that matters: what do I need to buy to put this engine in that car?

The Problem: LS Swap Knowledge is Scattered

The GM LS engine family (Gen III and IV, 1997–2015) is arguably the most versatile internal combustion engine platform ever built. They end up in everything: classic muscle cars, 4x4 trucks, Miatas, BMWs, RX-7s, even boats and airplanes. The aftermarket support is staggering.

But planning a swap requires answering a cascade of compatibility questions:

• Oil pan: Will the stock truck pan clear the crossmember on a 3rd-gen F-Body? (Spoiler: it won't. You need an F-Body pan, a Holley 302-1/302-2, or a Moroso 20140.)
• Reluctor wheel: Is your engine 24x or 58x? The ECU you pick has to match — get it wrong and you get no spark.
• Throttle body: Cable-driven or drive-by-wire? The pedal assembly, TAC module, and harness all change depending on this one detail.
• Transmission bolt pattern: An LS7 will physically bolt to a 4L60E, but the torque converter spacing is wrong. That combination will destroy itself.
• Accessory drive: Will the alternator clear the steering box? Will the A/C compressor hit the frame rail?

The information exists — buried in 40-page build threads on LS1Tech, scattered across Holley's catalog PDFs, encoded in the tribal knowledge of forums. But there's no single source that pulls it all together and validates the combinations programmatically.

What the Tool Does

The LS Swap Tool is a React 19 single-page application backed by a FastAPI REST API and a PostgreSQL 16 database. It covers the full swap planning workflow across seven routes:

Vehicle Browser

The landing page presents all 16 supported platforms as cards with generation info and year ranges. It's not just GM vehicles — the database includes popular swap recipients like the Mazda Miata (NA/NB), RX-7 (FC and FD), BMW 3-Series (E36 and E46), and Nissan 240SX (S13 and S14). Click any vehicle to see its specifications and a ranked list of compatible engines.

The vehicle detail page shows displacement, stock engine family, transmission options from the factory, and — crucially — which LS engines will physically fit in the engine bay with what modifications. Each compatible engine entry explains what's needed: "bolts to stock mounts," "requires aftermarket K-member," "needs notched oil pan."

Swap Planner

This is the killer feature. Pick a vehicle, pick an engine, and the planner walks you through three steps:

1. Engine Selection: Choose your LS variant (LM7, LQ4, LS1, LS3, LS7, LSA, etc.) with horsepower, torque, and displacement specs shown inline.
2. Transmission Matching: See which transmissions are compatible with your chosen engine — automatics (4L60E, 4L80E, 6L80E), manuals (T56, TR-6060, CD009), and what crossmember or tunnel modifications are needed.
3. Parts List: A complete bill of materials — oil pan, engine mounts, headers, wiring harness, ECU, fuel system, cooling system, accessory drive, clutch/flywheel, driveshaft — all validated against the vehicle-engine combination with part numbers and manufacturer links.

Components Database

A searchable, filterable catalog of 55+ components across 11 categories: oil pans (30), headers (23), engine mounts (35), wiring harnesses (18), cooling systems (23), fuel systems (17), accessory drives (20), clutch/flywheel kits (11), and more. Filter by category, manufacturer, or free-text search.

Builds Gallery

Twenty documented real-world builds with photos, parts lists, and notes. Filter by vehicle platform or engine to see what other people have actually done — not just what the compatibility matrix says should work, but what's been proven on the road.

Cost Estimator

A line-item cost breakdown for any vehicle-engine combination. See estimated prices for every component category (engine, transmission, mounts, headers, wiring, fuel system, cooling, etc.) with a running total. Prices are sourced from current aftermarket catalogs and updated periodically.

The Tech Stack

This is a modern production-grade stack, not a WordPress plugin:

Layer	Technology	Why
Frontend	React 19, Vite, TypeScript, Tailwind CSS 4, TanStack Query	Fast builds, type-safe API contracts, dark-themed responsive UI
Backend	FastAPI (Python 3.12), asyncpg	Async database access, auto-generated OpenAPI docs, Pydantic validation
Database	PostgreSQL 16	Relational integrity for compatibility rules, full-text search for components
Cache	Valkey 9.0	Redis-compatible drop-in, caches frequent queries (engine specs, vehicle lists)
Deployment	GitHub Pages (frontend), Kubernetes (API)	Static SPA on CDN, containerized API on the SolidRusT cluster
CI/CD	Gitea Actions, FluxCD, Kustomize	GitOps pipeline — push to main, auto-deploy to production

The Compatibility Engine

The heart of the tool is 14 compatibility rules encoded as database constraints and validated at the API layer. These rules encode hard-won lessons from the LS swap community:

• LS7 + 4L60E = FAIL: The LS7's crank flange depth requires a specific torque converter spacing. A 4L60E will bolt up but the converter won't seat properly — it'll take out the pump within 50 miles.
• G-Body oil pan clearance: Stock truck pans hang 2 inches below the crossmember. Only Holley 302-1/302-2, Moroso 20140, or factory F-Body pans clear the G-Body steering linkage and crossmember.
• 58x reluctor + Gen III ECU = no start: Gen III engines use a 24-tooth reluctor wheel. Gen IV uses 58-tooth. The ECU must match the reluctor count. Mismatch it and the crank position sensor can't sync — no spark, no fuel.
• DBW pedal mismatch: Drive-by-wire engines need a matching TAC module and pedal assembly. Mixing Gen III and Gen IV DBW components gives you a dead pedal.

The API exposes a /api/validate?vehicle=X&engine=X&trans=X endpoint that runs all 14 rules against a proposed combination and returns a pass/fail with specific reasons for each failure. No more finding out your oil pan doesn't clear after you've already dropped the engine in.

Why Build This?

I own a 1988 Pontiac Firebird SE Base — a V6 car with a 2.8L LB8 and a 700R4 transmission. It's the perfect LS swap candidate: the third-gen F-Body engine bay swallows an LS like it was designed for it, the aftermarket support is massive, and the weight distribution actually improves with an aluminum-block LS compared to the cast-iron V6.

Planning the swap meant spending weeks bouncing between LS1Tech build threads, Holley's catalog, ICT Billet's website, and eight different Facebook groups — all while trying to keep a running parts list in a spreadsheet. Every answer spawned two more questions. "OK, I need Hooker 12611HKR mounts. But wait — do those work with the stock K-member, or do I need the tubular one? And if I use the tubular K-member, does my stock steering rack still bolt up?"

The LS Swap Tool automates that entire research process. It's a database that encodes the tribal knowledge, a query engine that validates combinations, and a UI that makes it usable. It's the tool I wish existed when I started planning my own swap.

Architecture Decisions Worth Mentioning

Static SPA on GitHub Pages, API on Kubernetes

The frontend is a pure static build — React + Vite produces an index.html with hashed JS/CSS bundles. GitHub Pages serves it from a CDN with zero server cost and infinite scale. The API runs on my Kubernetes cluster behind an ingress controller, so the SPA calls api.solidrust.net for data. This split architecture means the frontend stays fast and cheap while the backend can be scaled independently.

PostgreSQL, Not MongoDB

Engine swap compatibility is inherently relational — engines have many transmissions, vehicles have many compatible engines, components belong to categories and manufacturers. A document store would force denormalization and make cross-referencing painful. PostgreSQL's foreign keys, join tables, and tsvector full-text search map directly to the domain model.

Valkey as a Read Cache

Engine specs and vehicle lists change rarely but get queried constantly. Valkey (a Redis-compatible fork) caches these queries with a TTL that invalidates on any data change. The cache hit rate on the vehicle browser is north of 95% — most page loads never touch the database.

GitOps from Day One

Every change — SQL migrations, API code, frontend builds — flows through Gitea Actions into the Kubernetes cluster via FluxCD and Kustomize. There's no SSH, no manual kubectl apply, no cowboy deploys. The entire pipeline is declarative and reproducible.

What's Next

The tool is at v0.3.1 with 62 tests (30 frontend, 32 API). The roadmap includes:

• User accounts: Save your swap plans, track parts purchases, share builds
• More vehicles: C5/C6 Corvette, GMT800 trucks, S10/S15, Jeep XJ, Toyota Supra, Porsche 944
• Gen V LT engines: LT1, LT4, LT5 support with direct injection considerations
• Vendor price scraping: Live pricing from Summit, Jegs, Holley, ICT Billet
• Wiring diagram generator: Auto-generate ECU pinout maps for your specific engine-harness-vehicle combination
• Community builds: Let users submit their completed swaps with photos and notes

Try It Yourself

The tool is live and free at lsswap.solidrust.net. No signup, no ads, no tracking — just a dark-themed SPA that answers the question "what fits?"

If you're planning a swap — or just curious about what an LS3 looks like in an RX-7 FD — fire up the Swap Planner, pick your poison, and get a complete parts list with validated compatibility. It beats scrolling through page 47 of a 2008 forum thread.

The source code is open at github.com/SolidRusT/srt-engine-swaps. PRs welcome, especially if you've got data on a platform that's not in the database yet.