DEV Community: Hamza Amir

How LLMs Actually Work

Hamza Amir — Thu, 30 Jul 2026 11:20:07 +0000

Every large language model you use today, GPT, Claude, Gemini, Llama, is built on one core invention: the Transformer. It came from a 2017 Google paper called Attention Is All You Need. Before that paper, models read text one word at a time, in order, using recurrent networks (RNNs and LSTMs). That was slow and made it hard to connect words that were far apart in a sentence.

The Transformer removed recurrence entirely and replaced it with attention, a mechanism that lets every word look at every other word at the same time. That single change is why modern LLMs can be trained on massive datasets in parallel and why they handle long, complex text so well.

This article walks through the full pipeline, from raw text to predicted output, in the order data actually flows through a model.

The Big Picture

Before the details, here is the full journey a sentence takes through an LLM:

Tokenization – break text into small chunks (tokens)
Vector Embedding – turn each token into a list of numbers
Positional Encoding – add information about word order
Self-Attention – let each token look at other tokens for context
Multi-Head Attention – run several attention patterns in parallel
Feed-Forward Network – process each token's information further
Add & Norm (residual connections) – stabilize and preserve information
Stack layers (Encoder / Decoder) – repeat the above N times for depth
Linear + Softmax – convert the final vectors into word probabilities
Sampling / Generation – pick the next word and repeat

Everything below explains each of these steps in detail.

1. Tokenization: Turning Text Into Pieces

A model cannot read raw text. It needs numbers. The first step is to split a sentence into tokens, which are usually not full words. Modern LLMs use subword tokenization methods such as Byte-Pair Encoding (BPE) or WordPiece.

Example:

Input text:  "unbelievable results"
Tokens:      ["un", "believ", "able", " results"]
Token IDs:   [4521, 8832, 219, 991]

Why subwords instead of whole words? Two reasons:

Vocabulary size stays manageable. A model does not need a separate entry for every possible word, including rare ones, typos, or made-up words. It can build them from smaller pieces.
Unknown words are never a dead end. Even a word the model has never seen can be broken into familiar subword pieces.

The original Transformer paper used Byte-Pair Encoding with a vocabulary of around 37,000 tokens for English-German translation, and word-piece encoding with a 32,000-token vocabulary for English-French. Today's LLMs use similar ideas but with larger vocabularies, often 50,000 to 100,000+ tokens.

Once tokenized, each token is mapped to a unique integer ID using a lookup vocabulary. That ID is what enters the model.

2. Vector Embeddings: Giving Tokens Meaning

A token ID like 4521 is just a label. It carries no meaning by itself. The next step converts each token ID into a vector embedding, a list of numbers (commonly 512, 768, 4096, or more dimensions depending on model size) that captures the token's meaning in a mathematical space.

This mapping is learned during training. Tokens with similar meanings end up with similar vectors. That is why, in embedding space, the vector for "king" minus "man" plus "woman" lands close to the vector for "queen." The model is not memorizing definitions, it is learning relationships from patterns in massive amounts of text.

In the original Transformer, the embedding dimension was called d_model and set to 512 for the base model. The same weight matrix was shared between the input embedding layer, the output embedding layer, and the final linear layer before the output probabilities. This means the model has one consistent way to translate between tokens and vectors, coming and going.

3. Positional Encoding: Restoring Word Order

Here is a subtle problem. Self-attention (explained next) looks at all tokens simultaneously, with no built-in sense of order. But word order clearly matters: "the dog bit the man" and "the man bit the dog" use identical words in a different order with a completely different meaning.

To fix this, the Transformer adds a positional encoding vector to each token's embedding before it enters the network. This encoding is built from sine and cosine waves of different frequencies:

PE(position, 2i)   = sin(position / 10000^(2i / d_model))
PE(position, 2i+1) = cos(position / 10000^(2i / d_model))

Each dimension of the encoding corresponds to a wave of a different frequency, so every position in the sequence gets a unique signature. The authors chose sine and cosine waves specifically because they let the model learn to attend to relative positions easily, and because the pattern can, in theory, generalize to sequence lengths longer than anything seen in training.

Some newer models use learned positional embeddings instead of fixed sine/cosine ones. The original paper tested both and found they performed almost identically.

At this point, each token is represented by: embedding vector + positional encoding. This combined vector is what flows into the attention layers.

4. Self-Attention: The Core Idea

This is the heart of the Transformer. Self-attention lets every token in a sequence look at every other token and decide how much to "pay attention" to it when building its own updated representation.

Query, Key, Value (Q, K, V)

Every token produces three vectors, all learned through separate weight matrices:

Query (Q): what this token is looking for
Key (K): what this token offers, as a label others can search against
Value (V): the actual content this token contributes if selected

A simple way to picture it: think of a search engine. Your search term is the Query. Every document in the index has a Key (title, tags, description). The engine compares your Query against all Keys to find matches, then returns the Values (the actual documents) weighted by how well they matched.

Scaled Dot-Product Attention

The formula from the paper is:

Attention(Q, K, V) = softmax( (Q · K^T) / sqrt(d_k) ) · V

Step by step:

Take the dot product of the Query with every Key. This produces a raw compatibility score between the current token and every other token.
Divide by the square root of the key dimension (d_k). This scaling step keeps the numbers from growing too large, which would otherwise push the softmax function into regions with extremely small gradients and slow down learning.
Apply softmax to turn the scores into a probability distribution that sums to 1. These are the attention weights.
Multiply those weights by the Value vectors and sum them up. The result is a new vector for this token that blends in information from every other token, weighted by relevance.

Every word ends up with a new representation that reflects its context, not just its isolated meaning. This is how a model figures out that "bank" means something different in "river bank" versus "savings bank," purely from what surrounds it.

Masked Self-Attention

When a model generates text, it should not be able to "cheat" by looking at future words it hasn't produced yet. To prevent this, the decoder uses masked self-attention: positions are only allowed to attend to earlier positions, not later ones. This is done by setting the attention score for any future position to negative infinity before the softmax step, which makes its weight effectively zero. Combined with shifting the output sequence by one position, this guarantees that a prediction for a given position depends only on the known outputs before it. This is what makes the model autoregressive, generating one token at a time based only on what came before.

