Why Next.js?

Complete Full-Stack Solution

• Server and client components
• Built-in API routes
• Automatic code splitting
• Optimized image handling
• SEO-friendly by default

Server Components (App Router)

// app/page.tsx
import { getProducts } from '@/lib/data';

export default async function HomePage() {
  const products = await getProducts();

  return (
    <main>
      <h1>Products</h1>
      {products.map(product => (
        <ProductCard key={product.id} product={product} />
      ))}
    </main>
  );
}

API Routes

// app/api/products/route.ts
import { NextResponse } from 'next/server';
import { db } from '@/lib/db';

export async function GET() {
  try {
    const products = await db.product.findMany();
    return NextResponse.json(products);
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch products' },
      { status: 500 }
    );
  }
}

export async function POST(request: Request) {
  const body = await request.json();
  const product = await db.product.create({ data: body });
  return NextResponse.json(product);
}

Data Fetching Patterns

// Server Component - Direct database access
async function getUser(id: string) {
  const user = await db.user.findUnique({ where: { id } });
  return user;
}

// With caching
import { unstable_cache } from 'next/cache';

const getCachedProducts = unstable_cache(
  async () => db.product.findMany(),
  ['products'],
  { revalidate: 3600 }
);

My Production Setup

Performance

• Image optimization with next/image
• Font optimization
• Bundle analyzer

SEO

• Metadata API
• Sitemap generation
• robots.txt

Developer Experience

• TypeScript throughout
• ESLint & Prettier
• Tailwind CSS

Next.js simplifies full-stack development while maintaining excellent performance and SEO. The App Router and Server Components have transformed how I build web applications.

This post covers the technical decisions that got us there, the tradeoffs we made, and what I'd do differently.

The Scale Reality

50M MAU sounds like an abstract number. In practice it means spikes of hundreds of thousands of concurrent users during Ramadan, Quran audio files being streamed from every continent simultaneously, prayer time calculations for locations across the entire globe, and serving both high-bandwidth users in the West and users on 2G/3G connections in South Asia and Sub-Saharan Africa.

That last point shaped almost every technical decision. You can't optimize purely for fast connections. You have to think about the user opening the site on a 2G connection in rural Pakistan at 3am for Fajr prayer.

Frontend: Next.js as the Foundation

We built on Next.js. Server-side rendering was critical for two reasons: SEO (the Quran text needs to be indexable) and first-load performance on slow connections.

Each Surah page (114 in total) is statically generated at build time — meaning the first HTML response is near-instant, no waiting for JS to hydrate before the user sees text.

We were aggressive about code splitting: audio player logic only loads when the user actually interacts with audio. Next.js Image with AVIF/WebP fallback cut image payloads significantly while staying compatible with older devices.

Offline Audio Streaming

One of the most technically interesting problems: how do you let a user listen to Quran recitations with no internet?

Quran audio is broken into individual ayah (verse) recordings — up to 6,236 of them per reciter. You can't cache all of that upfront.

Our solution: when a user starts playing a Surah, we silently prefetch the next 10 ayahs in the background using Service Workers and the Cache API. If connectivity drops, playback continues seamlessly.

We also gave users an explicit "Download for offline" option for Surahs they listen to regularly.

Geospatial: Prayer Times at Scale

