Event‑driven architectures are ideal for building scalable, resilient, and decoupled backends. Instead of tightly coupling synchronous calls, systems react to events and progress workflows asynchronously.

Azure Functions provides first‑class support for this style through HTTP triggers, queue triggers, and Event Grid triggers. In this post, we’ll build a real‑world order processing backend, walk through the code (Node.js runtime), explain the architectural responsibilities of each function, and show how to set everything up in Azure, queues, dead‑letter handling, Event Grid topics, and subscribers.

This is not a toy demo; it mirrors how production systems handle orders, payments, and notifications.

Solution Architecture Overview

Client
  → apiHTTPFunction (HTTP Trigger)
    → orders-queue
      → orderProcessFunction (Queue Trigger)
        → Event Grid Topic (order-events)
           → billingFunction (Event Grid Trigger)
            → notificationFunction (Event Grid Trigger)

Responsibilities

• apiHTTPFunction
  Accepts client intent, validates input, creates an order in the database (PENDING), and enqueues a command.
• orderProcessFunction
  Continues the workflow applies business rules, updates order state, and publishes domain events.
• billingFunction & notificationFunction
  React independently to domain events using Event Grid fan‑out.

This separation keeps HTTP fast, isolates failures, and allows independent scaling.

Implementing the Functions (Node.js)

All examples use Azure Functions v4 with Node.js.

1. HTTP Trigger — Accepting Orders

function.json

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["post"],
      "authLevel": "function"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "orderMessage",
      "queueName": "orders-queue",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

index.js

const crypto = require("crypto");

module.exports = async function (context, req) {
  const body = req.body || {};
  
  if (!body.customer_id || !Array.isArray(body.items)) {
    context.res = {
      status: 400,
      body: { error: "customer_id and items array are required" }
    };
    return;
  }
  
  // generate unique correlationId
  const correlationId = req.headers["x-correlation-id"] || crypto.randomUUID();
  
  // Insert into the table
  // Minimal pseudo code
  const orderId = crypto.randomUUID();
  
  const orderDocument = {
    orderId,
    customerId: body.customer_id,
    items: body.items,
    status: "PENDING",
    createdAt: new Date().toISOString()
  };
  
  // enqueue command
  context.bindings.orderMessage = JSON.stringify({
    orderId,
    correlationId
  });
  
  context.res = {
    status: 202,
    body: {
      message: "Order accepted",
      orderId,
      correlationId,
      status: orderDocument.status
    }
  };
};

Why this works

• HTTP remains low latency
• Only minimal DB work happens synchronously
• The queue guarantees retry if downstream processing fails

2. Queue Trigger — Processing Orders

This function owns business workflow progression, not simple CRUD.

function.json

{
  "bindings": [
    {
      "type": "queueTrigger",
      "direction": "in",
      "name": "queueMessage",
      "queueName": "orders-queue",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

index.js

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

module.exports = async function (context, queueMessage) {
  const { orderId, correlationId } = queueMessage;
  
  context.log({ correlationId, orderId }, "Processing order");
  
  // Idempotency check (pseudo)
  // if (order.status !== "PENDING") return;
  
  // Apply business logic
  const confirmed = true; // inventory / validation checks
  
  const eventType = confirmed ? "OrderConfirmed" : "OrderRejected";
  
  // Update DB state transactionally (pseudo)
  // status: PENDING → CONFIRMED | REJECTED
  
  const client = new EventGridPublisherClient(
    process.env.EVENT_GRID_TOPIC_ENDPOINT,
    new AzureKeyCredential(process.env.EVENT_GRID_TOPIC_KEY)
  );
  
  const event = {
    id: orderId,
    eventType,
    subject: `orders/${orderId}`,
    eventTime: new Date(),
    dataVersion: "1.0",
    data: { orderId, correlationId, status: eventType }
  };
  
  await client.send([event]);
  
  context.log({ correlationId, orderId }, "Domain event published");
};

Why Event Grid here?

• Emits facts, not commands
• Enables fan‑out without coupling
• Subscribers evolve independently

3. Event Grid Triggers — Billing & Notification

billingFunction/function.json

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "direction": "in",
      "name": "event"
    }
   ]
}

billingFunction/index.js

module.exports = async function (context, event) {
  if (event.eventType === "OrderConfirmed") {
    context.log("Charging customer for", event.data.orderId);
    // charge payment gateway
  }
};

notificationFunction/index.js

module.exports = async function (context, event) {
  if (event.eventType === "OrderConfirmed") {
    // send confirmation email
  } else if (event.eventType === "OrderRejected") {
    // send rejection email
  }
};

Each subscriber can fail or retry independently without affecting others.

Setting Up Azure Resources

1. Storage Queue + Dead‑Letter Queue

Create queues:

az storage queue create --name orders-queue
az storage queue create --name orders-queue-poison

Configure retries in host.json:

{
  "extensions": {
    "queues": {
      "maxDequeueCount": 5
    }
  }
}

Messages exceeding retries land in orders-queue-poison.

2. Event Grid Topic

az eventgrid topic create \
--name order-events \
--resource-group <rg> \
--location <region>

Store the endpoint and key as Function App settings.

3. Event Grid Subscriptions

az eventgrid event-subscription create \
--name billing-sub \
--source-resource-id <topic-id> \
--endpoint <billing-function-endpoint>


az eventgrid event-subscription create \
--name notification-sub \
--source-resource-id <topic-id> \
--endpoint <notification-function-endpoint>

Apply filters on eventType to reduce noise.

Key Design Principles

• Idempotency: Required for queues and events (at‑least‑once delivery)
• Transactional State Changes: Update DB before publishing events
• Correlation Tracking: Pass correlationId through HTTP → Queue → Event Grid
• Event‑Driven Fan‑out: Use Event Grid for facts, not commands

Common Pitfalls

• Missing idempotency → duplicate billing
• No poison queue monitoring
• Publishing commands via Event Grid
• Hard‑coding secrets instead of app settings / Key Vault
• Treating queues as CRUD instead of workflow continuation

Local Testing

• Use Azurite for queues
• Use local.settings.json for environment variables
• Test each function independently, then end‑to‑end

Azure Functions Triggers (Reference)

For completeness, below is a reference list of commonly used Azure Functions triggers. You will not use all of these in a single system, but it’s important to know what is available when designing event-driven architectures.

HTTP & API

• HTTP Trigger — Invoke a function via HTTP/HTTPS (REST APIs, webhooks)

Messaging & Eventing

• Queue Trigger (Azure Storage Queue) — Background processing, simple commands
• Service Bus Queue Trigger — Advanced messaging, DLQ, FIFO with sessions
• Service Bus Topic Trigger — Pub/sub messaging with multiple consumers
• Event Grid Trigger — Reactive fan-out for domain and infrastructure events
• Event Hub Trigger — High-throughput streaming (telemetry, logs, IoT)

Data & Storage

• Blob Trigger — React to blob uploads/changes
• Cosmos DB Trigger — React to inserts/updates via change feed
• Table Storage Trigger — React to table entity changes (limited scenarios)

Scheduling & Automation

• Timer Trigger — Scheduled jobs (cron-like)

Platform & Integration

• Durable Functions Triggers — Stateful workflows and orchestrations
• SignalR Trigger — Real-time messaging

Observations

• Queues and Service Bus are best for commands and workflow progression
• Event Grid is best for facts and fan-out
• Event Hub is optimized for high-volume streams, not business workflows
• Durable Functions are useful when orchestration logic becomes complex

Knowing the trigger landscape helps you choose the right tool for the job, rather than overloading a single trigger type.

Conclusion

Azure Functions, combined with queues and Event Grid, provide a production‑grade foundation for event‑driven backends. By separating intent intake, workflow processing, and domain event fan‑out, you get scalability, resilience, and clean evolution paths.

This architecture is widely used in real systems handling orders, payments, provisioning, and integrations and it scales far beyond simple CRUD applications.

Building Event‑Driven Backends with Azure Functions: HTTP, Queue, and Event Grid Triggers was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Have you ever wondered how your code compiles instantly on browser without even having compilers installed locally?

All codes are compiled/interpreted by Servers not your browser. Codes are sent to the server, and results are presented via response.

But it’s not just a simple REST API; there is a whole complex system working behind.

In this article, we’ll walk through the system design of such a platform, focusing on:

1. Core components and their responsibilities
2. Job queuing and asynchronous execution
3. Why polling is better than WebSockets for result tracking
4. How SQS visibility timeout protects against worker failures
5. Why Redis is used while the database remains the source of truth
6. Asynchronous code storage in S3
7. Docker-based isolated execution at scale

1. High-Level Architecture and Components

At a high level, the submission pipeline looks like this:

Client → API Gateway → Load Balancer → App Containers → Queue (SQS/RabbitMQ) → Workers → Docker Runners → Postgres + Redis + S3

A summarized flow of how the application will work?

1. The user submits code, which passes through the API Gateway and 
Load Balancer to the backend service, where a submission record is 
created and a job is pushed to the queue.

2. The backend immediately returns a submission_id to the client while 
the code is uploaded asynchronously to object storage.

3. Worker nodes continuously poll the queue, fetch the code, and execute it 
inside isolated Docker containers.

4. After execution, the worker updates the final result in the database and 
refreshes the cache.

5. The client polls the status API, which reads from cache first and falls 
back to the database if needed.

Let’s deep dive into the component and how it solves a specific problem.

Client (Browser / Mobile App)

• Sends code submissions.
• Polls for execution status and results.
• Displays verdicts and runtime statistics.

API Gateway

• Entry point for all requests.
• Handles authentication, rate limiting, and request validation.
• Shields internal services from direct exposure.
• Enables centralized logging and throttling.

Load Balancer

• Distributes traffic across multiple app containers.
• Ensures high availability and horizontal scalability.
• Allows rolling deployments with zero downtime.

App Containers (Backend Services)

• Accept submissions.
• Generate a unique submission_id.
• Store metadata in the database (initial status = PENDING).
• Upload code to object storage asynchronously.
• Push a job event into the queue.
• Expose APIs for status lookup.

These services are stateless, so they can scale easily.

Queue (Amazon SQS / RabbitMQ)

• Decouples request handling from execution.
• Buffers spikes in traffic.
• Guarantees reliable delivery of jobs to workers.
• Enables retry and failure handling.

Workers

• Continuously poll the queue.
• Pick up submission jobs.
• Fetch code from storage.
• Run code inside isolated Docker containers.
• Capture output, runtime, and memory usage.
• Update the result in the database and cache.

Docker Execution Environment

• Runs untrusted user code safely.
• Provides language-specific runtime images (Python, Java, C++, Go, JS).
• Enforces CPU, memory, and time limits.

Postgres (Primary Database)

• Stores submissions, users, problems, and verdicts.
• Maintains strong consistency and durability.
• Acts as the source of truth.

Redis (Cache)

• Caches submission status for fast reads.
• Reduces load on the database.
• Handles high-frequency polling efficiently.

S3 / Blob Storage

• Stores raw code submissions and artifacts.
• Cheap, durable, scalable storage.
• Decouples code persistence from the request lifecycle.

2. Job Queuing and Asynchronous Execution

Why not execute code synchronously?

Code execution can take seconds, and sometimes minutes (large inputs, timeouts, container startup). Keeping HTTP requests open would:

• Block server threads.
• Limit throughput.
• Cause timeouts and poor UX.

Solution: Async pipeline using a queue

Flow:

1. User submits code.
2. Backend:

• Creates submission_id.
• Writes a DB record with status = PENDING.
• Pushes a job message to the queue.

3. API immediately returns:

• { "submission_id": "abc123" }

4. Worker consumes the job and executes it asynchronously.

This allows:

• Independent scaling of API and workers.
• Natural backpressure handling via the queue.
• Fault isolation between submission and execution.

3. Why Polling is Better than WebSockets Here

