Non-Tech Speak: The Art of Explaining Simply

"I couldn't explain it to the freshmen. That means we don't really understand it." — Richard Feynman

Inspiration: The Feynman Spirit

This project was born out of a common frustration in the software world: the disconnect between Builders and Users. We spend hours debugging race conditions and optimizing SQL queries, but when a partner or a parent asks, "So, what did you do today?", we freeze.

How do you explain a "Docker Container" without sounding like a manual?

I drew inspiration from Richard Feynman, the Nobel prize-winning physicist known as "The Great Explainer." Feynman had a unique ability to strip away the jargon and reveal the core intuition of a concept using simple, physical analogies. He believed that complexity is often a mask for a lack of deep understanding.

Non-Tech Speak is built on this philosophy. It's not just a translator; it's a tool to practice empathy. It forces us to ask: How would I explain this to a 5-year-old? To my grandmother? To a busy CEO?

What It Does

Non-Tech Speak uses advanced AI to transform technical jargon into relatable narratives. It doesn't just "dumb it down"; it uses context-aware analogies.

If input is: $$ \text{Kubernetes orchestrates containerized applications.} $$

The output for a 5-year-old might be:

"Imagine you have a big toy box (the server) and lots of little robot toys (applications). Kubernetes is like the mom who makes sure every robot is playing nicely, has enough batteries, and cleans them up if they break!"

How I Built It

I chose a stack that prioritizes speed, type safety, and modern developer experience.

The Tech Stack

Runtime: Bun — for its incredible speed and built-in tooling.
Frontend: Next.js 16 (App Router) — ensuring a reactive, server-first UI.
Backend: ElysiaJS — A high-performance typescript framework that pairs perfectly with Bun.
Database: Neon (PostgreSQL) managed via Drizzle ORM.
AI Engine: Google Gemini 2.0 Flash via the Tanstack AI SDK (@tanstack/ai).
Auth: Better Auth — robust, type-safe authentication.
UI/UX: Shadcn UI + Tailwind CSS, structured with Atomic Design principles.

Architecture Highlights

The app is built as a Monorepo-style hybrid. Next.js handles the frontend, while requests are proxied to an internal Elysia server. This gives us the SEO benefits of Next.js with the raw API performance of Elysia.

Technical complexity is hidden behind a clean, "Apple-esque" interface. As Feynman would want, the complexity is there, but the experience is simple.

Challenges Faced

1. The "Stuttering" Stream

One of the trickiest bugs was what I call the "ImagineImagine" effect. When streaming the AI response, the chunks arrived in an ambiguous format. Some providers send the delta (just the new word), while others send the accumulated text (everything so far).

My initial implementation naively appended everything: $$ \text{Text}_{final} = \sum \text{Chunk}_n $$

This caused the text to repeat wildly. I had to implement a heuristic robust stream handler in the backend that intelligently detects if a chunk is a delta or a replacement:

if (simplifiedText && content.startsWith(simplifiedText)) {
  simplifiedText = content; // It was an accumulation!
} else {
  simplifiedText += content; // It was a delta!
}

2. Prompt Engineering as Code

Getting the AI to sound "human" and not "assistive" was hard. I used a "Tool Role" prompting strategy with strict rules to prevent the AI from adding fluff like "Sure, here is your explanation."

3. State Management

Tracking the "Public" vs "Private" state of a translation, along with its live view counts and upvotes, required careful optimistic UI updates to ensure the app felt snappy even on slower connections.

What I Learned

Building Non-Tech Speak reinforced Feynman's lesson: Constraint breeds creativity. By constraining the AI to specific personas (like a "Frustrated Boss" or a "Curious Child"), the explanations became significantly more valuable than generic summaries.

Technically, I learned that the bleeding edge (Bun + Elysia + Next.js 16) is sharp but powerful. The speed of iteration was unmatched, allowing me to focus on the soul of the project rather than boilerplate.

Ultimately, this project is a reminder that technology is meaningless if we can't share it with the people around us.

"The first principle is that you must not fool yourself and you are the easiest person to fool." — Richard Feynman