5. Multi-Head Attention: Many Perspectives at Once

A single attention calculation only captures one type of relationship at a time. Multi-head attention runs several attention operations in parallel, each with its own learned Q, K, and V projection matrices, so the model can capture different kinds of relationships simultaneously: one head might track grammatical structure, another might track long-distance references, another might track sentiment.

MultiHead(Q, K, V) = Concat(head_1, ..., head_h) · W_O
where head_i = Attention(Q·W_i^Q, K·W_i^K, V·W_i^V)

The original Transformer used 8 attention heads (h = 8), each working on a 64-dimensional slice (d_k = d_v = 64), so the total dimensionality across all heads matched the model's overall size of 512. The outputs of all heads are concatenated and passed through one more linear projection to produce the final result.

The paper found this mattered a lot: using just a single attention head performed noticeably worse, since averaging inhibits the model's ability to represent different types of relationships. But too many heads also hurt quality, since each head then works with too little dimensional space to be useful.

The Transformer uses multi-head attention in three distinct places:

Encoder self-attention: every input token attends to every other input token
Masked decoder self-attention: every output token attends only to earlier output tokens
Encoder-decoder (cross) attention: each decoder token attends to the full encoder output, letting the decoder pull relevant information from the input sequence while generating

6. Feed-Forward Network

After attention, each token's vector passes through a small, fully connected feed-forward network, applied identically and independently to each position:

FFN(x) = max(0, x·W1 + b1)·W2 + b2

This is two linear layers with a ReLU activation in between. In the base Transformer, the input and output are 512-dimensional, but the hidden layer in between expands to 2048 dimensions before compressing back down. This gives the model extra capacity to process and transform the information that attention just gathered, on a per-token basis. Attention handles mixing information between tokens; the feed-forward layer handles processing information within each token.

7. Add & Norm: Residual Connections and Layer Normalization

Around both the attention sub-layer and the feed-forward sub-layer, the Transformer applies a residual connection: the input to the sub-layer is added back to its output, followed by layer normalization.

Output = LayerNorm(x + Sublayer(x))

This matters for two practical reasons. First, residual connections let gradients flow more easily through deep networks during training, which prevents the vanishing gradient problems that plagued earlier deep architectures. Second, layer normalization keeps the scale of values consistent as data passes through many stacked layers, which stabilizes training.

8. Stacking It All: Encoder and Decoder

A single attention + feed-forward block is called a layer. The Transformer stacks several identical layers on top of each other, N = 6 in the original paper, to build depth. Each layer refines the representation a little further.

Encoder

The encoder's job is to build a rich understanding of the input sequence. Each encoder layer has two sub-layers:

Multi-head self-attention (every input token looks at every other input token)
Position-wise feed-forward network

Decoder

The decoder's job is to generate the output sequence, one token at a time, using both what it has generated so far and the encoder's understanding of the input. Each decoder layer has three sub-layers:

Masked multi-head self-attention (only looks at earlier output tokens)
Encoder-decoder cross-attention (looks at the encoder's output)
Position-wise feed-forward network

This encoder-decoder structure is what the original paper used for machine translation. Most modern LLMs (GPT-style models) are decoder-only: they drop the separate encoder and just stack masked self-attention decoder blocks, since their job is pure text generation rather than translating between two sequences. Models like BERT are encoder-only, built for understanding text rather than generating it.

9. Linear + Softmax: From Vectors to Word Probabilities

After the final decoder layer, the model has a vector for the next token position. This vector is passed through:

A linear layer that projects it into a score for every single word in the vocabulary (tens of thousands of numbers, one per possible token)
A softmax function that converts those raw scores into probabilities that sum to 1

The result is a full probability distribution over the entire vocabulary: how likely each possible next token is, given everything the model has seen so far.

10. Generation: How the Model Actually Writes Text

At inference time (when you chat with an LLM), the process becomes a loop:

The model looks at all tokens so far and predicts a probability distribution for the next token.
A token is picked from that distribution. This can be the single most likely token (greedy decoding) or a token sampled according to the probabilities with some randomness (which is why the same prompt can give different answers, controlled by a setting often called "temperature").
That chosen token is appended to the sequence.
The whole sequence, now one token longer, is fed back into the model to predict the next token.
This repeats until the model produces a stop signal or hits a length limit.

This is why LLMs generate text one piece at a time and why longer responses take proportionally longer to produce: each new token requires another full pass through the model.

Why This Architecture Won

The Transformer paper measured three things that mattered for training large models efficiently:

Computational complexity per layer: self-attention connects any two positions in a constant number of operations, while recurrent networks need a number of sequential steps proportional to sequence length.
Parallelization: because self-attention has no step-by-step dependency like an RNN does, all tokens can be processed simultaneously on modern hardware like GPUs, drastically speeding up training.
Path length between distant words: in a recurrent network, information from word 1 has to pass through every word in between to reach word 100. In self-attention, any two words are directly connected in a single step, which makes it far easier to learn long-range relationships.

On real benchmarks, the Transformer did not just match previous state-of-the-art translation models, it beat them while training dramatically faster. The big Transformer model reached a BLEU score of 28.4 on English-to-German translation and 41.8 on English-to-French, both new records at the time, while training in a few days on 8 GPUs rather than weeks.

Full Cheat Sheet Table

Stage	What It Does	Key Detail
Tokenization	Splits text into subword units	Uses BPE / WordPiece, ~32K-100K+ vocabulary
Embedding	Converts tokens into meaning-carrying vectors	Learned during training, similar meanings cluster together
Positional Encoding	Injects word order information	Sine/cosine waves of varying frequency added to embeddings
Self-Attention	Lets each token gather context from others	Uses Query, Key, Value vectors and scaled dot products
Masking	Prevents seeing future tokens during generation	Sets future attention scores to negative infinity
Multi-Head Attention	Captures multiple relationship types at once	8 heads in the original paper, each 64-dimensional
Feed-Forward Network	Processes each token's info independently	Two linear layers with ReLU, expands then compresses
Add & Norm	Stabilizes deep stacks of layers	Residual connection + layer normalization
Encoder	Builds understanding of the input	Self-attention + feed-forward, repeated N=6 times
Decoder	Generates output tokens one at a time	Masked self-attention + cross-attention + feed-forward
Linear + Softmax	Turns final vector into word probabilities	Produces a distribution over the whole vocabulary
Sampling	Picks the actual next word	Greedy or probability-based sampling, then loops

The Transformer Architecture Diagram

Below is the original architecture diagram from Attention Is All You Need, showing the encoder (left stack) and decoder (right stack) side by side, with inputs flowing up from the bottom and output probabilities produced at the top.

Reading it bottom to top: input tokens are embedded and combined with positional encoding, pass through N stacked encoder layers (masked multi-head attention, add & norm, feed-forward, add & norm), while the decoder stack does the same on the output side but adds a middle layer of cross-attention over the encoder's output. The final decoder output goes through a linear layer and softmax to produce output probabilities.

Source Material

This article summarizes concepts from:

Paper: Attention Is All You Need – Vaswani et al., Google Brain / Google Research, 2017. The original paper that introduced the Transformer architecture, tested on English-to-German and English-to-French machine translation.
Video: Transformer walkthrough – a visual explanation of the same architecture, useful for seeing the matrix operations and data flow described above in action.

Quick Recap in One Paragraph

Text gets broken into tokens, each token becomes a vector, and position information gets added so the model knows word order. Self-attention lets every token gather context from every other token using Query, Key, and Value vectors, and multi-head attention runs several of these attention patterns in parallel to capture different relationships. Feed-forward layers then process each token's information further, with residual connections and normalization keeping training stable across many stacked layers. Finally, a linear layer plus softmax turns the model's internal representation into a probability distribution over the vocabulary, and the model samples one token at a time, feeding its own output back in, to generate text. That loop, repeated one token at a time, is what "the LLM is typing" actually looks like under the hood.

AI Fluency: The Career Skill That Separates Operators from the Obsolete

Hamza Amir — Fri, 26 Jun 2026 15:16:39 +0000

By Hamza Amir | June 2026

Introduction: Two Professionals, One Tool, Very Different Results

Two marketing managers sit down with the same AI tool on the same Monday morning.

The first types: "Write me a product launch email." She gets a passable draft, skims it, pastes it into Outlook, and moves on. She tells her colleagues AI is "pretty useful sometimes."

The second types something longer. He specifies a persona, a target audience, a tone constraint, a strategic goal, and a desired call-to-action structure. He reviews the output not as a finished product but as a first draft from a smart collaborator who needs direction. He iterates twice. The final email drives a 34% open rate.

Same tool. Wildly different outcomes.

That gap has a name: AI fluency. And it is not the same thing as AI literacy.

AI literacy means you know what large language models are, that ChatGPT exists, that "prompt engineering" is a phrase people use. It is awareness. It is the equivalent of knowing that spreadsheets exist.

AI fluency is different. It is the ability to work with AI as a creative and analytical partner: to understand how it reasons, where it fails, how to structure your requests for precision, and how to apply judgment to everything it produces. It is the difference between someone who knows Excel exists and someone who can build a financial model from scratch.

The professionals who build this skill are not just getting more done. They are producing qualitatively different work. Those who do not build it are not standing still; they are falling behind people who are moving faster every quarter.

This article is not a survey of AI tools. It is a practical framework for developing the fluency that actually changes your output.

Section 1: The Probabilistic Mindset — Thinking Like AI Thinks

Before you can work well with an AI system, you need to understand what it actually is. Not at a research-paper level. At a practical intuition level.

What an LLM Actually Does (Without the Jargon)

Here is a useful mental model: imagine every book, article, forum thread, and document ever written has been turned into an enormous weather map of language patterns. When you type a sentence to an AI, it does not search that map for the right answer. It forecasts the most statistically probable continuation of your sentence given everything it has seen. It is not retrieving a fact the way a database retrieves a record. It is doing something closer to highly sophisticated pattern completion.

This has a direct consequence: AI is not an oracle. It is a probability engine.

When it gives you a confident-sounding response, that confidence is not a signal that the information is correct. It is a signal that the response pattern is common and coherent. Those are two very different things.

A calculator gives you a wrong answer only if you give it wrong inputs. An LLM can give you a wrong answer even with perfect inputs, because "wrong" is not part of its objective function. It optimizes for coherence, not truth.

Why the Calculator Analogy Fails You

Most professionals who underuse AI are treating it like a calculator: input goes in, output comes out, task is done. This leads to three predictable failure modes:

The acceptance trap: They take the first output at face value and stop.
The single-shot mistake: They write one vague prompt and, when the result is generic, conclude that "AI doesn't work for this."
The passivity problem: They forget that the output is a starting point, not a solution.

Professionals who overperform with AI treat it differently. They treat it like a brilliant but imperfect colleague who needs context, direction, and regular feedback. They iterate. They interrogate the output. They push back when something feels off.

The Fluency Shift in Practice

Thinking like a calculator user: "I asked it to write my report and the draft was mediocre."

Thinking like a fluent collaborator: "My first prompt was too vague. Let me rebuild it with clearer constraints, give it my existing outline, and ask it to match the register of the executive summary I already wrote."

The second person is not smarter. They just have a more accurate mental model of what they are working with.

Section 2: Conversational Mastery and Structured Prompting

If AI fluency has a single highest-leverage skill, it is this: the ability to construct precise, structured prompts that constrain the model toward your actual goal.

Vague prompts produce generic outputs. Not because the AI is lazy, but because vague prompts leave enormous probabilistic space, and the model fills that space with statistically average content.

Structured prompts collapse that space. They force the model toward your specific context, audience, and intent.

The RCCOS Framework

One practical framework for professional prompts covers five dimensions:

Dimension	What it does	Example
R — Role	Defines the persona the AI should operate from	"Act as a senior product manager reviewing a go-to-market plan."
C — Context	Provides the background the AI needs to reason accurately	"The product is a B2B SaaS tool for logistics companies. Our primary competitor is [X]."
C — Constraints	Sets the guardrails: tone, length, format, what to avoid	"Write in plain language. No jargon. Under 300 words. Avoid bullet points."
O — Objective	States exactly what the output should accomplish	"The goal is to convince a skeptical CFO to approve a pilot budget."
S — Style/Structure	Defines how the output should be organized	"Structure it as: opening hook, three supporting points, one clear ask."

Not every prompt needs all five layers. A casual brainstorm prompt can stay light. A high-stakes deliverable warrants the full framework.

Before and After: The Same Request, Two Very Different Results

The difference between a weak and a structured prompt is not about using more words. It is about using the right words.

WEAK PROMPT:

Write a LinkedIn post about our new product launch.

What this produces: A generic, enthusiasm-heavy paragraph with no specific audience, no differentiated value proposition, and a call-to-action that could apply to any product on earth.

STRUCTURED PROMPT (RCCOS applied):

Role: You are a B2B content strategist who writes for senior operations leaders.

Context: We are launching a supply chain visibility platform called TrackFlow. 
It integrates with existing ERP systems and cuts average inventory reconciliation 
time by 40%. Our audience is VP-level operations and logistics decision-makers 
at mid-sized manufacturing companies.

Constraints: 
- Write in a direct, peer-to-peer tone. Not promotional. Not hype-driven.
- Max 200 words.
- No exclamation marks.
- Avoid buzzwords like "game-changing," "innovative," or "cutting-edge."
- Do not open with "Excited to announce."

Objective: The post should make a VP of Operations think: 
"This sounds like it solves a problem I actually have."

Output structure:
1. Open with a specific, relatable pain point (1–2 sentences).
2. Introduce the product as a solution, not a feature list (2–3 sentences).
3. Include the 40% stat naturally in context.
4. Close with a single, low-friction call to action.

The structured version takes 90 seconds longer to write. It produces output that would take 30 minutes to write manually. That is the trade-off that fluent professionals understand.

Iteration Is Not a Sign of Failure

One subtle mindset block worth naming: many professionals feel that needing to revise an AI output means the tool "didn't work." This is backwards. Revision is the workflow. The first output is raw material. The second and third prompts refine it.

A fluent AI user builds a dialogue, not a transaction.

Section 3: The Critical Guardrails — Privacy, IP, and the Hallucination Problem

AI fluency is not only about getting more out of the tools. It is equally about knowing where the tools will hurt you if you are not paying attention.

Three guardrails matter more than any others.

Guardrail 1: Data Privacy and What You Should Never Type

Every time you paste content into a public AI interface, you are making a decision about data exposure. For most consumer-facing AI tools, inputs are used in various ways depending on the platform, the settings, and the terms of service at the time you use it.

Practical rule: Treat a public AI chat window like a semipublic email thread. Anything you would not want leaving your organization, do not paste in.

This includes:

Unreleased financial data or earnings figures
Client-identifying information or personal data covered by privacy regulations (GDPR, HIPAA, etc.)
Internal strategic plans, M&A discussions, or product roadmaps
Proprietary code that constitutes competitive advantage

Most enterprise AI deployments offer privacy controls and zero-data-retention settings. Know what your organization's approved tools are and use those for sensitive work. Using an unapproved tool for a shortcut is not a productivity win; it is a liability.

Guardrail 2: Intellectual Property and the Ownership Question

AI-generated content sits in a genuinely unsettled legal space as of 2026. Different jurisdictions treat AI-assisted work differently, and the rules are still evolving. What this means practically:

Work produced with AI assistance may have ambiguous copyright status. Be transparent with your organization about how you are using AI in deliverables.
If the AI reproduces a substantial amount of text that closely mirrors a training source, you could be looking at IP risk. For high-stakes external documents (contracts, published content, regulated communications), run a plagiarism check on AI-generated drafts.
Do not use AI to reproduce or closely paraphrase copyrighted frameworks, methodologies, or branded materials without checking first.

The honest answer is that most internal use cases carry low risk. But external deliverables, published content, and anything legal or regulatory in nature warrant an extra review step.

Guardrail 3: Hallucinations — How They Work and How to Catch Them

"Hallucination" is the term used when an AI produces information that is fluent, formatted, and completely wrong. It might cite a study that does not exist, give you a statistic that is plausible but fabricated, or produce a quote attributed to someone who never said it.

This happens because of the probabilistic nature described in Section 1. The model is not lying. It does not have a concept of lying. It is producing the most statistically coherent continuation of your prompt, and sometimes "most coherent" diverges from "factually accurate."

High-risk areas for hallucinations:

Specific statistics, percentages, or numerical claims
Citations, academic papers, and named studies
Legal specifics: case names, statute numbers, jurisdiction-specific rules
Historical dates and biographical details about non-famous figures
Recent events (models have knowledge cutoffs and can fill gaps with plausible-sounding fabrications)

A practical validation protocol for high-stakes outputs:

Flag every factual claim. Read the output and mark every specific number, name, citation, or assertion with a check symbol.
Verify the checkmarks. Search each claim against a primary source. Do not use another AI tool to verify; that compounds the risk.
For citations, confirm the source exists first. Search the exact title, author, and publication. If you cannot find it, it may not exist.
Apply domain knowledge. If something feels slightly off, it probably is. Trust your expertise over AI confidence.
For regulated outputs, involve a human expert. Medical, legal, financial, and compliance content needs professional review before it goes anywhere.

The professionals who get burned by AI hallucinations are almost always the ones who did not read the output critically because it sounded authoritative. Fluency includes knowing when to slow down.

Conclusion: The 30-Day AI Fluency Blueprint

AI fluency is not a credential. It is not a course you finish. It is a working habit built in increments, refined through practice, and measured by the quality of what you produce.

The professionals who will look back on this period and say they used it well are the ones who built the habit now, while the majority is still deciding whether AI is "worth the hype."

Here is a practical framework for the next 30 days.

Your 30-Day AI Fluency Blueprint

Week 1: Build the Mental Model

Read enough about how LLMs work to genuinely internalize the probabilistic framing from Section 1. You do not need a technical background. You need the right intuition.
Pick one AI tool and commit to it for the month. Do not tool-hop.
List five tasks in your current role that are repetitive, language-heavy, or require structured reasoning. These are your practice targets.

Week 2: Master the Structured Prompt

Apply the RCCOS framework to every significant prompt this week. Yes, every one.
Save your best-performing prompts in a personal prompt library (a simple document works fine). You will reuse and refine these over time.
Run the "before and after" exercise from Section 2 on one real work deliverable. Compare the outputs honestly.

Week 3: Build Your Verification Habit

For any AI output you plan to use externally or in a decision-making context, apply the five-step validation protocol from Section 3.
Deliberately test the model's limits this week. Ask it questions you know the answer to. See where it gets things wrong. That calibration exercise is more valuable than any tutorial.
Identify which tasks in your workflow carry hallucination risk and build a standing verification step into your process for those.

Week 4: Integrate and Systematize

Document two or three AI-assisted workflows that genuinely saved you time or improved your output quality this month. Be specific about what changed.
Share one insight or technique with a colleague. Teaching accelerates your own understanding.
Identify one area where you tried AI and it did not help. Ask yourself whether the problem was the tool, the prompt, or the task type. That reflection is where fluency gets built.

One final thought: the professionals who will be most valuable in three years are not the ones who used AI the most. They are the ones who combined AI's throughput with their own judgment, context, and accountability.

The tools do not replace those things. They amplify them. The ceiling on that amplification is how fluent you choose to become.

Hamza.dev
🌐 www.hamzaamir.me
© 2026. All rights reserved.

Selecting Your Frontend Foundation: React vs. Next.js

Hamza Amir — Tue, 16 Jun 2026 08:52:55 +0000

React and Next.js solve different problems. React gives you a library for building user interfaces. Next.js gives you a full framework built on top of React, with routing, rendering, and optimization included from the start.

This article breaks down the strengths and weaknesses of each option, so you make the right choice for your project.

What React Gives You

React, built by Meta, focuses on one job: rendering components based on state and props. Developers pick React for these strengths:

Component-based structure. You build small, reusable pieces and combine them into full interfaces.
A large ecosystem. Thousands of libraries support React, from state managers to UI kits.
Flexibility. You choose your own router, bundler, and styling approach.
A strong job market. Companies across every industry hire React developers.
React 19 added the React Compiler, which optimizes re-renders automatically, along with Actions for handling async operations.

Where React Falls Short

React stops at the component layer. You handle everything else yourself:

No built-in routing. You add React Router or a similar library to manage pages.
No server rendering by default. Without extra setup, your page ships an empty HTML shell, and content fills in after JavaScript loads.
Slower initial load on content-heavy pages, since users wait for JavaScript before seeing meaningful content.
Weak default SEO. Search engine crawlers struggle to read content rendered only on the client.
Manual configuration for bundling, image optimization, and code splitting.

What Next.js Adds

Next.js, built by Vercel, takes React and wraps production features around it:

File-based routing. Drop a file into the pages or app folder, and the route exists. You need no separate router library.
Server-side rendering. The server builds full HTML for each request, so users see content the moment the page loads.
Static site generation. Pages build once at deploy time and serve from a CDN, with load times under 100 milliseconds for many sites.
Incremental static regeneration. Pages stay static but refresh in the background on a schedule you set, so content stays current without a full rebuild.
Built-in API routes. Write backend logic in the same project, without a separate server.
Automatic image optimization. The Image component resizes images and serves modern formats without manual work.
React Server Components through the App Router. Components render on the server by default, cutting the JavaScript sent to the browser.
Server Actions. Forms submit directly to server functions, removing the need for separate API endpoints.
Wide adoption in production. Platforms like TikTok, Twitch, and Hulu run Next.js at scale.

Where Next.js Falls Short

Next.js brings structure, and structure comes with tradeoffs:

A steeper learning curve. New concepts like Server Components, caching layers, and the App Router take time to learn.
Hosting requirements. Server-side rendering needs a Node server or serverless functions, not a plain static host.
Opinionated conventions. You follow the file structure and rendering rules Next.js sets, with less room for a fully custom setup.
Weaker fit for highly interactive apps. Real-time tools like chat apps or multiplayer games gain little from server rendering and add unneeded complexity.
Migration cost. Moving an existing React app to Next.js takes planning and rewritten routing logic.

Quick Comparison

Factor	React	Next.js
Rendering	Client-side by default	Server-side, static, or hybrid
Routing	Requires a separate library	Built-in, file-based
SEO	Needs extra setup	Strong out of the box
Backend logic	Separate server required	API routes included
Image handling	Manual	Automatic optimization
Learning curve	Lower	Higher
Hosting	Any static host	Node server or serverless platform

When React Fits Best

Pick plain React when your project sits behind a login and search engines never see the page:

Admin dashboards and internal tools
Authenticated SaaS products where SEO carries no weight
Embedded widgets and small components added to existing sites
Projects needing full control over the build pipeline

When Next.js Fits Best

Pick Next.js when speed, search visibility, and full-stack structure matter:

Marketing sites, blogs, and documentation hubs that depend on search traffic
E-commerce product pages, where load speed affects conversion
Content platforms publishing many pages that benefit from static generation
Projects needing both frontend and backend code in one codebase

Your Decision

Your project requirements decide the answer, not trends. If your page needs to load fast for an anonymous visitor and rank on search engines, Next.js gives you the tools without added setup. If your app sits behind a login screen and serves logged-in users only, plain React with a bundler like Vite keeps things simple.

Most teams starting a new public-facing project in 2026 reach for Next.js first, then move to plain React only when a specific reason supports the switch.

My Open Source Journey with VoiceyBill

Hamza Amir — Sun, 07 Jun 2026 03:53:38 +0000

By Hamza Amir · June 2026

The Problem Nobody Talks About

There is a moment every developer knows — staring at a GitHub repository thinking, "I wish I could contribute to this," then quietly closing the tab. I did that for months. Then I stopped.

This is how I landed 3 merged and active pull requests across two repositories of VoiceyBill — a real-world, open source web app that lets users track income and expenses through voice input, AI receipt scanning, and analytics dashboards. Contributions here are not practice exercises — they ship to actual users on a live production deployment.

That raised the stakes. And honestly, that is what made it worth doing.

Key Terms — Read This First If You Are New

Repository (Repo): A project hosted on GitHub containing all the source code, history, and files.

PR (Pull Request): A proposal to add your code changes to the main project. The primary unit of open source contribution.

Fork: Your personal copy of someone else's repository. You make changes here safely, then open a PR.

Branch: A separate version of the code where you work on a feature without touching the main codebase.

Merge: When the project maintainer accepts your PR and adds your code to the main project.

RTK Query: Redux Toolkit Query — a data-fetching tool used by VoiceyBill's frontend instead of Axios.

ExcelJS: A Node.js library for creating and formatting Excel spreadsheet files programmatically.

JWT (JSON Web Token): A secure token sent with API requests to prove the user is logged in.

CI/CD: Automated checks (lint, build, tests) that run every time you push code. If they fail, your PR cannot merge.

Conventional Commits: A standard for writing commit messages: feat(), fix(), chore() etc. Keeps history readable.

Part 1: The Roadmap — From Observer to Contributor

This is the exact path I followed. You can follow it too, regardless of your experience level.

Phase 1 — Understand What Open Source Actually Is

Open source means the source code of a project is publicly available for anyone to read, use, and contribute to. When you contribute, you are not just writing code — you are joining a team with real standards, real reviews, and real users depending on your work.

VoiceyBill has three public repositories:

voiceyBill-web — the frontend (React, TypeScript, Tailwind CSS)
voiceyBill-server — the backend REST API (Node.js, Express, MongoDB)
voiceyBill-App

All accept contributions. I worked on couple of them.

Phase 2 — Build Your Basics First

You do not need to be an expert. But you need to be comfortable with these fundamentals before touching a production codebase:

Git — clone, branch, commit, push, pull, merge
GitHub — forking, opening PRs, responding to review comments
Your stack — at least enough to read and understand existing code

If any of these feel unfamiliar, spend a few days on them first. A rough or broken first contribution is worse than no contribution — it creates work for the maintainers and damages your confidence.

Phase 3 — Find the Right Project

Not every project welcomes beginners. Look for these green flags:

A CONTRIBUTING.md file that explains how to contribute
Issues labeled good first issue or help wanted
Active maintainers who respond to PRs within a few days
A project you actually care about or find interesting

VoiceyBill had all of these. The maintainers responded quickly, the issues were clearly described, and the product itself — a voice-powered finance tracker — was genuinely interesting to work on.

Phase 4 — Study the Codebase Before Writing Any Code

This is the most skipped step and the most important one.

Before I opened a single issue, I spent time:

Reading the existing PRs to understand what "good" looked like
Studying the folder structure of both repositories
Observing the team's commit message style (feat(), fix(), etc.)
Understanding the architecture — how the frontend talks to the backend

When I finally wrote code, I was following patterns I had already internalized — not guessing.

Phase 5 — Claim an Issue and Plan Your Work

Find an issue that matches your skill level. Comment on it to let the maintainers know you are working on it. This prevents two people from solving the same problem simultaneously.

Then plan before you code:

What files will I need to touch?
Does this change affect the frontend, backend, or both?
What is the expected behavior when I am done?

Phase 6 — Build, Test, and Document

Write your code. Test it manually. Run the project's lint and build commands. Then write your PR description as if you are explaining it to a teammate who has no context.

A great PR description includes:

A summary of what the change does and why
Step-by-step instructions for how to test it
Screenshots or recordings if there are visual changes
The issue number it closes

Phase 7 — Treat Code Review as a Learning Tool

When reviewers leave comments, they are not attacking you. They are doing their job — protecting the quality of a codebase that real users depend on.

Read every comment carefully. Fix what needs fixing. Push the update. Re-request review. Repeat until merged.

The review process is where you grow the fastest.

Part 2: PR #114 — Backend CSV Export (voiceyBill-server)

What Is a Backend? Why Does It Matter?

If you are new to full-stack development, here is a quick mental model:

The frontend is what users see in their browser — buttons, forms, dashboards
The backend is the server that runs behind the scenes — it handles data, business logic, authentication, and file generation

When a user clicks "Export CSV," the frontend sends a request to the backend. The backend generates the file and sends it back. The frontend then triggers the download.

This PR built the backend half of that flow.

The Issue

The project needed a way for users to download their full transaction history as a spreadsheet. The issue asked for an API endpoint that:

Checks that the user is logged in (authentication)
Fetches only that user's transactions from the database
Generates a formatted Excel file
Sends it back as a downloadable response

What I Built

I implemented the complete backend feature following VoiceyBill's existing controller → service → route architecture. Here is what that means in plain terms:

User clicks "Export" in browser
         ↓
Frontend sends: GET /api/transactions/export
         ↓
Route  →  Controller  →  Service  →  Database
                              ↓
                      ExcelJS generates .xlsx file
                              ↓
                 Backend sends file back to browser
                              ↓
              Browser downloads transactions.xlsx

The files I created or modified:

Service layer — exportTransactionsService: queries the database for the authenticated user's transactions, builds an Excel workbook using ExcelJS with bold/centered headers and formatted rows
Controller — exportTransactionsController: handles the HTTP request, calls the service, sets the correct response headers
Route — registered GET /api/transactions/export with authentication middleware so only logged-in users can access it

The spreadsheet columns exported:

Title	Amount	Type	Category	Date	Payment Method	Description	Recurring	Created At

The endpoint details:

GET /api/transactions/export
Authorization: Bearer <your-jwt-token>

Response: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
File: transactions.xlsx

How to Test It (Step by Step)

If you want to test this endpoint yourself after cloning the repo:

# 1. Start the backend server
npm run dev

# 2. Make sure MongoDB is running (local or Atlas)

# 3. Login through the API to get your JWT token

# 4. Call the export endpoint with your token
GET http://localhost:8000/api/transactions/export
Authorization: Bearer <your-token-here>

# 5. Open the downloaded transactions.xlsx in Excel or Google Sheets

The Review Process — CI Failure

The feature worked locally. But after I opened the PR, the project owner voiceyBill flagged that the CI workflow was failing.

CI (Continuous Integration) is an automated system that runs checks on every PR — linting, building, and testing the code. If CI fails, the PR cannot be merged, even if the code itself is correct.

The issue was a missing package-lock.json file. When I added a new dependency (ExcelJS), I did not commit the lock file that records the exact package versions. The CI pipeline could not reproduce the exact environment and failed.

Fix: I added the missing package-lock.json and pushed the update.

** Beginner Tip**

Always commit your package-lock.json (or yarn.lock) when you add or update dependencies.

This file locks down the exact version of every package so that CI servers and other developers get the same environment you tested with. Skipping it is one of the most common first-time mistakes.

The Outcome

✅ Merged

Approved by zainAwan9175 after CI checks passed.

Merged into main on June 6, 2026.

4 commits. 8 CI checks passed. Backend export live in production.

After the merge, the maintainer commented: "@HamzaAmir1470, now open the PR for the mobile app also." — a signal that the team trusted the work and wanted more.

Part 3: PR #145 — Frontend CSV Export (voiceyBill-web)

Connecting Frontend to Backend

Once the backend endpoint existed (PR #114), the frontend needed to actually call it and trigger the download in the browser. These two PRs are two halves of the same feature — one on each repository.

The Issue

Issue #116 asked for an Export CSV button on the Transactions page that:

Calls the backend endpoint when clicked
Shows the user feedback during the process (loading, success, error)
Triggers a file download in the browser when the backend responds

What I Built

I added an Export CSV button to the Transactions page using RTK Query's lazy query pattern:

User clicks "Export CSV" button
         ↓
Toast shows: "Preparing export..."
         ↓
useLazyExportTransactionsQuery() fires the API call
         ↓
Backend responds with .xlsx blob
         ↓
downloadCsv() utility triggers browser download
         ↓
Toast shows: "Export completed" ✅

The Review Process — Three Rounds of Corrections

The feature worked. But the review process taught me far more than the build did.

Round 1: Duplicated Logic

Reviewer Syed-Bilal-Haider-Engineer spotted that my download logic — creating a blob URL, appending a link to the DOM, clicking it, and revoking the URL — was written twice: once for the Transactions page and once for the Reports page.

His suggestion: extract it into a shared reusable utility.

// src/utils/downloadCsv.ts
export function downloadCsv(blob: Blob, filename: string): void {
  const url = window.URL.createObjectURL(blob);
  const link = document.createElement("a");
  link.href = url;
  link.download = filename;
  document.body.appendChild(link);
  link.click();
  document.body.removeChild(link);
  window.URL.revokeObjectURL(url);
}

** Beginner Tip: The DRY Principle**

DRY stands for "Don't Repeat Yourself." If the same logic exists in two places, it should live in one shared function.

Why? Because if you need to fix a bug in that logic later, you only fix it in one place — not hunt down every copy.

I refactored it. Done. Or so I thought.

Round 2: Missed Caller

A second reviewer — zainAwan9175 — caught that src/pages/transactions/index.tsx still contained the old duplicated implementation. I had created the shared utility but forgotten to update one of the original callers.

Another fix pushed. This kind of mistake is common. It is why code review exists.

Round 3: Wrong Dependency

A third flag: I had accidentally added axios to package.json, even though VoiceyBill deliberately uses RTK Query for all API calls. The project had made a deliberate architectural choice to use one data-fetching tool consistently.

** Beginner Tip: Respect Project Architecture**

Every codebase has intentional technology choices — which HTTP client to use, which state manager, which styling approach.

Before adding a new dependency, check what the project already uses. If there is already a tool for the job, use that one.

Removed the axios import. All three issues addressed.

The Outcome

PR #145 is still under active review with all requested changes addressed, pending final approval from the maintainers. The backend is live. The frontend is ready.

Part 4: PR #171 — Mobile Sidebar Close Button (voiceyBill-web)

The Issue

Issue #132 identified a real usability failure: on mobile, the sidebar opened but had no way to close. Once open, it covered the entire content area with no escape route — affecting every mobile user of the application.

This is a UI/UX bug — the kind of issue that is highly visible, clearly scoped, and very satisfying to fix.

What I Built

I made the sidebar fully responsive without touching any existing desktop behavior.

What "responsive" means for beginners: A responsive UI adapts its layout based on the screen size. The same component behaves differently on a 375px phone screen versus a 1440px desktop monitor.

On screens below 768px (mobile), I added:

Hamburger button (☰) — floating in the top-left corner, opens the sidebar
Slide-out sidebar — animates in from the left, same width as desktop
Close button (✕) — inside the sidebar, explicitly closes it
Backdrop overlay — a semi-transparent layer behind the sidebar; clicking it closes the sidebar
Auto-close on navigation — tapping any nav link automatically closes the sidebar
Top padding fix — pt-20 on mobile / pt-8 on desktop so page content is not hidden behind the floating button

On desktop: nothing changed. Every existing behavior — expanded/collapsed state, navigation links, VoiceyAI card, logout button — remained identical.

The only file changed: src/components/sidebar/index.tsx

Accessibility — Why It Matters

Accessibility means making your UI usable by everyone, including people using screen readers, keyboard navigation, or assistive technology.

For this PR, I added:

aria-label attributes on all new buttons so screen readers can announce their purpose
Proper focus management — when the sidebar opens, focus moves into it; when it closes, focus returns to where it was
Full keyboard navigation support — users can tab through the sidebar and press Escape to close it

** Beginner Tip: Always Think About Accessibility**

Accessibility is not optional in production software. It is often a legal requirement and always the right thing to do.

The simplest habit to build: every interactive element (button, link, input) should have a clear, descriptive label.

Testing — Why You Must Test Before Submitting

Before submitting, I tested the component across six browsers:

Browser	Status
Chrome (latest)	✅
Firefox (latest)	✅
Safari (latest)	✅
Edge (latest)	✅
Mobile Safari (iOS)	✅
Chrome Mobile (Android)	✅

** Beginner Tip: Test on Real Devices**

Chrome DevTools mobile emulation is a good start, but it does not perfectly replicate real device behavior — especially on iOS Safari.

If you are building anything that affects mobile layout, test on a real phone before submitting.

The Outcome

✅ Merged

Reviewed by ahadalireach: "awesome work man."

Approved by project owner voiceyBill.

Merged into main on June 5, 2026.

One commit. Clean history. No requested changes. First-pass approval.

Part 5: The Full Picture — 3 PRs Across 2 Repositories

Here is how all three contributions connect:

User on Mobile
      ↓
[PR #171] Mobile sidebar works — user can navigate the app
      ↓
User goes to Transactions page
      ↓
[PR #145] Clicks "Export CSV" → Frontend fires API call
      ↓
[PR #114] Backend generates Excel file → Sends to browser
      ↓
User downloads transactions.xlsx ✅

Each PR was a standalone contribution. Together, they deliver a complete user-facing feature — end to end, across two repositories, across frontend and backend.

Part 6: Real-World Challenges — What Nobody Warns You About

Challenge 1: The Codebase Feels Overwhelming

Every new codebase does. There are architectural patterns you have not seen, naming conventions you did not expect, and files that seem to do the same thing. This is normal.

The solution is not to understand everything before starting. It is to understand enough to do the specific task you have claimed, then let your understanding grow with each contribution.

Challenge 2: CI Failures Are Not Personal

When CI fails on your PR, it is not a judgment of your ability. It is the automated system doing its job — catching things that humans miss. PR #114's CI failure (the missing package-lock.json) was a one-line fix, but it required understanding why the CI system cares about that file.

Read the CI logs carefully. They tell you exactly what failed and usually point to the file and line number.

Challenge 3: Review Feedback Stings — Then It Helps

Three rounds of corrections on PR #145 felt uncomfortable in the moment. In hindsight, each one made the code meaningfully better:

Round 1 taught me about the DRY principle in a real codebase
Round 2 taught me to audit all callers when extracting shared logic
Round 3 taught me to respect project-level architectural decisions

No tutorial teaches these lessons as well as a real reviewer does.

Challenge 4: Every Project Has Rules You Have to Discover

VoiceyBill uses RTK Query, not Axios. It uses ExcelJS for spreadsheet generation. It has specific commit message formats. These rules are not always in the documentation — sometimes you learn them from a review comment.

When you discover a project rule, write it down. Do not repeat the same mistake.

Challenge 5: Patience Is a Skill

PR #145 is still awaiting final approval. The backend is live. The frontend is ready. The review has been thorough and constructive. Now I wait — and while waiting, I look for the next issue to work on.

Open source moves at its own pace. The maintainers are often doing this work between other responsibilities. Respect their time. Follow up professionally if a PR sits too long without response. Never send repeated messages demanding attention.

Part 7: Strengths and Limitations of Open Source Contribution

What You Gain

Real code review. Engineers you have never met read your code line by line and tell you what is wrong. This feedback is more valuable than any course.

Production exposure. Your code runs for real users on real servers. The accountability is genuine.

Portfolio credibility. A merged PR to an active public project is verifiable proof — anyone can read the code, the comments, and the review history.

Architectural thinking. Working in a real codebase forces you to think about how your change fits into a larger system — not just whether it works in isolation.

Community. You join a network of developers who share standards, norms, and context. After my PRs, the maintainer invited me to open another one. That invitation is worth more than a certificate.

What You Must Manage

Time and patience. Reviews happen on the maintainer's schedule, not yours.

Codebase learning curve. Every new project is a new mental model. Budget reading time before building time.

Rejection. Not every PR gets merged. Sometimes the approach conflicts with the project's direction. This is information, not failure.

Dependency on others. If the maintainer is unavailable, your PR waits. This is part of collaborative software development.

Part 8: Key Takeaways

You do not need to be senior. All three of these PRs were built by someone learning in public. Patience and professionalism matter more than seniority.
Read before you write. The fastest path to a merged PR is understanding what the team already expects — their conventions, their architecture, their tools.
Full-stack contributions are possible. PR #114 was backend. PR #145 was frontend. PR #171 was UI. You do not have to pick a lane on your first day.
CI failures are fixable. When automated checks fail, read the logs, understand why, and fix it. It is rarely as serious as it looks.
Working code is not the finish line. Code also needs to be consistent, non-duplicated, and aligned with the project's architectural choices.
One focused PR beats three scattered ones. PR #171 merged on the first review because it did one thing, documented it completely, and tested it thoroughly.
Every review makes you better. The corrections on PR #145 — three rounds of them — were the most educational part of this entire journey.
The first PR is the hardest. After it, the process is familiar, the codebase is less foreign, and the maintainers are less intimidating.

Part 9: How to Start — Your Action Plan

If you are reading this and have not made your first open source contribution yet, here is a concrete plan:

Week 1: Pick a project you use or find interesting. Read its README, CONTRIBUTING.md, and 5–10 existing PRs. Do not write any code yet.

Week 2: Set up the project locally. Make sure it runs. Read the folder structure until you could explain it to someone else.

Week 3: Find a good first issue. Comment to claim it. Plan your approach. Ask a question in the issue if something is unclear — maintainers appreciate engaged contributors.

Week 4: Build your solution. Test it manually. Run lint and build. Write a detailed PR description. Submit.

After submission: Respond to every review comment within 24 hours. Make changes promptly. Be professional and thankful.

Then look for the next issue and do it again.

Part 10: Further Reading

Git Branching Strategies — trunk-based development, feature branches, and when to use each
Writing Good PR Descriptions — how to communicate change intent clearly to reviewers
Conventional Commits Specification — the standard used by VoiceyBill and most modern projects
The DRY Principle — why duplicated code creates long-term maintenance problems
React Accessibility (a11y) — ARIA attributes, keyboard navigation, and focus management
RTK Query Docs — data fetching and caching in Redux Toolkit applications
ExcelJS — generating and formatting Excel files in Node.js
Understanding CI/CD — what automated pipelines check and why they matter

Closing Thought

Open source contribution is not about adding more code. It is about adding structure, care, and precision to a codebase that other people depend on.

VoiceyBill did not make me a better developer by being easy. It made me better by being real — real standards, real reviewers, real users, and real consequences when something breaks.

Three PRs across two repositories. One complete feature delivered end-to-end. Multiple rounds of review that sharpened the code and my thinking.

Two of them are merged. One is pending. All of them taught me something that solo projects never could.

If you have been putting off your first contribution, this is your sign. The codebase is not too advanced. The maintainers are not too intimidating. The issues are not too complex.

Pick one issue. Clone the repo. Build it. Ship it.

That is how you start.

Hamza Amir · github.com/HamzaAmir1470

PR #114 — Backend CSV Export
PR #145 — Frontend CSV Export
PR #171 — Mobile Sidebar