At first glance, WebSockets seem attractive: push results in real time. In practice, polling is often a better tradeoff for online judges.

⚠️ Problems with WebSockets

1. Connection explosion

• Thousands of users → thousands of persistent connections.
• Memory and file descriptor pressure.
• Harder to scale across nodes without sticky sessions.

2. Infrastructure complexity

• Requires stateful connection routing.
• Load balancers and firewalls complicate upgrades.

3. Intermittent usage pattern

• Users submit once, wait briefly, then leave.
• Maintaining long-lived connections is wasteful.

4. Failure handling

• Reconnection logic becomes complex.
• Message delivery guarantees are harder.

✅ Why Polling Works Better

• Status checks are lightweight reads (Redis).
• Polling interval can be controlled (e.g., every 1–2 seconds).
• Fully stateless HTTP requests.
• Easy horizontal scaling.
• Natural fit for mobile and browser clients.

4. How SQS Visibility Timeout Protects Worker Failures

When a worker picks a message from SQS:

• The message becomes invisible for a configured duration (visibility timeout).
• If the worker finishes successfully:
• It deletes the message.
• If the worker crashes, hangs, or fails:
• The message becomes visible again after a timeout.
• Another worker reprocesses it.

Why this is important

Worker failures can happen due to:

• Container crashes.
• Out-of-memory errors.
• Node restarts.
• Network failures.

Visibility timeout ensures:

• No job is permanently lost.
• At-least-once processing guarantee.
• Automatic retry without manual intervention.

Design considerations

• Timeout should exceed maximum execution time + buffer.
• Use idempotent processing to avoid duplicate side effects.
• Optionally use a Dead Letter Queue after repeated failures.

This gives strong fault tolerance with minimal complexity.

5. Redis for Speed, Database as Source of Truth

Why Redis?

• Extremely fast in-memory reads.
• Handles high QPS from polling clients.
• Reduces pressure on the primary database.

Usage:

• Cache submission status.
• Cache recent execution results.
• TTL-based eviction.

Why Database remains source of truth?

Redis is:

• In-memory.
• Can lose data on restart (depending on persistence).
• Eventually consistent.

Postgres provides:

• Durability.
• Transactions.
• Auditable history.
• Strong consistency.

Update pattern

1. Worker finishes execution.
2. Update database in a transaction.
3. After commit, update Redis cache.
4. Clients read from Redis first.
5. On cache miss → fallback to DB.
6. This avoids stale or inconsistent results and keeps correctness intact.

Note: We cache the submission status with a short TTL so that during polling, we geta response instantly, and we don’t hit a DB query at every poll request. Keeping a short TTL helps manage memory in redis as it is just a cache, and if we keep a lot of data in redis then it can lead to performance issues, even though we use cache.

6. Asynchronous Code Storage in S3

Storing raw code in S3 provides:

• Cheap long-term storage.
• Easy audit and replay.
• Decoupling from database growth.

Why async upload?

Uploading large payloads synchronously:

• Increases API latency.
• Blocks request threads.
• Reduces throughput.

Pattern

• API accepts submission.
• Metadata saved immediately.
• Code upload happens asynchronously.
• Background task.
• Event-driven worker.
• Queue job references S3 path instead of raw code.

This keeps submission APIs fast and scalable.

Note: To partition source code, we use question_id as the partition key because if we partition based on user_id, it can lead to performance issues are these platforms have millions of users, and it’s not feasible to create these many partitions and comparing the number of questions, it will always be in thousands.

7. Docker Containers for Isolated Execution at Scale

Executing user code directly on host machines is dangerous.

Risks

• Malicious code execution. (Leaking sensitive information from the server)
• Infinite loops. (Can stuck the main server)
• Memory exhaustion. (Allocating tons of memory without cleanup can lead to system failures)
• File system access. (Trying to delete OS/Kernel level files)
• Network abuse. (Trying to hit unwanted URLs or making a DOS attack on gov websites)

Docker provides

• Process isolation.
• Resource limits (CPU, memory).
• Read-only filesystem.
• Controlled networking.
• Clean execution environment per run.

Scaling model

• Workers spin up containers dynamically.
• Language-specific base images.
• Containers destroyed after execution.
• Horizontal scaling based on queue depth.

This enables safe multi-tenant execution without risking platform stability.

Conclusion

An online judging platform is fundamentally a distributed execution pipeline:

• Queues decouple submission from execution.
• Polling simplifies scalability and reliability.
• Visibility timeout protects against worker failures.
• Redis optimizes read performance while DB ensures correctness.
• S3 decouples storage from compute.
• Docker enforces isolation and security at scale.

These design choices balance correctness, performance, cost, and operational simplicity, the same tradeoffs used by real production platforms.

Scalable Code Evaluation Systems: A Backend Engineering Case Study was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Your app works perfectly on your laptop.

Then it meets real users. The server crashes under load. The network drops in a subway tunnel. Someone rapidly taps the like button 47 times. A user on a 3G connection in a rural area wonders why nothing loads.

Sound familiar?

I spent months studying system design theory for interviews. I could draw architectural diagrams on whiteboards. But when it came time to build something real, I couldn’t connect those boxes and arrows to actual code.

I built a complete social media feed from scratch — not a simulated or demo-based implementation, but a production-ready application following patterns used by platforms such as Twitter, Facebook, and Instagram.

View the live demo and full source code →

The Requirements That Changed Everything

Build a social media feed.

Seems simple. Then the real requirements arrive:

• Works offline (subway commuters still want to scroll)
• Shows likes instantly (no waiting for server round-trips)
• Handles millions of posts (pagination that doesn’t get slower over time)
• Runs when the server is down (graceful degradation)
• Accessible for screen readers (WCAG 2.1 AA compliance)
• Feels instant (skeleton screens, not spinners)

Each requirement seems reasonable. Together, they require a fundamentally different architecture than the typical React tutorial.

Welcome to production system design.

The Architecture That Makes It Work

Here’s the mental model:

User
    ↓
React Components (presentation)
    ↓
Custom Hooks (business logic)
    ↓
State Management
    - React Query (server data)
    - Zustand (client state)
    - Context (auth)
    ↓
Cache (3 layers)
    - L1: Memory (instant)
    - L2: IndexedDB (persistent)
    - L3: Service Worker (static)
    ↓
API Service
    ↓
Backend Server

Why this specific structure?

Each layer has exactly one job. Components render. Hooks handle logic. Services manage network calls. This separation means you can test each layer independently, reuse logic across components, and add features without breaking existing code.

The three-layer cache is the secret sauce. More on that shortly.

Following a Like Button Click

The best way to understand the system is to follow a single user action through every layer. Let’s trace what happens when someone taps the heart icon.

The Click (0ms)

// components/feed/PostItem.tsx
function PostItem({ post }) {
  const { mutate: likePost } = useLikePost()
  return (
    <button onClick={() => likePost({ postId: post.id, isLiked: post.isLiked })}>
      ❤️ {post.likes}
    </button>
  )
}

Simple React component. Calls a mutation when clicked.

The Optimistic Update (1ms)

Here’s where it gets interesting:

// hooks/useLikePost.ts
function useLikePost() {
  return useOptimisticMutation({
    onMutate: (oldData, { postId, isLiked }) => {
      return {
        ...oldData,
        pages: oldData.pages.map(page => ({
          ...page,
          posts: page.posts.map(post =>
            post.id === postId
              ? {
                  ...post,
                  isLiked: !isLiked,
                  likes: post.likes + (isLiked ? -1 : 1)
                }
              : post
          )
        }))
      }
    },
  
mutationFn: ({ postId, isLiked }) => {
      return isLiked
        ? api.delete(`/api/posts/${postId}/like`)
        : api.post(`/api/posts/${postId}/like`)
    },
  })
}

The key insight: We update the UI before the server responds.

The heart turns red and the count increments in 1 millisecond. The server call happens in the background. If it succeeds, we keep the changes. If it fails, we roll back.

The timeline:

0ms:    User clicks
1ms:    Heart turns red, count updates
500ms:  Server responds

Compare this to the traditional approach:

Old way: Click → Wait 500ms → See result (feels slow)

New way: Click → See result → Server confirms (feels instant)

This is why Twitter, Facebook, and Instagram feel responsive even on slow connections.

The Offline Fallback (when there’s no network)

if (!isOnline) {
  await offlineQueue.enqueue('LIKE_POST', { postId, userId })
  toast.info('Will sync when you\'re back online')
  return
}

If the user is offline, we queue the action. They still see the heart turn red. When they reconnect, the queue processes automatically.

Result: The user can use the app on the subway. No frustrating error messages. Everything syncs when they surface.

The Three-Layer Cache (The Real Magic)

This is where most production applications differ fundamentally from tutorials.

The Problem with Simple Caching

You have two bad options:

1. Always show cached data: Fast, but users see stale information
2. Always fetch fresh: Accurate, but slow and wasteful

The solution? Multiple cache layers with different characteristics.

Layer 1: Memory (React Query)

Speed: < 1ms Persistence: Until page refresh

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60,      // Fresh for 1 minute
      gcTime: 1000 * 60 * 10,    // Cached for 10 minutes
      retry: 3,
      networkMode: 'offlineFirst'
    }
  }
})

When you load the feed, data goes into memory. Return 30 seconds later? Instant display from cache. Return 2 minutes later? Show cached data immediately, then refresh in the background.

Layer 2: IndexedDB

Speed: 5–10ms Persistence: Survives browser restarts

class IndexedDBCache {
  private readonly DEFAULT_TTL = 7 * 24 * 60 * 60 * 1000  // 7 days
  private readonly MAX_CACHE_SIZE = 50 * 1024 * 1024      // 50MB

  async set(store: string, key: string, value: any) {
    const entry: CacheEntry = {
      id: key,
      data: value,
      cachedAt: Date.now(),
      expiresAt: Date.now() + this.DEFAULT_TTL,
      size: JSON.stringify(value).length
    }
    await db.put(store, entry)
    if (totalSize > this.MAX_CACHE_SIZE) {
      await this.evictLRU()
    }
  }
}

Real scenario:

Day 1, 2:00 PM - Browse feed, cache 100 posts in IndexedDB
Day 1, 5:00 PM - Close browser completely
Day 2, 9:00 AM - Open app, see feed instantly from IndexedDB
                 Fresh data loads in background

Without IndexedDB, returning users see a blank screen with a spinner. With it, they see their feed immediately.

Layer 3: Service Worker

Speed: 1–2ms Persistence: Forever (until app update)

self.addEventListener('fetch', (event) => {
  const { request } = event

  // Static assets: Cache first
  if (/\.(js|css|woff2?|png|jpg|webp)$/.test(request.url)) {
    event.respondWith(cacheFirst(request))
  }
  // API calls: Network first, fallback to cache
  else if (url.pathname.startsWith('/api/')) {
    event.respondWith(networkFirst(request))
  }
  // HTML: Show cached while fetching fresh
  else if (request.mode === 'navigate') {
    event.respondWith(staleWhileRevalidate(request))
  }
})

The service worker handles static assets and provides offline functionality. JavaScript, CSS, and images load from cache. The app shell appears instantly, even offline.

How the Layers Coordinate

Request feed data
    ↓
L1 (Memory): Hit? Return in < 1ms
    ↓
L2 (IndexedDB): Hit? Return in 5-10ms, populate L1
    ↓
L3 (Service Worker): Hit? Return from cache
    ↓
Network: Fetch fresh data, update all layers

The impact is dramatic:

Why Offset Pagination Breaks at Scale

Here’s something that trips up many developers: the standard pagination approach fails with large datasets.

The Problem

-- Page 1: Fast
SELECT * FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 0;

-- Page 100: Slow
SELECT * FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 1000;

-- Page 10,000: Unusable
SELECT * FROM posts ORDER BY created_at DESC LIMIT 10 OFFSET 100000;

