Forem: horus he

From Prompt to Production: A Practical Architecture for Chat-Based AI Image Generation

horus he — Tue, 03 Mar 2026 09:59:16 +0000

When we started building Banana AI, we faced a familiar challenge. Users wanted to generate images by describing what they needed, but most existing AI image tools required learning prompt syntax, navigating complex interfaces, or tolerating long waits with no feedback.

The solution we built centers on a chat-based interface where users describe their needs in plain language, refine through conversation, and receive production-ready images. This approach works well for our users, but getting there required solving several architectural problems around async processing, state management, and cost optimization.

This article walks through the practical decisions we made and the patterns that have worked in production of the ai image generator.

The Core Problem: AI Generation Is Slow

AI image generation takes anywhere from 2 to 20 seconds depending on the model and resolution. That's too long for a synchronous HTTP request. Users expect responsive interfaces, and holding a connection open for 20 seconds creates poor experiences and infrastructure problems.

The standard solution is async processing: accept a request, queue it, process it in the background, and notify the user when complete. But implementing this well requires thinking through several connected systems.

Architecture Overview

Our stack runs on Cloudflare's edge infrastructure:

Next.js 15 with App Router for the frontend
Cloudflare Workers for serverless compute
Cloudflare D1 for relational data (sessions, messages, user state)
Cloudflare Durable Objects for real-time prediction state
Cloudflare R2 for image storage
Cloudflare Queues for async job processing

The flow looks like this:

User sends a message through the chat interface
Frontend posts to our API as FormData (supports image uploads)
API authenticates, creates or resumes a session, and queues the generation job
Worker picks up the job, calls the AI model API, and streams progress events
Frontend receives real-time updates via polling
When complete, the image uploads to R2 and the user sees the result

This architecture keeps the frontend responsive while handling long-running AI tasks in the background.

State Management: Sessions and Messages

Chat-based generation differs from single-prompt tools because context matters. A user might say "make it darker," and the system needs to understand what "it" refers to.

We model this with two core entities:

Sessions

A session represents a conversation. It tracks:

User ID (if authenticated)
Current model selection (users can switch models mid-conversation)
Creation timestamp and last activity
Soft delete flag for user-initiated cleanup

// Simplified schema
const chatSessions = sqliteTable('chat_sessions', {
  uuid: text('uuid').primaryKey(),
  userId: text('user_id').notNull(),
  modelId: text('model_id').notNull(),
  createdAt: integer('created_at').notNull(),
  updatedAt: integer('updated_at').notNull(),
  deletedAt: integer('deleted_at'),
});

Messages

Each message belongs to a session and carries:

Role: user or assistant
Content: text, plus optional media attachments
Generation parameters: model used, aspect ratio, resolution
Status: pending, processing, completed, failed

The message history provides context for future generations. When a user says "make the background blue," we include the relevant conversation context when calling the AI model.

Credit System: Reservations and Confirmations

We use a credit-based pricing model. Different models cost different amounts (Nano Banana costs 5 credits, Nano Banana Pro costs 10-20 credits depending on resolution).

The challenge is handling credits atomically when AI generation can fail at multiple points:

User submits request
We reserve credits (deduct from balance but mark as "pending")
AI generation runs
If successful: confirm the reservation (credits become spent)
If failed: release the reservation (credits return to balance)

This reservation pattern prevents the worst case: charging users for failed generations.

We implement this with Durable Objects, which provide strongly consistent state. Each prediction gets its own Durable Object instance that tracks:

interface PredictionState {
  predictionId: string;
  userId: string;
  creditsReserved: number;
  status: 'pending' | 'processing' | 'succeeded' | 'failed';
  createdAt: number;
  completedAt?: number;
  resultUrl?: string;
  error?: string;
}

The Durable Object handles the state transitions and ensures credits are either confirmed or released exactly once.

Streaming Progress: Keeping Users Informed

One advantage of chat-based interfaces is that users expect conversational updates. We leverage this by streaming progress events during generation:

understanding: Processing the user's request
refining_prompt: Preparing the optimized prompt
generating: AI model is creating the image
uploading: Saving the result to storage
finalizing: Updating session state

The frontend polls a /prediction/[id] endpoint that returns the current state from the Durable Object. This creates a simple but effective progress indicator.

For longer generations (Nano Banana Pro includes a "thinking" stage that analyzes composition before generating), this feedback is essential. Users can see that progress is happening rather than staring at a static loading spinner.

Model Selection: Flexibility vs. Complexity

We support three AI models with different characteristics:

Model	Speed	Resolution	Cost	Best For
Nano Banana	2-5s	1K	5 credits	Quick drafts
Nano Banana 2	4-6s	Up to 4K	7-14 credits	Balanced work
Nano Banana Pro	10-20s	Up to 4K	10-20 credits	Maximum quality