Prayer times are calculated based on GPS coordinates — simple until you consider DST rules that differ by country, multiple calculation methodologies (Hanafi, Shafi'i, MWL, ISNA), and users who want accurate times regardless of whether they share their location.

We moved prayer time calculation to the client side. The astronomy math runs in under a millisecond on any modern device, requires no server round-trip, and stores no user location data.

For map-based features — nearby mosques, Qibla direction — we used Mapbox GL JS. The vector tile approach is ideal: compact, cacheable, and sharp at any zoom level.

Database and Infrastructure

PostgreSQL was our primary data store. The Quran text is relational in nature — verses have translations, tafsirs, word-by-word breakdowns, audio timestamps, and cross-references. A relational model maps cleanly to this structure.

For our read-heavy endpoints (almost all of them), we leaned on read replicas to distribute query load, Redis for caching frequently-accessed data, and aggressive CDN caching at the edge for static API responses.

Infrastructure ran on AWS: ECS for containerized services, RDS for PostgreSQL, ElastiCache for Redis, CloudFront as CDN.

What I'd Do Differently

Invest in observability earlier. We added distributed tracing later than we should have. When you're debugging a latency spike that only affects users in a specific region, you want granular trace data — not logs.

Be more aggressive with edge caching. Many API responses could have been fully cached at the CDN layer, eliminating server load for the vast majority of requests. We were conservative about this early and paid the price during Ramadan traffic spikes.

Design for low-bandwidth from day one. We retrofitted a lot of optimizations later. Starting with that constraint leads to better decisions upfront — smaller bundles, progressive loading, offline-first thinking baked in from the beginning.

Closing Thoughts

Working on a platform where the content matters deeply to hundreds of millions of people sharpens your instincts. Performance isn't vanity. A 3-second improvement in load time is the difference between someone completing Fajr prayer with the app or giving up.

If you're working on similar challenges — high-scale web apps, geospatial features, or offline-capable PWAs — find me at zunain.com or on GitHub at mzulqarnain118.

This post covers the production patterns we actually use — chunking strategies, FAISS setup, cross-encoder reranking, and offline evaluation metrics that give you real signal.

The Core Problem with Naive RAG

Most tutorials show you this pipeline:

1. Split document into chunks
2. Embed chunks
3. Store in vector DB
4. At query time: embed query → find nearest chunks → stuff into LLM prompt

It works in demos. It fails in production. Here's why:

Fixed-size chunking splits sentences mid-thought. A chunk ending with "The model performs well when" and the next chunk starting "the temperature is above 0.7" means neither chunk retrieves correctly for a query about model behavior.

No score threshold means garbage in, garbage out. If you retrieve the top-k regardless of score, you'll pass irrelevant chunks to the LLM. The LLM will either hallucinate or say "I don't know" — even when the answer exists in your corpus.

Bi-encoder similarity is approximate. Fast for retrieval, but the dot product between independently encoded embeddings is a coarse approximation of relevance. A cross-encoder that jointly processes the query and document is far more accurate.

Chunking: Get This Right First

Four strategies worth knowing:

Fixed-size chunking — Simple. Chunk every N tokens with M token overlap. Fast, predictable. Bad for prose, acceptable for structured data.

Sentence-boundary chunking — Split on sentence endings, accumulate until you hit the size limit, then start a new chunk with overlap. This preserves semantic units. What we use for most text at Quran.com.

Recursive chunking — Try paragraph splits first. If still too large, try sentence splits. If still too large, try word splits. LangChain's RecursiveCharacterTextSplitter is the standard implementation.

Semantic chunking — Embed each sentence, detect where cosine similarity drops (meaning shift), split there. Highest quality, ~5x slower. Worth it for high-stakes retrieval.

Key parameter: overlap matters more than chunk size. We found 10–15% overlap (e.g., 50 tokens of overlap on 400-token chunks) gives the best recall without wasting context budget. Too little and you lose context at boundaries. Too much and you fill the LLM prompt with duplicate content.

FAISS Setup for Production

import faiss
import numpy as np
from sentence_transformers import SentenceTransformer

model = SentenceTransformer('all-MiniLM-L6-v2')
dim = model.get_sentence_embedding_dimension()  # 384

# For small-medium corpora (<500k docs): IndexFlatIP
index = faiss.IndexFlatIP(dim)

# For large corpora (>500k docs): IndexHNSW
# index = faiss.IndexHNSWFlat(dim, 32)

Always normalize your embeddings before adding to an IP index. This makes inner product equivalent to cosine similarity.

def embed_and_add(texts, index, model, batch_size=64):
    for i in range(0, len(texts), batch_size):
        batch = texts[i:i+batch_size]
        embeddings = model.encode(batch, normalize_embeddings=True)
        index.add(embeddings.astype('float32'))

Score threshold is your most important hyperparameter. Set it empirically on a validation set, not by gut.

def retrieve(query, index, chunks, model, top_k=10, threshold=0.5):
    query_vec = model.encode([query], normalize_embeddings=True).astype('float32')
    scores, indices = index.search(query_vec, top_k)
    results = []
    for score, idx in zip(scores[0], indices[0]):
        if idx != -1 and score >= threshold:
            results.append((chunks[idx], float(score)))
    return results

Cross-Encoder Reranking

The pattern: retrieve top-20 with a fast bi-encoder, then rerank to top-5 with a cross-encoder.

Cross-encoders jointly process the query and document through the full attention mechanism. They're 10–100x slower than bi-encoders but far more accurate at judging relevance.

from sentence_transformers import CrossEncoder

reranker = CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')

def rerank(query, candidates, top_k=5):
    pairs = [(query, chunk.text) for chunk, _ in candidates]
    scores = reranker.predict(pairs)
    ranked = sorted(zip([c for c, _ in candidates], scores),
                   key=lambda x: x[1], reverse=True)
    return ranked[:top_k]

At Quran.com, adding a cross-encoder reranker improved our semantic search precision from ~72% to ~89% on our eval set.

Evaluation: Context Precision and Recall

Don't evaluate RAG by running queries through the LLM and judging the answers. Evaluate the retrieval layer directly.

Context Precision — Of the chunks I retrieved, what fraction are actually relevant? Context Recall — Of all the relevant chunks in my corpus, what fraction did I retrieve?

def context_precision(retrieved_chunks, relevant_sources):
    if not retrieved_chunks:
        return 0.0
    relevant = sum(1 for c in retrieved_chunks if c.source in relevant_sources)
    return relevant / len(retrieved_chunks)

def context_recall(retrieved_chunks, relevant_sources, all_chunks):
    total_relevant = sum(1 for c in all_chunks if c.source in relevant_sources)
    if total_relevant == 0:
        return 1.0
    retrieved_relevant = sum(1 for c in retrieved_chunks if c.source in relevant_sources)
    return retrieved_relevant / total_relevant

Build a test set of (query, relevant_source_ids) pairs. Run your pipeline. Track precision and recall over time.

Production Patterns That Actually Matter

Cache at the right layer. Cache (query_embedding → chunk_ids), not (query_string → chunk_ids). Semantically similar queries hit the same cache entry. We use Redis with a 1-hour TTL and cut embedding inference load by ~60%.

Groundedness monitoring. Log every LLM response along with the context chunks. Periodically sample and check whether the answer is grounded in the context or hallucinated.

Fallback on low confidence. If no chunk clears your score threshold, don't pass empty context to the LLM. Return a "I don't have enough information to answer this" response. Users trust a system that knows what it doesn't know.

Semi-supervised eval improvement. Every time a user clicks on a search result, that's a weak positive label. Accumulate these signals to periodically retune your threshold and swap embedding models.

Conclusion

The gap between a RAG demo and production RAG is mostly about the decisions around the retrieval layer — chunking strategy, score thresholds, reranking, and systematic evaluation. Get these right and the LLM part largely takes care of itself.

The patterns here are what we've battle-tested at Quran.com serving 50M+ monthly users. They're not the only way, but they work.

If you want to see the full implementation as runnable code, check out the companion Kaggle notebook: rag_pipeline_from_scratch.

This post covers the technical decisions that got us there, the tradeoffs we made, and what I'd do differently.

The Scale Reality

50M MAU sounds like an abstract number. In practice it means spikes of hundreds of thousands of concurrent users during Ramadan, Quran audio files being streamed from every continent simultaneously, prayer time calculations for locations across the entire globe, and serving both high-bandwidth users in the West and users on 2G/3G connections in South Asia and Sub-Saharan Africa.

That last point shaped almost every technical decision. You can't optimize purely for fast connections. You have to think about the user opening the site on a 2G connection in rural Pakistan at 3am for Fajr prayer.

Frontend: Next.js as the Foundation

We built on Next.js. Server-side rendering was critical for two reasons: SEO (the Quran text needs to be indexable) and first-load performance on slow connections.

Each Surah page (114 in total) is statically generated at build time — meaning the first HTML response is near-instant, no waiting for JS to hydrate before the user sees text. We were aggressive about code splitting: audio player logic only loads when the user actually interacts with audio. Next.js Image with AVIF/WebP fallback cut image payloads significantly while staying compatible with older devices.

Offline Audio Streaming

One of the most technically interesting problems: how do you let a user listen to Quran recitations with no internet?

Quran audio is broken into individual ayah (verse) recordings — up to 6,236 of them per reciter. You can't cache all of that upfront. Our solution: when a user starts playing a Surah, we silently prefetch the next 10 ayahs in the background using Service Workers and the Cache API. If connectivity drops, playback continues seamlessly. We also gave users an explicit "Download for offline" option for Surahs they listen to regularly.

Geospatial: Prayer Times at Scale

Prayer times are calculated based on GPS coordinates — simple until you consider DST rules that differ by country, multiple calculation methodologies (Hanafi, Shafi'i, MWL, ISNA), and users who want accurate times regardless of whether they share their location.

We moved prayer time calculation to the client side. The astronomy math runs in under a millisecond on any modern device, requires no server round-trip, and stores no user location data. For map-based features — nearby mosques, Qibla direction — we used Mapbox GL JS. The vector tile approach is ideal: compact, cacheable, and sharp at any zoom level.

Database and Infrastructure

PostgreSQL was our primary data store. The Quran text is relational in nature — verses have translations, tafsirs, word-by-word breakdowns, audio timestamps, and cross-references. A relational model maps cleanly to this structure.

For our read-heavy endpoints (almost all of them), we leaned on read replicas to distribute query load, Redis for caching frequently-accessed data, and aggressive CDN caching at the edge for static API responses. Infrastructure ran on AWS: ECS for containerized services, RDS for PostgreSQL, ElastiCache for Redis, CloudFront as CDN.

What I'd Do Differently

Invest in observability earlier. We added distributed tracing later than we should have. When you're debugging a latency spike that only affects users in a specific region, you want granular trace data — not logs.

Be more aggressive with edge caching. Many API responses could have been fully cached at the CDN layer, eliminating server load for the vast majority of requests. We were conservative about this early and paid the price during Ramadan traffic spikes.

Design for low-bandwidth from day one. We retrofitted a lot of optimizations later. Starting with that constraint leads to better decisions upfront — smaller bundles, progressive loading, offline-first thinking baked in from the beginning.

Closing Thoughts

Working on a platform where the content matters deeply to hundreds of millions of people sharpens your instincts. Performance isn't vanity. A 3-second improvement in load time is the difference between someone completing Fajr prayer with the app or giving up.

If you're working on similar challenges — high-scale web apps, geospatial features, or offline-capable PWAs — find me at zunain.com or on GitHub at mzulqarnain118.