With offset pagination, the database must scan and discard all preceding rows. Page 10,000 means scanning 100,000 rows to return 10.

Twitter has billions of tweets. Offset pagination would never work.

The Solution: Cursor Pagination

Instead of “skip N rows,” we say “get rows after this specific post.”

// Cursor: base64-encoded position marker
const cursor = btoa(JSON.stringify({
  lastId: 'p42',
  timestamp: '2024-01-15T10:30:00Z'
}))

// SQL equivalent
SELECT * FROM posts
WHERE (created_at, id) < ('2024-01-15T10:30:00Z', 'p42')
ORDER BY created_at DESC, id DESC
LIMIT 10;

Performance: O(1) at any position. Page 10,000 is as fast as page 1.

Frontend Implementation

function useInfiniteScroll() {
  const { data, fetchNextPage, hasNextPage } = useInfiniteQuery({
    queryKey: ['feed', 'infinite'],

   queryFn: async ({ pageParam = null }) => {
      const response = await api.get('/api/feed', {
        params: { limit: 10, cursor: pageParam }
      })
      return response.data
    },
    getNextPageParam: (lastPage) => {
      return lastPage.hasMore ? lastPage.nextCursor : undefined
    },
  })
  const loadMoreRef = useCallback((node) => {
    if (!node || !hasNextPage) return
    const observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        fetchNextPage()
      }
    }, { rootMargin: '200px' })
    observer.observe(node)
  }, [hasNextPage, fetchNextPage])
  return { posts: data?.pages.flatMap(page => page.posts) ?? [], loadMoreRef }
}

The intersection observer triggers 200px before the user reaches the bottom. New posts load seamlessly. The user never waits.

Building Resilience: When Things Go Wrong

Servers fail. Networks drop. Users close their laptops mid-request. Production applications need to handle all of it gracefully.

Classifying Errors

Not all errors deserve the same treatment:

enum ErrorType {
  NETWORK = 'NETWORK',        // No internet → Retry
  TIMEOUT = 'TIMEOUT',        // Too slow → Retry
  SERVER = 'SERVER',          // 5xx → Retry
  VALIDATION = 'VALIDATION',  // 400 → Don't retry
  AUTH = 'AUTH',              // 401 → Don't retry
}

• Network errors? Retry automatically. The user might have reconnected.
• Validation errors? Show the message. Retrying won’t help.
• Auth errors? Redirect to login. The session expired.

Exponential Backoff

When the server is struggling, hammering it with retries makes things worse.

const RETRY_CONFIG = {
  maxAttempts: 3,
  baseDelay: 1000,    // 1 second
  maxDelay: 30000,    // 30 seconds
  backoffFactor: 2    // Double each time
}

function calculateDelay(attempt: number): number {
  const exponentialDelay = 1000 * Math.pow(2, attempt)
  const cappedDelay = Math.min(exponentialDelay, 30000)
  const jitter = Math.random() * 200 - 100  // Prevent thundering herd
  return cappedDelay + jitter
}

Wait times:

• Attempt 1: Wait 1 second
• Attempt 2: Wait 2 seconds
• Attempt 3: Wait 4 seconds
• Give up

The jitter is important. Without it, a thousand clients that failed simultaneously will all retry simultaneously, creating another spike.

Circuit Breaker

When the server is completely down, retrying is pointless. The circuit breaker pattern fails fast:

class CircuitBreaker {
  private state = 'CLOSED'  // CLOSED, OPEN, HALF_OPEN
  private failureCount = 0
  private lastFailureTime = 0

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    // After 60 seconds, try one request
    if (this.state === 'OPEN' && Date.now() - this.lastFailureTime > 60000) {
      this.state = 'HALF_OPEN'
    }
    // Fast fail if circuit is open
    if (this.state === 'OPEN') {
      throw new Error('Circuit breaker OPEN. Server is down.')
    }
    try {
      const result = await fn()
      if (this.state === 'HALF_OPEN') {
        this.state = 'CLOSED'
        this.failureCount = 0
      }
      return result
    } catch (error) {
      this.failureCount++
      this.lastFailureTime = Date.now()
      if (this.failureCount >= 5) {
        this.state = 'OPEN'
      }
      throw error
    }
  }
}

The flow:

CLOSED (Normal operation)
  → 5 failures
OPEN (Reject all requests immediately)
  → Wait 60 seconds
HALF-OPEN (Try one request)
  → Success: Back to CLOSED
  → Failure: Back to OPEN

Without this, users see 30-second timeouts on every action during an outage. With it, they see instant “Server unavailable” messages and can at least browse cached content.

The Offline Queue: Never Lose User Data

Users on spotty connections shouldn’t lose their work. The offline queue ensures every action eventually reaches the server.

class OfflineQueue {
  async enqueue(type: ActionType, payload: any) {
    const action = {
      id: `${type}_${Date.now()}`,
      type,
      payload,
      status: 'pending',
      retries: 0,
      timestamp: Date.now()
    }
    await db.put('offline-queue', action)
  }

  async processQueue() {
      const pending = await this.getPendingActions()
      for (const action of pending) {
        try {
          await this.executeAction(action)
          await this.markCompleted(action.id)
          toast.success(`${action.type} synced`)
        } catch (error) {
          action.retries++
          if (action.retries >= 3) {
            await this.markFailed(action.id)
            toast.error(`${action.type} failed after 3 retries`)
          }
        }
      }
    }
  }

The user experience:

User enters subway tunnel → Connection lost
User likes a post → Heart turns red, action queued
User creates a comment → Comment appears locally, action queued
User exits tunnel → Reconnects
Queue processes automatically → "All changes synced"

The 30-second auto-sync interval handles cases where the connection returns silently. The online event handler catches explicit reconnections.

State Management: The Right Tool for Each Job

One of the most common architectural mistakes is using a single state solution for everything.

The Decision Tree

Is this data from an API?
  → React Query (caching, refetching, pagination built-in)

Is this UI state shared across components?
  → Zustand (theme, modals, toasts)

Is this local to one component?
  → useState (form inputs, toggles)

Is this auth data needed everywhere?
  → React Context (user, permissions)

React Query for Server State

function useFeedPosts() {
  return useInfiniteQuery({
    queryKey: ['feed', 'infinite'],
    queryFn: async ({ pageParam = null }) => {
      const response = await api.get('/api/feed', {
        params: { limit: 10, cursor: pageParam }
      })
      return response.data
    },
    getNextPageParam: (lastPage) => lastPage.hasMore ? lastPage.nextCursor : undefined,
  })
}

You get caching, background refetching, loading states, error handling, request deduplication, and pagination support. For free.

Zustand for Client State

const useUIStore = create(
  persist(
    (set) => ({
      theme: 'light',
      toggleTheme: () => set((state) => ({
        theme: state.theme === 'light' ? 'dark' : 'light'
      })),
    }),
    { name: 'ui-storage' }
  )
)

Three lines to create a theme toggle with persistence. Compare that to Redux boilerplate.

Performance Optimizations That Actually Matter

Lazy Loading Images

Loading 200 images on page load destroys performance. Load them as users scroll:

function LazyImage({ src, alt }) {
  const [isInView, setIsInView] = useState(false)
  const imgRef = useRef()

  useEffect(() => {
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsInView(true)
          observer.disconnect()
        }
      },
      { rootMargin: '100px' }  // Load 100px before visible
    )
    if (imgRef.current) observer.observe(imgRef.current)
    return () => observer.disconnect()
  }, [])
  return (
    <div ref={imgRef}>
      {isInView ? <img src={src} alt={alt} /> : <div className="skeleton" />}
    </div>
  )
}

Impact: 100 posts with 2 images each goes from loading 200 images (20MB, 10 seconds) to loading 10 visible images (1MB, 1 second).

Code Splitting

Don’t load the analytics dashboard until someone visits it:

const Analytics = lazy(() => import('./pages/AnalyticsDashboard'))

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <Routes>
        <Route path="/" element={<FeedContainer />} />
        <Route path="/analytics" element={<Analytics />} />
      </Routes>
    </Suspense>
  )
}

Impact: Initial bundle drops from 500KB to 200KB. Time to interactive goes from 3 seconds to 1 second.

Preventing Re-renders with memo

When one post’s like count changes, don’t re-render 99 other posts:

const PostItem = memo(({ post, onLike }) => {
  return (
    <div>
      <p>{post.content}</p>
      <button onClick={() => onLike(post.id)}>
        ❤️ {post.likes}
      </button>
    </div>
  )
})

Impact: Liking a post re-renders 1 component instead of 100.

The Trade-offs

Every architectural decision involves trade-offs. Here’s how I thought through the major ones:

Consistency vs. Availability

When a user likes a post offline, I have two options:

Option A: Strong Consistency

• Data is always correct
• App breaks when offline
• Every action waits for the server

Option B: Eventual Consistency (chosen)

• Works offline
• Fast optimistic updates
• Temporary inconsistencies possible

For a social feed, speed and availability matter more than perfect consistency. Users accept occasional rollbacks over 500ms waits on every action.

Cache Duration Trade-offs

Different data have different freshness requirements.

Server vs. Client Rendering

Server-side: Better SEO, faster first paint, but complex setup and higher costs.

Client-side: Simple deployment, cheap static hosting, rich interactivity, but slower first paint.

For a social feed where interactivity matters more than SEO, client-side wins. The three-layer cache mitigates the slow first paint problem.

What’s Not Included (And Why)

This codebase intentionally omits some production features to stay focused on core system design patterns:

• Authentication: Uses a mock user. Real auth adds complexity without teaching new patterns.
• Real-time updates: WebSockets would be nice, but aren’t essential for demonstrating caching and offline support.
• File uploads: Validation exists, but no actual CDN integration.
• Rate limiting: Server returns 429,s but doesn’t actually limit.
• Push notifications: PWA manifest exists, but no push implementation.

Each of these could be a separate article.

What I Learned

Building this taught me things that whiteboards never could:

1. Optimistic updates change everything. The perceived performance improvement from instant feedback is worth the complexity of rollback handling.
2. Caching is harder than it looks. A single cache layer isn’t enough. You need different strategies for different data types and different persistence requirements.
3. Cursor pagination is non-negotiable at scale. Offset pagination’s linear degradation is unacceptable for any dataset that might grow.
4. Resilience patterns compound. Retry logic, circuit breakers, and offline queues work together to create an application that survives real-world conditions.
5. State management isn’t one-size-fits-all. Server state and client state have fundamentally different requirements.

Explore the Code

The complete source code is available with detailed comments explaining each pattern:

github.com/vue-simform/system-design-in-practice

Start with these files:

• src/hooks/useOptimisticMutation.ts — Optimistic updates pattern
• src/hooks/useInfiniteScroll.ts — Cursor pagination
• src/utils/indexedDBCache.ts — Persistent cache layer
• public/service-worker.js — Offline support

Then explore:

• src/utils/offlineQueue.ts — Offline mutation queue
• src/utils/errorHandling.ts — Retry logic and circuit breaker
• server/server.js — Backend cursor pagination

Further Reading & References

State Management & Data Fetching

• TanStack Query — Important Defaults
• TanStack Query — Caching Examples
• TanStack Query — Optimistic Updates
• TanStack Query — Mutations
• TkDodo — Mastering Mutations in React Query
• TkDodo — Concurrent Optimistic Updates
• Zustand Documentation
• Zustand GitHub
• Frontend Masters — Introducing Zustand

Client-Side Storage & Offline

• MDN — IndexedDB API
• MDN — Using IndexedDB
• MDN — IndexedDB Terminology
• web.dev — Work with IndexedDB
• MDN — Service Workers
• MDN — Caching in PWAs
• MDN — Offline and Background Operation
• Chrome — Workbox Caching Strategies
• web.dev — Service Worker and HTTP Caching