Users can switch models mid-conversation. This creates flexibility (draft with a fast model, refine with a quality model) but adds complexity to the state management.

We store model selection at the session level, but each message records which model actually produced it. This means a single conversation can include generations from multiple models, and users can see which model produced each result.

Webhook Handling: External Service Integration

We use Replicate as one of our AI model providers. Replicate processes images asynchronously and sends a webhook when complete.

Handling webhooks reliably requires addressing several edge cases:

Idempotency

Webhooks can arrive multiple times. Our handler checks if we've already processed this prediction ID before taking action:

// Simplified handler
export async function POST(request: Request) {
  const { id, status, output } = await request.json();

  // Get the Durable Object for this prediction
  const stub = getPredictionDO(id);
  const state = await stub.getState();

  // Already processed?
  if (state.status !== 'pending' && state.status !== 'processing') {
    return new Response('Already processed', { status: 200 });
  }

  // Update state and confirm or release credits
  if (status === 'succeeded') {
    await stub.markCompleted(output);
    await confirmCredits(state.userId, state.creditsReserved);
  } else {
    await stub.markFailed();
    await releaseCredits(state.userId, state.creditsReserved);
  }

  return new Response('OK', { status: 200 });
}

Timeout Handling

Sometimes webhooks never arrive. We implement a timeout mechanism that checks for stale predictions and either retries or releases reserved credits.

State Recovery

If our service restarts mid-generation, we need to recover. Durable Objects persist their state, so when the service comes back online, we can query for predictions that were in-progress and either resume waiting or initiate recovery.

Cost Optimization: Learning from Production Data

After running this system in production, we've identified several patterns that reduce costs:

Model Routing

Simple prompts often don't need the highest-quality model. We've experimented with automatic model selection based on prompt complexity, though currently we let users choose explicitly. The data suggests we could route 30-40% of requests to cheaper models without noticeable quality impact.

Resolution Defaults

Most users don't need 4K output. We default to 2K, which costs fewer credits and generates faster. Users can upgrade resolution for specific images where it matters.

Caching Similar Requests

Users often regenerate with minor variations ("same but with different text"). We've explored caching intermediate representations, though the complexity hasn't been worth it for our scale yet.

What We'd Do Differently

Building this system taught us a few lessons:

Polling vs. WebSockets

We chose polling for simplicity. It works adequately, but for real-time collaboration features, WebSockets would provide a better experience. The infrastructure complexity is the trade-off.

Queue Visibility

Cloudflare Queues are reliable but debugging failed jobs can be challenging. We added extensive logging to the queue consumer, which helps but isn't as nice as a proper dead-letter queue interface.

Rate Limiting at the Edge

We implement rate limiting with Durable Objects, which works but adds latency to every request. A dedicated rate-limiting service at the edge would be cleaner.

Conclusion

Chat-based AI image generation requires thinking beyond the AI model itself. The surrounding architecture (async processing, state management, credit handling, progress streaming) determines whether the user experience feels smooth or frustrating.

Our approach prioritizes:

Responsiveness: The UI never blocks on long-running AI tasks
Transparency: Users see progress and understand what's happening
Reliability: Credits are handled atomically; failures don't charge users
Flexibility: Users can switch models and refine through conversation

This architecture has handled thousands of generations with consistent uptime. You can see it in action at Banana AI.

If you're building similar systems, I'm interested in hearing about your architectural decisions. What trade-offs have you made between simplicity and features? How do you handle the async nature of AI generation?

Technical Stack Summary

Framework: Next.js 15 with App Router
Runtime: Cloudflare Workers via OpenNext
Database: Cloudflare D1 (SQLite at the edge)
State: Cloudflare Durable Objects
Storage: Cloudflare R2
Queue: Cloudflare Queues
AI Providers: Google Gemini models via Replicate
Authentication: NextAuth v5 with Google OAuth

Tags: #javascript #typescript #ai #cloudflare #architecture #webdev

How I Handle 15-Second AI Tasks Without Losing 87% of Users

horus he — Sat, 13 Sep 2025 01:49:14 +0000

Last week, I watched our analytics dashboard in horror. 87% of users were abandoning our AI jersey designer during the generation process. The culprit? A spinning loader that lasted 15-20 seconds with zero feedback.

Sound familiar? If you're building AI features, you've probably faced this exact problem. Here's how I transformed those painful wait times into a smooth, engaging experience that actually keeps users around.

The $10,000 Problem

Our AI jersey generator was bleeding users and money. Every abandoned generation meant:

Wasted AI compute costs ($0.04 per failed attempt)
Lost conversion opportunity ($12 average order value)
Negative brand perception (users thought the app was broken)

After losing nearly $10,000 in potential revenue in just one month, I knew we needed a radical rethink.

The Magic: Async Processing + Smart Polling

