TypeScript + Python: one engineer, two ecosystems, one contract

More and more products I work on have two halves. One is what people touch - a Next.js interface, a Node.js API, auth, payments. The other is model work - inference, embeddings, audio, data processing. The first half speaks TypeScript, the second speaks Python. Being fluent in both is not about collecting languages; it is about owning the seam between them, which is exactly where most AI products break.

The good news is that the two ecosystems mirror each other more than people think. Zod has Pydantic. tsc has mypy and pyright. ESLint and Prettier have Ruff. npm and pnpm have uv and Poetry. Express and NestJS have FastAPI, which even generates OpenAPI from typed models out of the box. I bring the same discipline to both sides: strict types, a formatter nobody argues with, pinned dependencies, and tests in CI.

The contract between them is the most important file in the system. I define it once and generate the rest: Pydantic models in FastAPI produce an OpenAPI schema, and the TypeScript client and types are generated from it. Rename a field in Python, and the Next.js build fails before a user ever sees undefined. For async work the contract is a job payload with a schema on both ends, not a free-form JSON blob each side interprets its own way.

The split of responsibilities stays strict. TypeScript owns identity, permissions, money, and the UI. Python owns the model and nothing else: it receives a job, does the heavy work - a StyleTTS2 voice, an embedding batch, a document parse - and returns a result. The Python service never talks to the browser and never decides who is allowed to do what. Fast calls go over HTTP, slow ones through a queue, with timeouts, retries, and idempotency on both sides.

The differences matter too, and respecting them is part of the job. Python is where you prototype in a notebook, but notebooks are not production - working code moves into a module with tests. Python concurrency is not Node’s event loop: CPU-heavy inference belongs in worker processes or a GPU service, not in an async request handler. And the deployment units differ - a lean Node image versus a Python image with CUDA and model weights - so they scale, cache, and cost differently.

For a client, the value of one engineer across both sides is simple: no translation layer between “the AI person” and “the web person,” and no API each side blames on the other. If your product has a model that works in a notebook and a web app that does not know how to use it yet, send me both. I will reply with the contract I would put between them and the first version I would ship.