Progressive Web Apps

• web.dev — Progressive Web Apps
• Google Codelabs — Going Offline
• MDN — Making PWA Work Offline
• GitHub — Offline First Resources

Pagination

• Zendesk — Cursor vs Offset Pagination
• Milan Jovanovic — Why Cursor Pagination is Fast
• Prisma — Pagination Documentation
• PingCAP — Pagination in MySQL

Resilience Patterns

• Martin Fowler — Circuit Breaker
• Martin Fowler — Microservices Guide
• Java Design Patterns — Circuit Breaker
• AWS — Exponential Backoff and Jitter
• AWS — Retry with Backoff Pattern
• Microsoft — Implement Retries with Exponential Backoff
• Wikipedia — Exponential Backoff
• Baeldung — Resilience4j Backoff and Jitter

React Performance

• React — memo
• React — useMemo
• React — useCallback
• React — lazy
• Legacy React Docs — Code Splitting
• web.dev — Code Splitting with React.lazy
• Kent C. Dodds — When to useMemo and useCallback
• MDN — Intersection Observer API
• LogRocket — Lazy Loading with Intersection Observer

Distributed Systems

• IBM — CAP Theorem
• Wikipedia — CAP Theorem
• AWS — CAP Theorem Whitepaper
• Splunk — CAP Theorem Strategies
• AlgoMaster — CAP Theorem Explained

Accessibility

• WCAG 2.1 Specification
• WCAG 2 Overview
• Understanding WCAG 2.1
• What’s New in WCAG 2.1
• MDN — Understanding WCAG
• WebAIM — WCAG 2 Checklist

Books

• “Release It!” by Michael Nygard — The book that popularized the Circuit Breaker pattern
• “Designing Data-Intensive Applications” by Martin Kleppmann — Deep dive into distributed systems, CAP theorem, and data storage
• “High Performance Browser Networking” by Ilya Grigorik — Understanding network performance, caching, and service workers

Building production applications requires moving beyond tutorials. The patterns in this codebase have been battle-tested at companies handling millions of users. Now you have a working code to study and adapt.

If this was helpful, consider starring the repo. Questions? Open an issue.

For more updates on the latest tools and technologies, follow the Simform Engineering blog.

Follow us: Twitter | LinkedIn

System Design in Action: Building a Production-Ready News Feed was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

I spent four hours trying to configure Nx for my first monorepo. Then I discovered Turborepo and had it running in 15 minutes. That moment taught me something important: monorepos aren’t about the tools, they’re about solving real problems with your codebase.

This isn’t another “here’s how Google does it” article. This is what worked (and what spectacularly failed) for me and my teams across three different production systems.

Full Demo Project: Want to see all these patterns in action? Check out the complete Restaurant Management System Monorepo, a production-ready example implementing everything discussed in this guide.

Why This Guide Exists

You’ve probably seen monorepo articles that either:

• Show you a toy example that falls apart in production
• Assume you have Google’s infrastructure budget
• Skip the messy parts where things actually break

This guide is different. We’re building a real task management app from scratch, making actual mistakes, and fixing them the way you would in production.

What You’re Actually Building

Not another TODO app. A production-ready restaurant management system with:

Backend API (Express on port 3001)

• REST endpoints with proper validation
• Complex billing engine with configurable rules
• Database queries that won’t make your DBA cry
• Error handling that actually helps debugging

Customer Frontend (React on port 5173)

• Real-time order billing preview
• Menu browsing and cart management
• API calls that handle failures gracefully

Admin Dashboard (React on port 3002)

• Restaurant configuration and management
• Pricing, tax, and discount rule configuration
• Menu and order management

Shared Packages

• TypeScript types that prevent runtime errors
• Zod validators that work on both frontend and backend
• Reusable UI components
• Billing engine with rule-based calculations
• Database with Prisma ORM

The thing that changed everything for me: you validate once, use everywhere. No more “the API accepted this, but the frontend rejected it” bugs at 3 am.

See it in action: This entire system is built and documented in the demo repository. Clone it, run it, and see exactly how everything fits together.

The Monorepo Decision Tree

Use a Monorepo When:

You’re copy-pasting code between projects — If you’ve ever though,t “I just fixed this bug in Project A, now I need to copy the fix to Project B, C, and D” — monorepo solves this.

Frontend and backend teams are out of sync — Backend ships a breaking API change. Frontend doesn’t know until production explodes. With monorepos, TypeScript catches this at build time.

You want atomic commits across projects — Change the API signature? Update all callers in one pull request. No coordination nightmares across repos.

Your team is small to medium (2–20 devs) — Large enough to have code duplication problems, small enough that you don’t need dedicated tooling teams.

Avoid Monorepos When:

You need strict access control — Monorepos are all-or-nothing. If contractors shouldn’t see proprietary algorithms, you need separate repos.

Your repo is already 2GB+ — Git performance falls off a cliff. Fresh clones take forever. Developers hate waiting.

Teams are truly independent — If your mobile team never talks to your web team and they share zero code, separate repos are simpler.

You’re planning to open-source parts — Extracting code from monorepos into separate repos later is painful. Plan for this upfront.

The Truth About Monorepo Tools

The Tools Landscape (December 2024)

pnpm Workspaces — Start here

• Zero config beyond one YAML file
• Handles 90% of use cases
• Works with everything

Turborepo — Add this next

• Caching that actually speeds things up
• Simple config (20 lines, not 200)
• Built by Vercel, actively maintained

Nx — For the advanced use cases

• Comprehensive but complex
• Code generators save time at scale
• Best when you have 10+ packages

I spent two weeks evaluating tools. Here’s what I learned: start simple, add complexity only when you feel the pain.

My Actual Tool Migration Path

Month 1–3: Plain pnpm workspaces

• Good: Learning curve was 30 minutes
• Bad: Rebuilding everything on every change
• Breaking point: CI taking 8 minutes for trivial changes

Month 4–8: Added Turborepo

• Good: CI dropped to 2 minutes
• Bad: Still rebuilding too much locally
• Breaking point: Still manageable

Month 9+: Considering Nx

• Not there yet — Turborepo still handles our load

The key insight: tool complexity should match your pain level, not your ego.

Setting Up Your Production Monorepo

Project Structure That Scales

Why this structure wins:

Apps folder = things users interact with Packages folder = code that apps share Config package = one source of truth for tooling

I tried other structures. This one survived three major refactorings.

Step 1: Initialize the Workspace

Root package.json:

pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

turbo.json (the file that saves you hours):

That dependsOn: ["^build"] line? It means "build my dependencies first". Saves you from mysterious build failures.

The Seven Rules That Keep Monorepos Sane

Rule 1: Namespace Everything

Bad:

{
  "name": "types",
  "name": "ui"
}

Good:

{
  "name": "@demo/types",
  "name": "@demo/ui",
  "name": "@demo/database",
  "name": "@demo/billing-engine"
}

Why this matters: I once spent two hours debugging why imports weren’t working. Turned out our types package was conflicting with @types/node. Namespacing prevents this entirely.

Rule 2: Use Workspace Protocol

In your package.json dependencies:

{
  "dependencies": {
    "@demo/types": "workspace:*",
    "@demo/database": "workspace:*",
    "@demo/billing-engine": "workspace:*",
    "express": "^4.18.2"
  }
}

That workspace:* tells pnpm "link to my local package". Changes propagate instantly. No version bumps needed during development.

Rule 3: Share TypeScript Config

packages/config/tsconfig.base.json:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

Each app extends it:

{
  "extends": "@demo/typescript-config/node.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  }
}

Update TypeScript settings once, applies everywhere. Changed my life.

Rule 4: Controlled Package Exports

packages/types/package.json:

{
  "name": "@demo/types",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    },
    "./validators": {
      "types": "./dist/validators.d.ts",
      "default": "./dist/validators.js"
    }
  }
}

Now you can:

import { Restaurant, MenuItem } from '@demo/types';
import { createRestaurantSchema, createMenuItemSchema } from '@demo/types/validators';

Prevents importing server-only code in the browser. Saved me from a 500KB bundle size disaster.

Rule 5: One Source of Truth for Validation

This is the game-changer. packages/types/src/validators.ts:

Backend uses it:

Frontend uses it:

Why this is huge: Change the validation rules once, both frontend and backend enforce them. No more “API rejected valid frontend data” bugs.

Rule 6: Dev Server Proxy (CORS Killer)

apps/web/vite.config.ts:

What this does:

• Frontend runs on localhost:5173
• Backend runs on localhost:3001
• Request to /api/tasks gets proxied to backend
• Zero CORS configuration needed

In production, both are on same domain. No code changes required.

Rule 7: Build Outputs

Option A: Separate Builds Each app builds independently, deployed separately.

Option B: Unified Build (what I use) Frontend builds into API’s public folder:

// apps/web/vite.config.ts
export default {
  build: {
    outDir: '../api/public'
  }
}

API serves static files:

// apps/api/src/index.ts
app.use(express.static('public'));
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, '../public/index.html'));
});

One build, one deployment. Simpler infrastructure.

Common Mistakes (That I Made So You Don’t Have To)

Mistake 1: Not Setting Up Caching

Symptom: Every change rebuilds everything. CI takes forever.

Fix: Add this to turbo.json:

{
  "tasks": {
    "build": {
      "outputs": ["dist/**"],
      "dependsOn": ["^build"]
    }
  }
}

Turborepo caches build outputs. Second build is instant if nothing changed.

Mistake 2: Circular Dependencies

What happened: Package A imports Package B, Package B imports Package A. Build fails mysteriously.

Fix: Design rule — shared packages can’t import from apps. Apps import from packages. Never the reverse.

✅ apps/api → packages/types
✅ apps/api → packages/database
✅ apps/api → packages/billing-engine
✅ apps/web → packages/types
✅ apps/web → packages/ui
✅ apps/dashboard → packages/types
✅ apps/dashboard → packages/ui
✅ packages/ui → packages/types
✅ packages/billing-engine → packages/types
❌ packages/types → apps/api

Mistake 3: Forgetting to Build Packages

Symptom: Import from @demo/types shows "Cannot find module".

Fix: Packages need build steps. In package.json:

{
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  }
}

Run pnpm build from root. Turborepo handles the order.

Mistake 4: Not Using Path Aliases

Problem: Import paths like ../../../../shared/utils are fragile.

Fix: Use unique prefixes per app:

apps/web/tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/web/*": ["./src/*"]
    }
  }
}

apps/api/tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/api/*": ["./src/*"]
    }
  }
}

Now you can:

import { TaskList } from '@/web/components/TaskList';
import { taskService } from '@/api/services/tasks';

Unique prefixes prevent conflicts.

Mistake 5: Overusing Shared Code

What I did wrong: Created packages/utils and threw everything in there.

Why it’s bad: The shared package becomes a dumping ground. Grows to 50+ utilities. Half are used once.

Better approach: Create specific shared packages:

• packages/types - only types and validators
• packages/ui - only React components
• packages/database - only Prisma schema and client
• packages/billing-engine - only billing calculation logic
• packages/typescript-config - only shared TypeScript configs

Keep packages focused. If a utility is used by only one app, keep it in that app.

Real Performance Numbers

From my actual projects:

Installation Speed

• npm: 45 seconds (fresh install)
• yarn: 38 seconds
• pnpm: 15 seconds

pnpm wins by sharing packages across projects. 50–80% disk space savings.

Build Speed (with Turborepo)

• Without caching: 28 seconds
• With caching (no changes): 0.8 seconds
• With caching (types changed): 4.2 seconds

Turborepo only rebuilds what changed. 40–85% faster CI builds.

Git Clone Size

• Small monorepo (10 packages): 45MB
• Medium monorepo (30 packages): 180MB
• Large monorepo (50+ packages): 350MB+

Storage grows fast. This is the monorepo tax. Plan accordingly.

When Things Go Wrong: Debugging Guide

“Module not found” errors

Check these in order:

1. Did you run pnpm install at root?
2. Did you build the package? (pnpm build)
3. Is the package name correct in dependencies?
4. Does the package have an exports field?

Quick fix:

cd packages/types
pnpm build
cd ../..
pnpm install

Turborepo not caching

Check:

1. Is turbo.json in root?
2. Do tasks have outputs defined?
3. Did you change env variables? (Busts cache)

Force clean cache:

turbo run build --force

TypeScript errors in imports

Common cause: Source files in src/, built files in dist/, but imports point to src/.

Fix in package.json:

{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts"
}

Point to built files, not source.

Circular dependency hell

Symptoms: Mysterious build order failures, “Cannot access before initialization” errors.

Find the culprit:

npx madge --circular --extensions ts ./apps ./packages

Fix: Restructure imports to break the cycle. Usually means extracting shared code to a lower-level package.

The Migration Path: Moving to Monorepo

If You Have Existing Repos

Week 1: Setup

1. Create new monorepo
2. Set up pnpm-workspace.yaml
3. Add turbo.json
4. Don’t move code yet

Week 2–3: Move One App

1. Copy first app to apps/
2. Update imports to use workspaces
3. Verify builds work
4. Keep original repo as backup

Week 4+: Move Remaining Apps

1. One app per week
2. Extract shared code to packages as you go
3. Update CI/CD pipelines
4. Delete old repos only after successful deploys

Don’t: Move everything at once. Recipe for disaster.

Do: Incremental migration with rollback plan.

Alternative Approaches (When Monorepo Isn’t Right)

Git Submodules

Separate repos, referenced in parent repo.

Pros: Separate histories, fine-grained access Cons: Complex to work with, easy to mess up

Private npm Registry

Publish internal packages privately.

Options:

• Verdaccio (free, self-hosted)
• GitHub Packages (free with GitHub)
• npm private packages ($7/user/month)

When to use: Multiple teams, strict access control, willing to manage versions.

My Actual Development Workflow

Starting work:

git pull
pnpm install           # Installs all deps
pnpm dev              # Starts all apps

Turborepo runs everything in parallel. API on 3001, web on 5173.

Making changes:

1. Edit code in any package
2. Hot reload updates instantly
3. TypeScript errors show immediately
4. Shared packages rebuild automatically

Before committing:

pnpm lint             # Lints everything
pnpm test             # Runs all tests
pnpm build            # Builds for production

Turborepo runs tasks in dependency order. Caches what hasn’t changed.

Committing:

git add .
git commit -m "Add task filtering"
git push

CI runs same commands. Cache hits make it fast.

The Verdict After Three Years

What worked:

• Shared types eliminated entire classes of bugs
• Turborepo caching genuinely saved hours
• One repo simplified onboarding
• Atomic commits across frontend/backend were liberating

What didn’t:

• Git history got messy at 50+ packages
• Hard to give contractors partial access
• Some deployment platforms assumed one app per repo
• Learning curve steeper than expected

Would I do it again?

For my use case (small team, shared codebase, TypeScript stack): Absolutely.

For a different context (large org, strict access control, polyglot): Probably not.

Quick Decision Checklist

Use monorepo if:

• You have 2–20 developers
• Teams work on overlapping code
• You value type safety across boundaries
• CI/CD complexity isn’t a blocker
• Everyone can access all code

Avoid monorepo if:

• Need strict access control
• Repo is already 2GB+
• Teams are truly independent
• Deployment tooling fights single repos
• Team resists the change

Resources That Actually Helped

Must-reads:

• Turborepo docs (best quickstart guide)
• pnpm workspace guide (simple, practical)
• Nx documentation (when you need advanced features)

Avoid:

• Articles that only mention Google/Facebook scale
• Tutorials that skip production deployment
• Comparisons that cherry-pick metrics

Join communities:

• Turborepo Discord (active, helpful)
• Nx community (advanced discussions)
• r/javascript, r/typescript (general advice)

Final Thoughts

Monorepos aren’t magic. They’re a tool that solves specific problems:✅

• Code duplication between projects
• Type safety across boundaries
• Coordinating changes across apps
• Sharing configs and tooling

They create new problems: ❌

• Git performance at scale
• Access control complexity
• Deployment integration work
• Steeper learning curve

The decision isn’t “are monorepos good?” It’s “do monorepos solve my specific problems better than the alternatives?”

For me, on three different projects, the answer was yes. Your mileage will vary.

Start simple. Add complexity when you feel the pain. Measure results. Iterate.

That’s the real secret to monorepo success.

Complete Working Example

All code examples in this guide come from a real, working project:

Restaurant Management System — Full Monorepo Demo

• Complete source code with all patterns implemented
• Comprehensive documentation and setup guides
• Real-world billing engine with configurable rules
• Production-ready structure verified against best practices
• Ready to clone, run, and learn from

Clone it, explore it, use it as a template for your own monorepo!

Questions? Hit me up. I’ve made every mistake there is to make. Happy to save you some time.

For more updates on the latest tools and technologies, follow the Simform Engineering blog.

Follow us: Twitter | LinkedIn

The Real-World Monorepo Guide: What They Don’t Tell You was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Welcome back! In Part 1, we explored Method Channels and Event Channels — the communication foundation between Flutter and native code. In Part 2, we’ll dive into Platform Views, which allow you to embed native UI components directly into your Flutter app, along with best practices, testing strategies.

📖 ← Back to Part 1: Method Channels and Event Channels

📖 Part 2: Platform Views and Advanced Patterns (You’re here)

Platform Views: Embedding Native UI

Sometimes you need to embed native UI components directly into your Flutter app. This is where Platform Views come in. They allow you to display native Android Views or iOS UIViews within your Flutter widget tree.

Common Use Cases

• Google Maps SDK
• WebView with platform-specific features
• Camera preview
• Video players
• Native ads
• AR components

Performance Considerations

Platform Views come with a performance cost because they require hybrid composition or virtual displays. Use them only when necessary.

Platform Comparison

Android — Hybrid Composition (Default)
✅ Better performance
✅ Recommended for production apps

Android — Virtual Display (Legacy)
⚠️ Legacy mode
⚠️ Use only for backward compatibility

iOS — UIKitView
✅ Good performance
✅ Standard approach for iOS

Implementation Example: Native Text View

Let’s build a simple native text view that renders a platform-specific label (TextView on Android, UILabel on iOS).

Step 1: Add an Android platform-specific implementation

Start by creating the Native View logic. This class implements PlatformView and handles the actual rendering of the Android view.

Next, create a Factory class that creates instances of your native view.

Finally, register the factory in your MainActivity.kt. This tells the Flutter engine about your custom view type.

Step 2: Add an iOS platform-specific implementation

First, create the Native View class. This class inherits from NSObject and implements FlutterPlatformView.

Next, create the Factory class.

Finally, register the factory in AppDelegate.swift.

Note: In a real plugin, you would register this in your plugin’s main class. For the app runner, you can register it in the App Delegate.

Step 3: Create the Flutter Platform View widget

Now you can use the native view in your Flutter layout. Use AndroidView for Android and UiKitView for iOS.

Limitations of Platform Views

Platform Views are a powerful tool, but they are not a silver bullet. Consider these limitations:

• Performance Impact: Rendering native views is more expensive than rendering Flutter widgets. Each frame requires synchronization between the Flutter engine and the native UI system.
• Gesture Conflicts: Touch events pass through multiple layers. Sometimes, gestures might be consumed by the native view and not reach Flutter, or vice-versa. Careful configuration of gestureRecognizers is often needed.
• Keyboard Interactions: Handling focus and soft keyboards can be tricky when mixing Flutter text fields with native text fields, especially on Android versions using Virtual Displays.
• Frame Lag: In some scenarios, particularly with complex animations, the native view might lag one frame behind the Flutter UI due to the asynchronous nature of the rendering pipeline.
• Creation Param Size Limit: The creationParams are passed from Flutter to the native side using a platform channel. Therefore, they are subject to the same buffer size limitations as standard method calls (approx. 1MB on Android).

Best Practices for Platform Views

• Size constraints: Always provide explicit size constraints
• Gesture handling: Configure gesture recognizers appropriately
• Memory management: Properly dispose of resources
• Performance: Use sparingly, as they can impact rendering performance
• Hybrid composition: Prefer Android’s hybrid composition for better performance

Security Considerations

• Validate inputs: Never trust data from either side
• Permission handling: Request permissions appropriately
• Secure data transmission: Encrypt sensitive data
• Resource limits: Prevent resource exhaustion

Testing Platform Channels

Testing platform interactions doesn’t require running on a real device. You can mock the channel responses in your widget tests or unit tests.

Step 1: Test Setup

Ensure you have the flutter_test dependency. In your test file, initialize the test binding.

Step 2: Mock the Method Call Handler

Intercept calls to the platform channel and return a mock response. This simulates the native side returning data.

Step 3: Verify Results

Write the actual test case to verify that your Dart code responds correctly to the mocked native data.

Testing Event Channels

Testing EventChannel streams require mocking the defaultBinaryMessenger to emit events.

Bonus: Type-safe Channels with Pigeon

Writing manual method channel code (strings and maps) is error-prone. For production apps, consider using Pigeon.

Pigeon generates type-safe Dart, Java/Kotlin, and Objective-C/Swift code from a simple API definition.

1. Define API in Dart: abstract class DeviceApi { String getDeviceModel(); }
2. Run Pigeon: Generates the glue code for you.
3. Implement: Just implement the generated interface on Android/iOS.
4. Call: Use the generated Dart class to call native methods safely.

Quick Decision Guide

• Use Method Channels when: ✔️ Making one-off API calls ✔️ Calling platform-specific functions ✔️ Need bidirectional communication
• Use Event Channels when: ✔️ Streaming continuous data ✔️ Monitoring sensors or system events ✔️ Real-time updates from native code
• Use Platform Views when: ✔️ Embedding native UI components ✔️ Integrating third-party native SDKs with UI ✔️ Need platform-specific rendering

Conclusion

Mastering Flutter’s native integration isn’t just about adding features; it’s about removing the invisible barriers of cross-platform development. By leveraging Method Channels, Event Channels, and Platform Views, you effectively “hack” the limitations of a UI-only framework, transforming Flutter into a high-performance, native-powerhouse builder.

The real “power” doesn’t come from choosing between Flutter or Native. It comes from the ability to bridge them seamlessly. You now have the architectural blueprints to build apps that are as fluid as Dart and as powerful as the underlying OS.

The bridge is built. The power is unlocked. What will you build next?

Further Resources

• Official Platform Channels Documentation
• Flutter Plugins Development
• Platform Views Deep Dive
• Sample Code Repository

📖 ← Back to Part 1: Method Channels and Event Channels

For more updates on the latest tools and technologies, follow the Simform Engineering blog.

Follow us: Twitter | LinkedIn

Unlock Native Power in Flutter [Part 2] was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Flutter has revolutionized cross-platform development, but let’s face it, there are times when you need to tap into platform-specific APIs that Flutter doesn’t expose out of the box. Whether it’s accessing native sensors, integrating third-party SDKs, or leveraging platform-specific UI components, understanding how to bridge the gap between Flutter and native code is essential for building production-ready apps.

In this two-part series, we’ll learn about the complete spectrum of Flutter-native interaction mechanisms. Part 1 focuses on Method Channels and Event Channels the foundation of Flutter-native communication. Part 2 will cover Platform Views and advanced integration patterns.

📖 Part 1: Method Channels and Event Channels (You’re here)

📖 Continue to Part 2: Platform Views and Advanced Patterns →

Why Native Integration Matters

Before we dive into the technical details, let’s understand why native integration is crucial:

• Platform-specific APIs: Bluetooth, NFC, advanced camera features
• Third-party SDKs: Payment gateways, analytics, crash reporting
• Performance optimization: Heavy computations, image processing
• Native UI components: MapView, WebView with advanced features
• Background tasks: Geolocation tracking, push notifications

Flutter provides excellent coverage for most use cases, but the ecosystem is vast, and sometimes you need that extra mile of platform-specific functionality.

Platform Channels

At its core, Flutter uses platform channels to communicate between Dart code and native code (Kotlin/Java for Android, Swift/Objective-C for iOS). Think of it as a message-passing bridge that serializes data across the platform boundary.

Key Concepts

1. Channel Names: Unique identifiers for communication channels
2. Method Codecs: Serialize data between Dart and native (StandardMethodCodec, JSONMethodCodec)
3. Platform-specific implementations: Separate code for Android and iOS

Method Channels: Bidirectional Communication

Method Channels are the most common way to invoke platform-specific code from Flutter. They support asynchronous method calls with responses.

How It Works

1. Flutter calls a method on the Dart side
2. The call is serialized and sent to the native side
3. Native code processes the request
4. Result is serialized and returned to Flutter

Implementation Example: Device Model

Let’s build a practical example to fetch the device model name (e.g., “Pixel 6” or “iPhone 14”).

Step 1: Create the Flutter platform client

The app’s State class holds the current app state. Extend that to hold the current device model.

First, construct the channel. Use a MethodChannel with a single platform method that returns the device model.

The client and host sides of a channel are connected through a channel name passed in the channel constructor. All channel names used in a single app must be unique; prefix the channel name with a unique ‘domain prefix’, for example: com.example.app/device.

Next, invoke a method on the method channel, specifying the concrete method to call using the String identifier getDeviceModel. The call might fail—for example, if the platform doesn't support the platform API (such as when running in a simulator), so wrap the invokeMethod call in a try-catch statement.

Finally, replace the build method from the template to contain a small user interface that displays the device model in a string, and a button for refreshing the value.

Step 2: Add an Android platform-specific implementation

Start by opening the Android host portion of your Flutter app:

1. Navigate to the directory holding your Flutter app, and select the android folder inside it.
2. Open the file MainActivity.kt located in the kotlin folder in the Project view.

Inside the configureFlutterEngine() method, create a MethodChannel and call setMethodCallHandler(). Make sure to use the same channel name as was used on the Flutter client side.

Add the Android Kotlin code that uses the Android Build API to retrieve the device model. This code is exactly the same as you would write in a native Android app.

Step 3: Add an iOS platform-specific implementation

Start by opening the iOS host portion of your Flutter app:

1. Navigate to the directory holding your Flutter app, and select the ios folder.
2. Open the file AppDelegate.swift located under Runner > Runner in the Project navigator.

Override the application:didFinishLaunchingWithOptions: function and create a FlutterMethodChannel tied to the channel name com.example.app/device.

Next, add the iOS Swift code that uses the UIDevice API to retrieve the device model.

Understanding the Response Mechanism

The result object (Android) and completion handler (iOS) are used to communicate back to the Flutter client. There are three primary responses:

• success: Use this to return data (Strings, Maps, Lists, etc.) or null if the operation completed but has no return value.
• error: Use this for expected failures (e.g., “SENSOR_MISSING”, “PERMISSION_DENIED”). This allows you to handle platform errors gracefully in Dart using try-catch.
• notImplemented: This is a fallback to inform the Flutter client that the channel is registered, but the specific method name requested is not recognized by the native implementation.

Key Takeaways

• Channel naming: Use reverse domain notation for uniqueness
• Error handling: Always wrap calls in try-catch blocks
• Type safety: Method channels support standard Dart types (int, String, List, Map)
• Async nature: All method calls are asynchronous

Event Channels: Streaming Data

While Method Channels are great for one-off requests, Event Channels shine when you need continuous streams of data from native code to Flutter. Think sensor data, location updates, or real-time notifications.

Use Cases

• Accelerometer/Gyroscope data
• GPS location tracking
• Battery state monitoring
• Network connectivity changes
• BLE device scanning

Implementation Example: Accelerometer Stream

Let’s implement a stream that listens to accelerometer sensor updates.

Step 1: Create the Flutter platform client

The app’s State class holds the current app state. Extend that to hold the current accelerometer data.

First, construct the channel. Use an EventChannel instead of a MethodChannel, as we are listening to a stream of events.

Next, listen to the stream. We’ll start listening in initState and cancel the subscription in dispose. The receiveBroadcastStream() method returns a stream that we can listen to.

Finally, replace the build method to display the streaming data.

Step 2: Add an Android platform-specific implementation

Start by opening the Android host portion of your Flutter app in Android Studio.

Inside MainActivity.kt, implement the EventChannel.StreamHandler interface. This interface requires two methods: onListen (called when the Flutter client subscribes) and onCancel (called when the subscription ends).

Register the stream handler in configureFlutterEngine.

Implement the onListen and onCancel methods to register/unregister the Android sensor listener.

Finally, implement the SensorEventListener to send sensor data to Flutter using the eventSink.

Step 3: Add an iOS platform-specific implementation

Start by opening the iOS host portion of your Flutter app in Xcode. Open AppDelegate.swift and implement the FlutterStreamHandler protocol.

Implement onListen to start accelerometer updates using CoreMotion and send data to the eventSink.

Implement onCancel to stop updates and clean up.

Method Channel vs Event Channel

Here’s a quick comparison to help you choose the right approach:

Limitations of Platform Channels

While powerful, platform channels come with some constraints you should be aware of:

• Main Thread Blocking: Platform channels run on the platform’s main thread (UI thread). Heavy processing on the native side can block the Flutter UI. Always offload intensive tasks to background threads.
• Serialization Overhead: All data passed between Flutter and native code must be serialized and deserialized. Transferring large chunks of data (like images or large files) directly through channels can be slow.
• Limited Data Types: Only a specific set of data types (Map, List, String, int, bool, etc.) are supported by the StandardMessageCodec. Complex custom objects need to be converted to Map/JSON.
• Transaction Size Limit: Arguments codified into the envelope are subject to buffer size limits (e.g., on Android, the Binder transaction buffer is ~1MB). Sending data larger than this can crash the app with a TransactionTooLargeException.

What’s Next?

In Part 1, we’ve covered the fundamental communication mechanisms between Flutter and native platforms using Method Channels and Event Channels. You now understand how to make one-off API calls and stream continuous data from native code.

Part 2 will dive into:

• 🎨 Platform Views: Embedding native UI components
• ⚡ Best Practices: Performance optimization and security
• 🧪 Testing: How to test platform channel code

📖 Continue to Part 2: Platform Views and Advanced Patterns →

For more updates on the latest tools and technologies, follow the Simform Engineering blog.

Follow us: Twitter | LinkedIn

Unlock Native Power in Flutter [Part 1] was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Securing Distributed Systems at Scale: Advanced Token Management, Service-to-Service Auth, and Compliance Strategies

Topic Overview — Introduction

In a microservices architecture, authentication and authorization become significantly more complex than in monolithic applications. Each service could potentially implement its own authentication logic, leading to duplicated code, inconsistent security policies, and increased attack surface. As your microservices ecosystem grows from 3 to 30 services, this fragmentation becomes a critical security and maintenance liability.

Centralized authentication addresses these challenges by providing:

• Consistency: A single source of truth for authentication policies across all services
• Reduced Duplication: No need to implement authentication logic in every microservice
• Security at Scale: Centralized monitoring, key rotation, and policy enforcement
• Simplified Compliance: Unified audit trails and access control for regulatory requirements

While Single Sign-On (SSO) is one benefit, the real value lies in establishing a consistent security perimeter across distributed services. This blog explores advanced topics, including token lifecycle management, service-to-service authentication patterns, multi-tenancy considerations, security hardening techniques, and compliance monitoring strategies for production-grade systems.

Azure Entra ID (formerly Azure Active Directory) serves as our Identity Provider (IdP), offering enterprise-grade features including conditional access, threat detection, multi-factor authentication, and seamless integration with the .NET ecosystem.

Core Concepts

Authentication vs Authorization

Authentication answers “Who are you?” — verifying the identity of a user or service through credentials. Authorization answers “What can you do?” — determining permissions and access rights based on that verified identity.

In microservices, these concerns are separated:

• Authentication happens once at the entry point (API Gateway)
• Authorization happens at each service based on claims and policies

Role of an Identity Provider (IdP)

An Identity Provider like Azure Entra ID centralizes user management, credential storage, and token issuance. Instead of each microservice validating credentials, they trust tokens issued by the IdP. Popular options include Azure Entra ID, Duende IdentityServer, Auth0, and Keycloak.

JWT vs Reference Tokens

JWT (JSON Web Tokens) are self-contained tokens carrying claims in a signed payload. Advantages: stateless validation, no database lookup per request. Disadvantages: cannot be revoked before expiration, larger payload size.

Reference Tokens are opaque identifiers requiring validation against the authorization server. Advantages: instant revocation, smaller size. Disadvantages: adds latency and database load for each validation.

Best Practice: Use short-lived JWTs (5–15 minutes) for access tokens, with refresh tokens for extended sessions. For highly sensitive operations, use reference tokens or hybrid approaches.

Features

Core Capabilities

• Centralized identity management with unified user lifecycle and MFA enforcement
• JWT-based stateless authentication with refresh token rotation
• OAuth 2.0 Client Credentials flow for service-to-service communication

Advanced Security

• Multi-tenancy support with tenant isolation via claims
• Role-based and policy-based authorization with fine-grained permissions
• Automatic key rotation, token binding, and IP-based refresh token validation

Operations & Compliance

• Centralized audit logs and security event monitoring
• Compliance reporting for GDPR, HIPAA, and PCI-DSS requirements

Advanced Token Management

Short-Lived Access Tokens & Refresh Tokens

In microservices, balancing security with user experience is critical. Access tokens should be short-lived (5–15 minutes) to limit exposure if compromised. Refresh tokens enable obtaining new access tokens without re-authentication.

Architecture Pattern:

1. User authenticates → receives access token (15 min) + refresh token (7 days)
2. Client uses an access token for API calls
3. When the access token expires, the client uses the refresh token to get a new access token
4. Refresh tokens are rotated on each use (one-time use pattern)

Implementation Considerations:

• Store refresh tokens securely (encrypted, httpOnly cookies for web)
• Implement refresh token rotation to detect token theft
• Track refresh token families to invalidate chains on suspicious activity

Token Exchange Patterns

When a user calls Service A, which needs to call Service B on behalf of the user, we need a token exchange:

On-Behalf-Of (OBO) Flow:

User → API Gateway (user token) → Service A (user token) → 
Service A exchanges token → Service B (delegated token with Service B audience)

This ensures each service validates tokens meant for its audience, downstream services act on behalf of the original user, and maintain a full audit trail of user actions across services.

Implementation: Use Azure Entra ID’s OBO flow or token exchange specification (RFC 8693).

Token Revocation Challenges

JWTs are stateless — services validate them locally without contacting the IdP. This creates a revocation problem: a user logs out, but their JWT remains valid until expiration.

Solutions:

1. Short Expiration: Minimize exposure window (5–15 minutes)
2. Token Introspection: Services call IdP to validate token status (adds latency)
3. Distributed Cache: Maintain a blacklist of revoked tokens in Redis with TTL
4. Reference Tokens: Use opaque tokens requiring IdP lookup for every request
5. Hybrid Approach: JWT for most operations, introspection for sensitive actions

Recommended Pattern: Short-lived JWTs + refresh token rotation + blacklist cache for critical revocations (account compromise, privilege changes).

Service-to-Service Authentication

Why Client Credentials Flow Matters

Not all API calls originate from users. Background jobs, scheduled tasks, and inter-service communication require machine-to-machine authentication. OAuth 2.0 Client Credentials flow addresses this:

• Service authenticates using its own credentials (client ID + secret or certificate)
• Receives access token with service-specific scopes
• No user context involved

Azure Entra ID Implementation:

• Register each service as an App Registration
• Use client secrets (development) or certificate-based auth (production)
• Azure Managed Identity for services running in Azure (no credential management)

Securing gRPC and REST Microservices

Both REST and gRPC services can be secured with JWT Bearer authentication:

• REST API: Standard Authorization: Bearer <token> header
• gRPC: Token propagation via metadata headers

Key Configuration: Validate issuer, audience, and signing keys; configure HTTPS/TLS for all communication; implement retry logic with token refresh.

API Gateway Pattern

The API Gateway acts as the authentication enforcement point:

1. Receives incoming requests with user credentials or tokens
2. Validates authentication against Azure Entra ID
3. Enforces authorization policies (rate limiting, IP restrictions)
4. Propagates tokens downstream to microservices
5. Handles token refresh transparently

Benefits: Microservices don’t handle authentication, only authorization; centralized security policy enforcement; token transformation (user token → service-specific tokens).

Example: Service A → Service B with Delegated Token

Scenario: Order Service needs to verify product availability from Product Service

1. User calls Order Service with user access token
2. Order Service validates token (user is authenticated)
3. Order Service exchanges token for Product Service-specific token (OBO flow)
4. Order Service calls Product Service with new token
5. Product Service validates token and processes request

This maintains user context throughout the call chain while ensuring each service only accepts tokens meant for its audience.

Multi-Tenancy & Claims Management

Handling Multiple Tenants

In SaaS applications, a single deployment serves multiple customers (tenants). Centralized auth must enforce tenant isolation:

Strategies:

1. Separate Audiences: Each tenant has unique audience claim in token
2. Tenant Claim: Include tenant_id claim in all tokens
3. Claims Transformation Middleware: Inject tenant context early in request pipeline

Implementation Pattern:

// Extract tenant from token claims
var tenantId = user.FindFirst("tenant_id")?.Value;

// Filter data by tenant
var products = await _context.Products
    .Where(p => p.TenantId == tenantId)
    .ToListAsync();

Role-Based vs Policy-Based Authorization

Role-Based Access Control (RBAC):

• Simple: Users have roles (Admin, User, Manager)
• Roles map to permissions
• Good for straightforward hierarchies

[Authorize(Roles = "Admin,Manager")]
public IActionResult DeleteProduct(int id) { }

Policy-Based Authorization:

• Flexible: Policies evaluate multiple requirements
• Combine roles, claims, custom logic
• Better for complex scenarios

[Authorize(Policy = "CanManageProducts")]
public IActionResult UpdateProduct(Product product) { }

// Policy definition
services.AddAuthorization(options =>
{
    options.AddPolicy("CanManageProducts", policy =>
        policy.RequireAssertion(context =>
            context.User.HasClaim("role", "Admin") ||
            (context.User.HasClaim("role", "Manager") && 
             context.User.HasClaim("department", "Sales"))));
});

Scope-Based Service Management

OAuth 2.0 scopes define what operations a token permits. In microservices:

• User tokens: products.read, products.write, orders.read, orders.write
• Service tokens: products-service.all, orders-service.all

Best Practice: Assign minimum required scopes. A read-only client should never receive write scopes.

[Authorize(Policy = "RequireProductWriteScope")]
public IActionResult CreateProduct([FromBody] Product product)
{
    // Only tokens with "products.write" scope can access
}

// Policy checks scope
options.AddPolicy("RequireProductWriteScope", policy =>
    policy.RequireClaim("scope", "products.write"));

Security Hardening

Rotating Signing Keys

JWT tokens are signed with cryptographic keys. Compromised keys allow attackers to forge valid tokens. Automatic key rotation mitigates this risk:

Azure Entra ID: Automatically rotates signing keys every 90 days, publishes multiple keys simultaneously in JWKS endpoint, and services validate against any current key.

Implementation:

services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://login.microsoftonline.com/{tenant-id}";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
        };
        options.RefreshOnIssuerKeyNotFound = true; // Auto-refresh on key rollover
    });

Securing Refresh Tokens

Refresh tokens are long-lived (days to months), making them high-value targets:

IP/Device Binding:

// Store IP and device fingerprint with refresh token
var refreshToken = new RefreshToken
{
    Token = GenerateSecureToken(),
    UserId = userId,
    IpAddress = HttpContext.Connection.RemoteIpAddress.ToString(),
    DeviceFingerprint = ComputeDeviceFingerprint(userAgent, acceptLanguage),
    ExpiresAt = DateTime.UtcNow.AddDays(7)
};

// Validate on refresh
if (storedToken.IpAddress != currentIp || 
    storedToken.DeviceFingerprint != currentFingerprint)
{
    await RevokeTokenFamily(storedToken.FamilyId);
    await AlertSecurityTeam(userId, "Refresh token used from different device");
    throw new SecurityException("Token validation failed");
}

Rotation Strategies: One-time use (invalidate after use), token families (track chains, revoke on anomaly), sliding expiration (extend on use, up to maximum lifetime).

Protecting Against Replay Attacks

In distributed systems, an attacker capturing a valid token could replay it:

Mitigation Strategies:

1. Short token lifetime: Minimize replay window
2. HTTPS everywhere: Prevent token capture
3. Token binding: Cryptographically bind token to TLS connection (RFC 8473)
4. Nonce/JTI claims: Track used token IDs in distributed cache
5. Time-based validation: Reject tokens outside time window (nbf, exp claims)

Implementation Example:

public async Task<bool> ValidateTokenReplayAsync(string jti, DateTime exp)
{
    var cacheKey = $"used_token:{jti}";
    if (await _cache.ExistsAsync(cacheKey))
        return false;
    
    var ttl = exp - DateTime.UtcNow;
    await _cache.SetAsync(cacheKey, "1", ttl);
    return true;
}

Advantages

Security & Operations

• Single point of control reduces attack surface and enables rapid token revocation
• Consistent security policies across all services with centralized audit logs
• Stateless JWT validation enables horizontal scaling without database dependencies

Development & Business

• Reduced code duplication and faster development cycles
• Lower TCO through simplified compliance and maintenance
• Better user experience with SSO and seamless cross-service navigation

Use Cases

Enterprise SaaS & Regulated Industries

Multi-tenant SaaS platforms (e-commerce, CRM, project management) benefit from tenant isolation and SSO integration. Financial services and healthcare systems leverage centralized auth for unified audit trails, regulatory compliance (PCI-DSS, HIPAA), and comprehensive access logging across microservices.

Monitoring & Compliance

Logging Failed Authentication Attempts

Centralized authentication creates a single point for security monitoring:

Key Metrics to Track:

• Failed login attempts by user/IP
• Unusual login locations or times
• Token validation failures
• Refresh token reuse attempts
• Service-to-service authentication failures

Implementation with Application Insights:

JwtBearerEvents.OnAuthenticationFailed = context =>
{
    _telemetry.TrackEvent("AuthenticationFailed", new Dictionary<string, string>
    {
        { "Reason", context.Exception.Message },
        { "IP", context.HttpContext.Connection.RemoteIpAddress.ToString() },
        { "Endpoint", context.Request.Path },
        { "Service", Environment.GetEnvironmentVariable("SERVICE_NAME") }
    });
    return Task.CompletedTask;
};

Security Event Monitoring

Anomaly Detection Patterns:

1. Velocity Checks: >10 failed logins in 5 minutes
2. Impossible Travel: Login from New York, then Tokyo 1 hour later
3. Token Pattern Abuse: Same refresh token used from multiple IPs
4. Privilege Escalation: User role changes followed by sensitive operations

Compliance (GDPR, HIPAA, PCI)

Centralized authentication simplifies compliance:

GDPR Requirements: Right to Access (single query returns all auth events), Right to Erasure (revoke all tokens in one place), Data Minimization (tokens contain only necessary claims), Audit Trail (comprehensive logs).

HIPAA Requirements: Access Controls (centralized enforcement), Audit Logs (detailed PHI access logging), Automatic Logoff (centralized session timeout), Person Authentication (strong auth mechanisms).

PCI-DSS Requirements: Unique ID for each person (IdP enforced), Track and monitor all access (centralized logs), Password policies (centralized enforcement).

Auditing Access Across Services

Distributed Tracing with Correlation IDs:

public class CorrelationIdMiddleware
{
    public async Task InvokeAsync(HttpContext context)
    {
        var correlationId = context.Request.Headers["X-Correlation-ID"].FirstOrDefault()
            ?? Guid.NewGuid().ToString();
        
        context.Items["CorrelationId"] = correlationId;
        context.Response.Headers.Add("X-Correlation-ID", correlationId);
        
        _logger.LogInformation("User {UserId} accessed {Endpoint} [CorrelationId: {CorrelationId}]",
            context.User.Identity?.Name, context.Request.Path, correlationId);
        
        await _next(context);
    }
}

This enables tracing a user’s complete journey through the system for security investigations and compliance audits.

Conclusion

Building a centralized authentication system for .NET microservices is a comprehensive security architecture covering token lifecycle management, service-to-service communication, multi-tenancy, and regulatory compliance.

Key Takeaways:

1. Strong Foundations: Azure Entra ID provides enterprise features, but understanding JWT vs reference tokens and token exchange patterns is crucial for production.
2. Service-to-Service Auth: Client credentials flow and managed identities enable secure microservice communication without user context.
3. Layered Security: Short-lived tokens, refresh rotation, key rotation, and distributed caching create defense in depth.
4. Compliance by Design: Centralized authentication simplifies GDPR, HIPAA, and PCI-DSS implementation with built-in audit trails and access controls.

Investing in robust centralized authentication is fundamental to building secure, scalable, and compliant distributed systems. The patterns outlined here provide a roadmap that scales from startups to enterprise deployments.

References & Further Reading

• Microsoft Identity Platform Documentation
• OAuth 2.0 On-Behalf-Of Flow
• .NET Microservices Security
• JWT Best Practices
• OpenID Connect Specification

Building a Centralized Authentication System for .NET Microservices with Azure Entra ID was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Vue 3 is fast. Exceptionally fast. But modern applications — complex dashboards, deeply nested components, large datasets, and aggressive API-driven updates — can push even Vue’s reactivity system into uncomfortable territory.

Over the last few years, I’ve seen otherwise clean applications develop slow renders, input lag, frame drops, and mysterious “Vue is slow” complaints that had nothing to do with Vue itself.

This guide breaks down the real performance issues senior developers run into, why they occur, and how to fix them. To ground this in reality, we’ll use a sample application: a property comparison dashboard displaying hundreds of items with filters, calculations, and nested data.

1. Over-Reactive Components

When everything reacts to everything

Vue’s reactivity system is incredibly capable, but it only tracks what you tell it to. If you bind large reactive objects directly to your components — especially full API responses or entire Pinia store states — Vue will re-render more aggressively than intended.

Why this hurts

• Large reactive dependencies trigger updates even for small property changes.
• Expensive component trees re-render unnecessarily.
• Deep-nested components inherit all reactivity from parent objects, even when they don’t need it.

Real impact in our dashboard

A single filter change causes all 200+ cards to update because every card depends on the same large reactive state object.
This can create 300–500ms frame delays on mid-range devices.

Fix

• Destructure stores and reactive objects to isolate the smallest reactive units.
• Use computed wrappers around small slices of state.
• Mark static data with markRaw() or freeze it.
• Apply v-once for sections that never change.

2. Computed Properties That Recompute Too Often

The silent recalculation problem

Computed properties are cached, but only until one of their dependencies changes. If the dependency happens to be a large reactive source, then even minor changes invalidate the cache.

Why this hurts

A single reactive update — unrelated to the computed property’s purpose can force expensive operations to run repeatedly.

Real impact in our dashboard

“Y-Total” calculations depend on a large list of property details. Typing a character into a search box invalidates the computed and recalculates heavy logic across 200 items. Multiply that across multiple filters, and your UI starts lagging.

Fix

• Narrow dependency tracking: expose only required fields through computed refs.
• Break monolithic computed chains into smaller, independent segments.
• Memoize stable derived values.
• Pre-calculate static parts at API ingestion time.

3. v-for + Reactive Props = Unnecessary Re-Renders

Where performance dies one row at a time

v-for is efficient, but it still re-renders children when parent props change.

Why this hurts

• Child components receive reactive props.
• Parent updates — even unrelated ones — cascade through every child.
• Each child may run its own computed properties, watchers, or lifecycle logic.

Real impact in our dashboard

Scrolling becomes jittery, and typing filters have noticeable lag. Chrome DevTools shows frame rates dipping below 40 FPS because Vue is forced to update the entire list on every minor change.

Fix

• Always use stable keys.
• Mark static sections non-reactive.
• Use v-memo (Vue 3.4+) to skip unnecessary updates.
• Flatten overly nested structures where possible.

4. Watchers That Shouldn’t Exist

Accidental complexity through observation

Watchers often start as convenience utilities but quietly accumulate into reactive chains that trigger excessive updates or duplicate calls.

Why this hurts

• Watchers re-run on every dependency change.
• One watcher triggers another.
• Developers often attach watchers to entire objects instead of specific fields.

Real impact in our dashboard

One filter change fires:
→ multiple watchers
→ computed recalculations
→ downstream watchers
→ API calls
→ even more watchers

What should be a single update becomes a storm of cascading reactivity.

Fix

• Replace watchers with computed properties when possible.
• Avoid watchEffect unless necessary—prefer explicit watchers.
• Add flush: 'post' to avoid chained reruns.
• Debounce watchers that trigger I/O.

5. Deeply Nested Props: The Cascade of Doom

When one prop update ripples across the entire component tree

Passing large reactive objects four or five levels deep spreads reactivity everywhere.

Why this hurts

• A single parent update invalidates the entire tree.
• Child components recompute derived states that don’t need refreshing.
• Memoization becomes ineffective because dependencies appear unstable.

Real impact in our dashboard

ComparisonContainer → ComparisonList → ItemCard → MetricRow
One parent update forces every metric to recompute—even if only one item changed.

Fix

• Use provide/inject for stable data.
• Pass primitives or readonly slices instead of entire objects.
• Move shared state into composables or Pinia modules.
• Avoid deeply nested props when not necessary.

6. Overly Reactive Stores

When a pinia store becomes a junk drawer

Pinia encourages global reactivity, which is powerful but dangerous if used without boundaries.

Why this hurts

If you store everything in a single reactive store — user info, filters, lists, pagination, UI flags — then any update will ripple across the entire application.

Real impact in our dashboard

Pagination changes cause:
→ list recomputation
→ card re-renders
→ header updates
→ UI flashes
Even though pagination isn’t related to any of those components.

Fix

• Split stores by domain and responsibility.
• Store static data using markRaw() or non-reactive structures.
• Avoid unnecessary $subscribe calls.
• Use getters for expensive derived data — they are cached by default.

7. Template-Level Anti-Patterns

The quietest but most common source of performance issues

Templates re-evaluate expressions on every render. Recalculating heavy lists inside the template is one of the quickest ways to hurt performance.

Why this hurts

• Any render event recalculates inline functions, filters, mappings, or reductions.
• Inline objects cause Vue to think props have changed.
• Complex logic in templates makes re-renders extremely expensive.

Real impact in our dashboard

A card template that runs multiple array filters or mappings recalculates all of them, even on unrelated UI changes, such as a tooltip appearing.

Fix

• Move every piece of logic out of the template and into computed properties.
• Avoid inline object or function instantiations.
• Preprocess data in the parent component if needed.

Why This Matters

The performance issues above rarely appear in isolation. In real dashboards and complex apps, they stack. One inefficient watcher plus a heavy computed property plus deeply nested reactive props can lead to cascading performance problems that feel unsolvable.

Understanding Vue’s reactivity at a structural level and not just at the API level is what separates a smooth application from a sluggish one.

For more updates on the latest tools and technologies, follow the Simform Engineering blog.

Follow us: Twitter | LinkedIn

7 Vue 3 Performance Pitfalls That Quietly Derail Your App was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

When we build an Android app using Firebase, we trust that only our actual app will communicate with Firebase services, such as Firestore, Realtime Database, or Cloud Storage. But in reality, anyone can extract your Firebase keys and try to access your backend using fake or modified apps.

This is where Firebase App Check comes in.

In this blog, we’ll understand:

• What is Firebase App Check?
• How App Check Works?
• How to integrate App Check in an Android app?
• App Check Token Expiry
• Common Issues That Can Break the Firebase App Check
• Using App Check During Development and Debugging
• App Check request metrics
• How it works with Firebase services: Demo use case

What Is Firebase App Check?

Firebase App Check is a security layer that ensures only your real, untampered app can access Firebase services.

Without App Check:

• Fake or cloned apps can directly access your Firestore
• Automated scripts can abuse your APIs
• Your Firebase quota can be drained
• Your billing costs can unexpectedly increase

With App Check:

• Firebase verifies your app before responding to requests
• Only trusted and valid apps are allowed access
• Modified, fake, or unauthorized apps are blocked automatically
• Your data, quota, and billing stay protected

Think of App Check as an identity card your app must show before talking to Firebase.

How App Check Works:

Firebase App Check doesn’t just blindly trust your app. Instead, it uses a trusted system called an attestation provider to verify that your app is genuine and hasn’t been tampered with. This verification process addresses three key questions: Is the app genuine, has it been modified, and was it installed from a trusted source? By checking these things, Firebase ensures that only authentic apps can communicate with its services.

On Android, the attestation provider is the Play Integrity API. This system helps confirm that user actions and server requests are coming from your real app, installed through Google Play, and running on an authentic, certified Android device. In other words, it makes sure the app interacting with Firebase is exactly the app you built, and nothing else.

How App Check Verifies Your App

1. Your app asks the Play Integrity API for an attestation token
2. Play Integrity checks the app’s integrity
3. A token is returned to Firebase
4. Firebase verifies the token
5. If valid → access granted
   If invalid → request blocked

The best part is that all of this happens seamlessly in the background. Users won’t notice anything, but Firebase quietly ensures that every request comes from a secure, real, and untampered version of your app. This adds an invisible layer of protection, keeping your data, APIs, and backend safe from misuse.

How to integrate App Check in an Android app?

Prerequisites: Ensure the following requirements are met before you begin:

• Firebase project is created
• Android app has been added to Firebase
• google-services.json is properly configured
• Firebase SDK is already added

Step 1: Add App Check Dependency

In your app-level build.gradle File:

dependencies {
    implementation "com.google.firebase:firebase-appcheck-playintegrity:LATEST_VERSION_HERE"
}

Step 2: Enable App Check in Your App

In your MainActivity or Application Class:

val firebaseAppCheck = FirebaseAppCheck.getInstance()
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance()
)

That’s it! Now App Check is active in your Android app.

Step 3: Enable App Check in Firebase Console

1. Open Firebase Console
2. Go to Project Settings
3. Open App Check
4. Select your Android app
5. Enable App Check
6. Turn on enforcement for:

• Firestore
• Realtime Database
• Cloud Storage

Once App Check is enabled:

• Firebase services will expect a valid App Check token
• Requests without valid tokens will be rejected

App Check Token Expiry:

Once Firebase App Check has verified that your app is genuine, it provides your app with a temporary token. This token acts like a short-lived pass, proving to Firebase that your app is trusted while it communicates with the backend. Because these tokens are temporary, they eventually expire, but the good news is that the Firebase SDK takes care of refreshing them automatically. Your app can continue to interact with Firebase services without interruption, and most of the time, you don’t even have to think about it.

In some cases, such as debugging or making custom backend calls, you might want to manually fetch a new token. This can be done using a simple call like firebaseAppCheck.getToken(forceRefresh: true). The forceRefreshparameter determines whether Firebase should return a cached token if one exists or fetch a brand-new token from the server. Setting it to true forces a fresh token, while false allows Firebase to return a valid cached token if available. This flexibility can be very useful when testing or handling special scenarios in your app.

firebaseAppCheck.getToken(forceRefresh: true)
.addOnSuccessListener(token -> {
    // Use token if needed
})
.addOnFailureListener(e -> {
    // Handle error
})

Common Issues That Can Break the Firebase App Check:

Even though Firebase App Check works quietly in the background to protect your app, sometimes things can go wrong. Knowing these common issues can help you fix problems quickly and keep your app secure:

• App Check token not sent — Firebase didn’t receive the verification token from your app.
• App not installed from the Play Store — App Check expects the app to come from a trusted source like Google Play.
• App Check is not enabled in the Firebase Console — App Check must be turned on for your project to work.
• Play Integrity API is not properly configured — The system that checks your app’s authenticity isn’t set up correctly.

Using App Check During Development and Debugging:

While Play Integrity is the provider used in production to ensure your app is genuine, development and debugging require a slightly different approach. During development, your app may not be installed from the Play Store, or you might be testing on devices that aren’t certified. In these cases, Firebase provides a Debug App Check Provider that allows you to test and develop your app without running into verification issues.

Using the debug provider is simple. You can set it up with theDebugAppCheckProviderFactory which gives your app a debug token. This token acts like a temporary pass for your app during development, letting you test App Check functionality without requiring Play Integrity. Once your app is ready for production, you can switch back to Play Integrity to ensure full security for your real users.

Add a dependency in your app-level build.gradle file:

dependencies {
    implementation "com.google.firebase:firebase-appcheck-debug:LATEST_VERSION_HERE"
}

In your MainActivity or Application Class:

val firebaseAppCheck = FirebaseAppCheck.getInstance()
firebaseAppCheck.installAppCheckProviderFactory(
    DebugAppCheckProviderFactory.getInstance()
)

Now launch the app and check Logcat to get the debug token.

Add a debug token to App Check on the Firebase console to avoid blocking your test builds.

App Check request metrics:

• App Check metrics show how many requests are coming from valid vs invalid apps.
• You can see trends like:
• Spike in invalid requests → possible attack or misuse
• Drop in valid requests → maybe legitimate users are facing issues

Demo Use Case Of Firestore: App Check-in Action

// Add collection to Firestore
val db = FirebaseFirestore.getInstance()

val data = hashMapOf(
    "text" to "Hi from Firestore App Check demo"
)

db.collection("messages")
    .document("hello")
    .set(data)
    .addOnSuccessListener {
        Log.d("DEMO", "Document written successfully")
    }
    .addOnFailureListener { e ->
        Log.e("DEMO", "Firestore write failed", e)
    }

Scenario 1: Legit App

• Installed from the Play Store
• Valid App Check token
• Firestore access allowed

Scenario 2: Tampered App

• Modified APK
• Invalid token
• Firestore access blocked

Conclusion:

Firebase App Check is not only simple to set up but also extremely effective at protecting your app and backend. Without it, your Firebase services are exposed, leaving your data vulnerable to fake apps, automated scripts, and potential misuse that can increase your billing unexpectedly.

By adding just a few lines of code, you can secure your Firebase data, block unauthorized access, and prevent abuse, all without interrupting your users’ experience. App Check works quietly in the background, giving you peace of mind that only your real, trusted app can communicate with Firebase, keeping both your users and your backend safe.

Official Documentation
Firebase App Check: https://firebase.google.com/docs/app-check

Happy Learning!

If this guide helped you, show some love with 👏 and share it with your friends. Let’s make learning Firebase fun and easy for everyone. Thanks for reading!

Firebase App Check with Play Integrity API in Android was originally published in Simform Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.