Instead of making users wait, I split the process into three phases:

// 1. Instant submission - returns in 200ms
async function submitDesign(request: Request) {
  const validation = validateInput(request.body);
  if (!validation.success) return { error: validation.error };

  // Create async task and return immediately
  const predictionId = await createPrediction({
    prompt: request.body.prompt,
    webhookUrl: `${API_URL}/webhooks/ai-complete`
  });

  // Store initial status
  await kvStore.put(`prediction:${predictionId}`, {
    status: 'starting',
    createdAt: Date.now()
  });

  return { 
    predictionId, 
    message: 'Your design is being created!' 
  };
}

The Frontend Magic

Here's where it gets interesting. Instead of a boring spinner, users see real progress:

function JerseyGenerator() {
  const [status, setStatus] = useState('idle');
  const [progress, setProgress] = useState(0);

  async function pollStatus(predictionId: string) {
    const delays = [1000, 2000, 5000, 10000]; // Progressive delays
    let attempt = 0;

    while (attempt < 60) {
      const result = await fetch(`/api/status/${predictionId}`);
      const data = await result.json();

      if (data.status === 'processing') {
        setProgress(Math.min(attempt * 10, 90)); // Visual progress
        setStatus('AI is crafting your unique design...');
      } else if (data.status === 'succeeded') {
        setProgress(100);
        displayResult(data.imageUrl);
        return;
      }

      const delay = delays[Math.min(attempt, delays.length - 1)];
      await sleep(delay);
      attempt++;
    }
  }

  return (
    <div>
      {status !== 'idle' && (
        <ProgressBar value={progress} message={status} />
      )}
    </div>
  );
}

The Webhook Secret Sauce

When the AI completes, a webhook instantly updates the status:

async function handleWebhook(request: Request) {
  const event = await request.json();

  // Verify webhook signature (crucial for security!)
  if (!verifySignature(request)) {
    return new Response('Unauthorized', { status: 401 });
  }

  if (event.status === 'succeeded') {
    // Download and store the result
    const imageUrl = await storeImage(event.output[0]);

    // Update status for frontend polling
    await kvStore.put(`prediction:${event.id}`, {
      status: 'succeeded',
      imageUrl,
      completedAt: Date.now()
    });
  }

  return new Response('OK');
}

Real Production Results

After implementing this architecture at AI Jersey Design:

📊 User Engagement:

Abandonment rate: 87% → 12%
Average session duration: +340%
Conversion rate: 2.3% → 8.7%

⚡ Performance:

Initial response: 200ms (was 15+ seconds)
P95 completion time: 8 seconds
Successful generations: 99.2%

💰 Business Impact:

Revenue increase: +278%
Support tickets: -65%
AI cost per conversion: -40%

The Gotchas Nobody Talks About

Webhook Retries: AI services retry failed webhooks. Without idempotency, you'll process duplicates.
Status Expiration: Set TTLs on your KV storage. I learned this after accumulating 100GB of orphaned predictions.
Progressive Delays: Don't poll every second! Use exponential backoff to save bandwidth.
Error Recovery: When webhooks fail, have a backup polling mechanism to check AI service directly.

Quick Implementation Checklist

If you're implementing this pattern, here's your checklist:

[ ] Non-blocking API endpoint that returns immediately
[ ] KV storage for status with automatic TTL
[ ] Webhook endpoint with signature verification
[ ] Frontend polling with progressive delays
[ ] Progress indicators beyond just spinners
[ ] Error handling for each failure mode
[ ] Monitoring for webhook delivery rates

The Architecture That Scales

This pattern has handled:

Peak load: 500+ concurrent generations
Daily volume: 10,000+ images
Global users: <50ms status checks worldwide
Zero downtime: During 3 months of production

Your Turn

What's your approach to handling long-running tasks? Have you tried async patterns in your AI apps? I'd love to hear what worked (or didn't) for you.

Drop a comment with your experience, or share your horror stories of users abandoning your AI features. Let's solve this together!

Found this helpful? Follow me for more real-world AI architecture patterns. Next week: How I cut our AI costs by 73% without sacrificing quality.

Why I Ditched Redis for Cloudflare Durable Objects in My Rate Limiter？

horus he — Sat, 30 Aug 2025 03:26:00 +0000

Have you ever watched your serverless application crumble under unexpected traffic? Last month, our AI-powered image generator went viral on social media, and within hours we were drowning in requests. Our traditional rate limiting setup couldn't keep up with the distributed load across Cloudflare's edge network.

This experience taught me that rate limiting in serverless environments requires a fundamentally different approach. Here's how I built a production-ready rate limiter using Cloudflare Durable Objects that handles thousands of concurrent requests while running at the edge.

The Traditional Approach Falls Short

Most developers reach for Redis when implementing rate limiting. It's fast, reliable, and has excellent libraries. But in a serverless environment, especially one distributed across multiple edge locations, Redis introduces several challenges:

Latency Issues: Every rate limit check requires a round trip to your Redis instance, adding 50-200ms of latency depending on geographic distance.

Single Point of Failure: Your entire rate limiting system depends on Redis availability. If Redis goes down, you either block all traffic or allow unlimited requests.

Cold Start Problems: Serverless functions need to establish Redis connections on cold starts, further increasing response times.

Geographic Complexity: Running Redis replicas across multiple regions for low latency gets expensive quickly and introduces data consistency challenges.

Enter Durable Objects

Cloudflare Durable Objects solve these problems elegantly by providing stateful compute primitives that run directly at the edge. Each Durable Object instance maintains its own persistent state and can handle concurrent requests while ensuring strong consistency.

Think of Durable Objects as tiny, persistent computers that live at Cloudflare's edge locations. They wake up when needed, maintain state between requests, and automatically migrate to follow your traffic patterns.

Building the Rate Limiter

Here's the complete implementation of a production-ready rate limiter using Durable Objects:

import { DurableObject } from "cloudflare:workers";

interface ThrottleState {
  limitTimes: number;
  limitEndTimeMs: number;
  executedTimesCurrentCycle: number;
  currentCycle: number;
}

export interface TryApplyOptions {
  limitCycleExecutionTimes: number;
  limitCycleTimeMs: number;
}

export interface ThrottlerResponse {
  granted: boolean;
  state: ThrottleState;
}

export class ThrottlerDO extends DurableObject {
  limitCycleExecutionTimes = 10; // Default: 10 requests per cycle
  limitCycleTimeMs = 10 * 60 * 1000; // Default: 10 minutes

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
  }

  async getState(): Promise<ThrottlerResponse> {
    let state = await this.ctx.storage.get('throttle_state') as ThrottleState | null;

    if (!state) {
      state = {
        limitTimes: 0,
        limitEndTimeMs: 0,
        executedTimesCurrentCycle: 0,
        currentCycle: 0,
      };
    }

    const currentMs = Date.now();

    // Reset state if cycle has expired
    if (state.limitEndTimeMs > 0 && currentMs > state.limitEndTimeMs) {
      state = {
        ...state,
        limitEndTimeMs: 0,
        executedTimesCurrentCycle: 0,
      };
    }

    const granted = state.executedTimesCurrentCycle < this.limitCycleExecutionTimes;
    return { granted, state };
  }

  async tryApply(options?: TryApplyOptions): Promise<ThrottlerResponse> {
    if (options) {
      this.limitCycleExecutionTimes = options.limitCycleExecutionTimes;
      this.limitCycleTimeMs = options.limitCycleTimeMs;
    }

    let granted = false;
    let state = await this.ctx.storage.get('throttle_state') as ThrottleState | null;

    if (!state) {
      state = {
        limitTimes: 0,
        limitEndTimeMs: 0,
        executedTimesCurrentCycle: 0,
        currentCycle: 0,
      };
    }

    const currentMs = Date.now();

    // Reset cycle if expired
    if (state.limitEndTimeMs > 0 && currentMs > state.limitEndTimeMs) {
      state.limitEndTimeMs = 0;
      state.executedTimesCurrentCycle = 0;
    }

    // Check if request can be granted
    if (state.executedTimesCurrentCycle < this.limitCycleExecutionTimes) {
      state.executedTimesCurrentCycle++;
      granted = true;
    } else {
      state.limitTimes++;
      granted = false;
    }

    // Initialize new cycle if needed
    if (state.limitEndTimeMs === 0) {
      state.limitEndTimeMs = currentMs + this.limitCycleTimeMs;
      state.currentCycle++;

      if (state.currentCycle >= 65535) {
        state.currentCycle = 1;
      }
    }

    await this.ctx.storage.put('throttle_state', state);
    return { granted, state };
  }
}

Using the Rate Limiter

Integrating this rate limiter into your Worker is straightforward:

export default {
  async fetch(request: Request, env: Env) {
    // Create DO instance based on user identifier
    const userId = request.headers.get('user-id') || 'anonymous';
    const id = env.THROTTLER.idFromName(userId);
    const throttler = env.THROTTLER.get(id);

    // Check rate limit
    const result = await throttler.tryApply({
      limitCycleExecutionTimes: 5,
      limitCycleTimeMs: 60 * 1000, // 1 minute
    });

    if (!result.granted) {
      return new Response('Rate limit exceeded', { 
        status: 429,
        headers: {
          'Retry-After': '60'
        }
      });
    }

    // Process the actual request
    return processRequest(request);
  }
};

Real-World Performance

I've been running this rate limiter in production for several months now. The results have been impressive:

Latency: Average rate limit checks complete in under 5ms, compared to 80-150ms with our previous Redis setup.

Reliability: Zero downtime related to rate limiting failures since deployment. Durable Objects automatically handle failover and state migration.

Cost Efficiency: Running at roughly 30% of our previous Redis costs while serving 10x more requests.

Geographic Performance: Users in Asia Pacific see the same low latency as users in North America, thanks to Cloudflare's global network.

This architecture has been battle-tested at Fastjrsy, where we process thousands of AI-generated jersey design requests daily. During traffic spikes, the rate limiter seamlessly scales to handle 500+ concurrent requests per second while maintaining fair usage policies across our global user base.

Key Takeaways

Durable Objects excel when you need:

Stateful logic at the edge
Strong consistency guarantees
Automatic scaling and geographic distribution
Low latency for global applications

They may not be the right choice if you need:

Cross-platform compatibility beyond Cloudflare
Complex query capabilities like traditional databases
Shared state across multiple applications

What's Your Experience?

Have you implemented rate limiting in serverless environments? I'd love to hear about your approach and any challenges you've encountered. Are there specific use cases where you think Durable Objects would be particularly valuable?

Drop a comment below and let's discuss the future of edge computing architecture!

How to Implement Random Algorithms in Frontend JavaScript?

horus he — Mon, 07 Apr 2025 01:46:57 +0000

In the world of frontend development, randomness can play a crucial role in various applications, from gaming to data sampling. This article explores different ways to implement random algorithms in JavaScript, focusing on the built-in methods and their advantages. We'll cover the traditional Math.random() method, the more secure crypto.getRandomValues(), and delve into concepts like normalization, weighted random selection, and advanced shuffling techniques.

Random Algorithm Implementations

1. The `Math.random()` Method

The simplest way to generate a random number in JavaScript is by using the Math.random() method. This function returns a floating-point number between 0 (inclusive) and 1 (exclusive). Here’s a basic example:

const randomValue = Math.random();
console.log(randomValue); // Outputs a random number between 0 and 1

However, Math.random() is not suitable for cryptographic purposes or applications requiring high levels of unpredictability, as its algorithm is not designed to be secure.

2. The `crypto.getRandomValues()` Method

For applications that demand randomness with a higher degree of security, the crypto.getRandomValues() method is the go-to choice. This method generates cryptographically secure random values, making it ideal for tasks like generating tokens or keys.

Here's how to use it:

const array = new Uint32Array(10);
window.crypto.getRandomValues(array);
console.log(array); // Outputs an array of 10 cryptographically secure random integers

Advantages of `crypto.getRandomValues()`

Cryptographic Security: Unlike Math.random(), crypto.getRandomValues() is designed to provide secure random values that are suitable for cryptographic use.
Uniform Distribution: It ensures a more uniform distribution of values, reducing predictability.
Browser Support: Most modern browsers support the Web Crypto API, making it widely usable.

Understanding Normalization

Normalization is the process of adjusting values measured on different scales to a common scale. In the context of random selection, normalization is crucial when dealing with weighted probabilities.

Use Case of Normalization

Suppose you have an array of objects with associated weights:

const items = [
  { name: "A", weight: 1 },
  { name: "B", weight: 3 },
  { name: "C", weight: 2 },
];

To normalize these weights, you calculate the total weight and then divide each weight by this total:

const totalWeight = items.reduce((sum, item) => sum + item.weight, 0);
const normalizedWeights = items.map(item => item.weight / totalWeight);

This gives you a set of probabilities that sum to 1, making it easier to implement weighted random selection.

Implementing Weighted Random Selection

Now that we have normalized weights, we can implement a function to randomly select an item based on its weight:

function weightedRandomSelection(items) {
  const totalWeight = items.reduce((sum, item) => sum + item.weight, 0);
  const randomValue = Math.random() * totalWeight;

  let cumulativeWeight = 0;
  for (const item of items) {
    cumulativeWeight += item.weight;
    if (randomValue < cumulativeWeight) {
      return item.name; // Return the selected item
    }
  }
}

// Example usage
const selectedItem = weightedRandomSelection(items);
console.log(selectedItem); // Outputs either "A", "B", or "C" based on their weights

Advanced: The Fisher-Yates Shuffle Algorithm

The Fisher-Yates shuffle algorithm is an efficient way to randomly shuffle an array. This algorithm ensures that every permutation of the array is equally likely.

Here’s how you can implement it:

function fisherYatesShuffle(array) {
  for (let i = array.length - 1; i > 0; i--) {
    const j = Math.floor(Math.random() * (i + 1));
    [array[i], array[j]] = [array[j], array[i]]; // Swap elements
  }
  return array;
}

// Example usage
const shuffledArray = fisherYatesShuffle([1, 2, 3, 4, 5]);
console.log(shuffledArray); // Outputs a randomly shuffled array

Secure Version (using crypto)

Use the secure version for shuffling sensitive data like password character sets or game cards.

function secureRandomInt(max) {
  const array = new Uint32Array(1);
  window.crypto.getRandomValues(array);
  return array[0] % (max + 1);
}

function secureFisherYatesShuffle(array) {
  const result = [...array];
  for (let i = result.length - 1; i > 0; i--) {
    const j = secureRandomInt(i);
    [result[i], result[j]] = [result[j], result[i]];
  }
  return result;
}

Advanced: Multi-Sample Weighted Selection

For scenarios where you need to select multiple items based on weights, you can extend the weighted selection function. This involves removing the selected item from the pool or adjusting the weights accordingly.

Here’s a simple implementation:

function multiSampleWeightedSelection(items, sampleSize) {
  const results = [];
  const availableItems = [...items];

  for (let i = 0; i < sampleSize; i++) {
    const selectedItem = weightedRandomSelection(availableItems);
    results.push(selectedItem);
    // Optionally remove or adjust the selected item from availableItems
  }

  return results;
}

// Example usage
const samples = multiSampleWeightedSelection(items, 2);
console.log(samples); // Outputs an array of selected items based on their weights

Without Replacement (unique selections)

function multiSampleUniqueWeightedSelection(items, sampleSize) {
  const results = [];
  const pool = [...items];
  for (let i = 0; i < sampleSize && pool.length > 0; i++) {
    const selectedName = weightedRandomSelection(pool);
    results.push(selectedName);
    const index = pool.findIndex(item => item.name === selectedName);
    pool.splice(index, 1); // remove selected item
  }
  return results;
}

Choose with or without replacement depending on whether duplicates are acceptable in your use case.

Real-World Example: Weighted Random Spinner

A great real-world example of weighted random selection is the interactive spinner at:

👉 https://ruletaa.net/

This site allows users to create custom spinning wheels where each segment can have a different weight, influencing the likelihood of being selected when the wheel is spun.

Use Cases:

Random giveaways with weighted chances
Classroom participation tools
Decision-making apps with biased outcomes
Gamified reward systems

Behind the scenes, tools like this often use the same weighted selection logic we discussed earlier — assigning each option a weight, normalizing the probabilities, and then selecting based on those weights.

Conclusion

In this article, we explored various ways to implement random algorithms in frontend JavaScript. From using Math.random() for simple tasks to employing crypto.getRandomValues() for secure applications, we also covered normalization, weighted random selection, and advanced techniques like the Fisher-Yates shuffle and multi-sample weighted selection.

Understanding these concepts will empower you to implement randomness effectively in your applications, ensuring both fairness and security where needed. Happy coding!

Building a Geographic Distance and Direction Calculator for Flag-based Geography Games

horus he — Fri, 24 Jan 2025 11:28:50 +0000

As a developer working on geography education games, I recently faced an interesting challenge: how to make learning world geography more engaging and interactive. This led me to develop a comprehensive geographic calculation system for Flagle Explorer, a flag-guessing game that provides real-time feedback based on players' guesses.

The Challenge

Traditional geography games often rely on simple "right or wrong" feedback. However, research from the Journal of Geography in Higher Education shows that interactive learning methods can improve geographic knowledge retention by up to 40%. This inspired us to create a more nuanced feedback system that would guide players toward the correct answer while teaching them about global geography.

Research and Requirements

Our key requirements were:

Calculate accurate distances between any two points on Earth
Determine directional relationships between locations
Provide a meaningful "closeness" percentage
Support emoji-based direction indicators for better UX

The Solution

Let's break down the key components of our geographic calculation system:

1. Distance Calculation

We implemented the Haversine formula to calculate the great-circle distance between two points:

export function calculateDistance(point1: GeoPoint, point2: GeoPoint): number {
  // Quick return for identical points
  if (point1.lat === point2.lat && point1.lon === point2.lon) {
    return 0;
  }

  // Earth's radius in meters
  const R = 6371000;

  // Convert latitude/longitude differences to radians
  const dLat = (point2.lat - point1.lat) * Math.PI / 180;
  const dLon = (point2.lon - point1.lon) * Math.PI / 180;

  // Haversine formula
  const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) +
    Math.cos(point1.lat * Math.PI / 180) * Math.cos(point2.lat * Math.PI / 180) *
    Math.sin(dLon / 2) * Math.sin(dLon / 2);
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));

  // Convert to kilometers
  return R * c / 1000;
}

2. Direction Calculation

We developed a bearing calculation system that converts complex angular mathematics into user-friendly directional indicators:

export function calculateOrientationEmoji(point1: GeoPoint, point2: GeoPoint): string {
  const orientation = calculateOrientation(point1, point2);

  // Handle identical points
  if (orientation === 0 || (point1.lat === point2.lat && point1.lon === point2.lon)) {
    return '🟢';
  }

  // Convert bearing to 8-direction compass
  if (orientation >= 337.5 || orientation < 22.5) return '⬆️';  // North
  if (orientation >= 22.5 && orientation < 67.5) return '↗️';   // Northeast
  if (orientation >= 67.5 && orientation < 112.5) return '➡️';  // East
  if (orientation >= 112.5 && orientation < 157.5) return '↘️'; // Southeast
  if (orientation >= 157.5 && orientation < 202.5) return '⬇️'; // South
  if (orientation >= 202.5 && orientation < 247.5) return '↙️'; // Southwest
  if (orientation >= 247.5 && orientation < 292.5) return '⬅️'; // West
  return '↖️'; // Northwest
}

3. Proximity Percentage

To provide intuitive feedback about how close a guess is, we implemented a percentage-based system:

export function calculateGeoClosingPercent(point1: GeoPoint, point2: GeoPoint): number {
  const distance = calculateDistance(point1, point2);
  const MAX_DISTANCE = 20000; // Maximum reference distance in km

  if (distance >= MAX_DISTANCE) return 1;
  if (distance === 0) return 100;

  // Linear interpolation for percentage calculation
  const percent = ((MAX_DISTANCE - distance) / MAX_DISTANCE) * 100;
  return Math.max(0, Math.min(100, Number(percent.toFixed(2))));
}

Real-world Application

This system has been successfully implemented in Flagle Explorer, where it provides players with three key pieces of feedback after each guess:

Exact distance to the target in kilometers
Directional guidance using intuitive emoji arrows
A percentage indicating how close they are to the correct answer

The feedback system has proven particularly effective in educational settings, where teachers report increased student engagement and better retention of geographical concepts.

Future Optimizations

We're currently exploring several improvements:

Adding terrain and geographical features to distance calculations
Implementing regional proximity bonuses
Developing a difficulty-based scoring system
Adding support for historical border changes

Want to see these geographic calculations in action? Try solving today's flag puzzle at Flagle Explorer and watch as the distance and direction indicators guide you around the globe!

Building a Robust Color Mixing Engine: From Theory to Implementation

horus he — Wed, 15 Jan 2025 04:55:40 +0000

Ever wondered why mixing colors on your screen feels different from mixing paints? Let's dive deep into digital color mixing and build a powerful color mixing engine using TypeScript! 🎨

Understanding Digital Color Theory

Unlike physical pigments that use subtractive color mixing (CMYK), digital displays work with additive color mixing (RGB). When we mix colors digitally, we're actually blending light rather than physical materials. This fundamental difference leads to some interesting challenges and opportunities in implementation.

Here's what makes digital color mixing unique:

Colors are represented as RGB values (typically 0-255 or 0-100)
Mixing is achieved through mathematical calculations
Results can be precisely controlled and reproduced
The process is reversible (unlike physical paint mixing)

Implementing the Color Mixing Engine

Let's build a robust color mixing system that handles precise proportional mixing. We'll start with the core types and then implement the mixing logic:

interface Color {
  red: number;   // 0-100 range
  green: number; // 0-100 range
  blue: number;  // 0-100 range
}

interface ColorMix {
  color: Color;
  proportion: number; // percentage (0-100)
}

function mixColors(colorMixes: ColorMix[]): Color {
  // Validate proportions
  const totalProportion = colorMixes.reduce((sum, mix) => sum + mix.proportion, 0);
  if (Math.abs(totalProportion - 100) > 0.001) {
    throw new Error('Color proportions must sum up to 100%');
  }

  // Mix colors using weighted average
  return colorMixes.reduce((result, mix) => ({
    red: result.red + (mix.color.red * mix.proportion) / 100,
    green: result.green + (mix.color.green * mix.proportion) / 100,
    blue: result.blue + (mix.color.blue * mix.proportion) / 100
  }), { red: 0, green: 0, blue: 0 });
}

Key Design Decisions

Type Safety: We use TypeScript interfaces to ensure type correctness and provide better IDE support.
Normalized Values: Colors use 0-100 range for easier percentage calculations.
Proportion Validation: We ensure mixing proportions always sum to 100%.
Immutable Operations: The mixing function doesn't modify input values.

Building a Color Mixing Tool

Want to create your own color mixing tool? Here's a step-by-step guide:

1.Set Up the UI Components:

interface ColorPickerProps {
  onColorChange: (color: Color) => void;
  onProportionChange: (proportion: number) => void;
}

// Example React component structure
const ColorMixer = () => {
  const [colors, setColors] = useState<ColorMix[]>([]);
  const [result, setResult] = useState<Color | null>(null);

  // Implementation details...
};

2.Add Real-time Preview:

// Calculate and update mixed color on any change
useEffect(() => {
  if (colors.length > 0) {
    try {
      const mixed = mixColors(colors);
      setResult(mixed);
    } catch (error) {
      console.error('Invalid color mix:', error);
    }
  }
}, [colors]);

3.Implement Color Visualization:

const toRGBString = (color: Color): string => 
  `rgb(${color.red}%, ${color.green}%, ${color.blue}%)`;

// Use in your JSX
<div style={{ backgroundColor: toRGBString(result) }} />

Advanced Topics and Optimizations

Performance Considerations

When building a real-world color mixing application, consider these optimizations:

1.Memoization: Cache frequently used color combinations

const memoizedMixColors = memoize(mixColors, {
  maxSize: 1000,
  resolver: (colorMixes) => JSON.stringify(colorMixes)
});

2.Batch Processing: Group color calculations for better performance

const batchMixColors = (colorBatches: ColorMix[][]): Color[] => {
  return colorBatches.map(batch => mixColors(batch));
};

Extended Features

To make your color mixing tool more powerful, consider adding these features:

1.Color Space Conversions:

interface HSLColor {
  hue: number;
  saturation: number;
  lightness: number;
}

const rgbToHsl = (color: Color): HSLColor => {
  // Conversion logic
};

const hslToRgb = (color: HSLColor): Color => {
  // Conversion logic
};

2.Gamma Correction:

const applyGamma = (color: Color, gamma: number = 2.2): Color => ({
  red: Math.pow(color.red / 100, gamma) * 100,
  green: Math.pow(color.green / 100, gamma) * 100,
  blue: Math.pow(color.blue / 100, gamma) * 100
});

Practical Applications and Future Directions

Our color mixing engine has numerous practical applications:

Digital Art Tools: Create realistic color blending effects
Design Systems: Generate consistent color palettes
Data Visualization: Mix colors for gradients and charts
Game Development: Dynamic color effects and transitions

Future improvements could include:

Support for additional color spaces (LAB, HSV)
Color harmony algorithms
Accessibility features (contrast checking)
Integration with popular design tools

Remember, while our implementation is mathematically accurate, the visual perception of mixed colors might vary slightly due to screen calibration and human color perception differences.

Want to experiment with the code? Check out the Colorfle - The Ultimate Color Mixing Puzzle Game or try the Colorfle Unlimited!

I hope this guide helps you understand digital color mixing and inspires you to build your own color tools! Feel free to share your implementations or ask questions in the comments below. 🚀

Forem: horus he

From Prompt to Production: A Practical Architecture for Chat-Based AI Image Generation

The Core Problem: AI Generation Is Slow

Architecture Overview

State Management: Sessions and Messages

Sessions

Messages

Credit System: Reservations and Confirmations

Streaming Progress: Keeping Users Informed

Model Selection: Flexibility vs. Complexity

Webhook Handling: External Service Integration

Idempotency

Timeout Handling

State Recovery

Cost Optimization: Learning from Production Data

Model Routing

Resolution Defaults

Caching Similar Requests

What We'd Do Differently

Polling vs. WebSockets

Queue Visibility

Rate Limiting at the Edge

Conclusion

Technical Stack Summary

How I Handle 15-Second AI Tasks Without Losing 87% of Users

The $10,000 Problem

The Magic: Async Processing + Smart Polling

The Frontend Magic

The Webhook Secret Sauce

Real Production Results

The Gotchas Nobody Talks About

Quick Implementation Checklist

The Architecture That Scales

Your Turn

Why I Ditched Redis for Cloudflare Durable Objects in My Rate Limiter？

The Traditional Approach Falls Short

Enter Durable Objects

Building the Rate Limiter

Using the Rate Limiter

Real-World Performance

Key Takeaways

What's Your Experience?

How to Implement Random Algorithms in Frontend JavaScript?

Random Algorithm Implementations

1. The Math.random() Method

2. The crypto.getRandomValues() Method

Advantages of crypto.getRandomValues()

Understanding Normalization

Use Case of Normalization

Implementing Weighted Random Selection

Advanced: The Fisher-Yates Shuffle Algorithm

Secure Version (using crypto)

Advanced: Multi-Sample Weighted Selection

Without Replacement (unique selections)

Real-World Example: Weighted Random Spinner

Conclusion

Building a Geographic Distance and Direction Calculator for Flag-based Geography Games

The Challenge

Research and Requirements

The Solution

1. Distance Calculation

2. Direction Calculation

3. Proximity Percentage

Real-world Application

Future Optimizations

Building a Robust Color Mixing Engine: From Theory to Implementation

Understanding Digital Color Theory

Implementing the Color Mixing Engine

Key Design Decisions

Building a Color Mixing Tool

Advanced Topics and Optimizations

Performance Considerations

Extended Features

Practical Applications and Future Directions

1. The `Math.random()` Method

2. The `crypto.getRandomValues()` Method

Advantages of `crypto.getRandomValues()`