DEV Community: PubliFlow

How I Integrated AI Video Generation into a SaaS Platform — Seedance API + Credit System

PubliFlow — Sun, 02 Aug 2026 16:23:03 +0000

AI video generation is no longer a novelty — it's becoming a core feature in SaaS products. But integrating it into a production application comes with real engineering challenges: asynchronous processing, credit-based billing, cost management, and user experience design.

In this article, I'll walk through how I integrated Seedance 2.0 Mini into VEIGO's platform, built a credit system around it, and what I learned about pricing AI-generated content.

The Challenge

I needed to add AI video generation to a SaaS platform with these requirements:

Users should be able to generate videos from text prompts or images
The system needs to handle long-running generation tasks (30s to 5min)
Monetization through a credit/point system rather than per-video pricing
Seamless UX — users shouldn't feel like they're waiting for a batch job

Why Seedance 2.0 Mini

After evaluating Runway, Pika, Kling, and Stable Video Diffusion, I chose Seedance 2.0 Mini for several reasons:

Cost-effectiveness: Competitive pricing for the quality output
API reliability: Consistent uptime and response times
Resolution flexibility: Multiple output options (480p, 720p, 1080p)
Image-to-video capability: Critical for property listings and product showcases
Chinese market alignment: Better support for Chinese text prompts and cultural context

Architecture: The Async Task Pattern

Video generation isn't instant. Even "fast" models take 30+ seconds. Here's the architecture I implemented:

User Request → Task Queue → Seedance API → Polling Service → Result Storage → User Notification

Step 1: Task Creation

When a user submits a generation request, we don't wait for the video. Instead:

// app/api/studio/generate/route.ts
export async function POST(req: Request) {
  const { prompt, imageUrl, resolution, duration } = await req.json();

  // Calculate credit cost based on parameters
  const creditCost = calculateCredits(resolution, duration);

  // Check user balance
  const user = await getUserWithBalance(session.userId);
  if (user.credits < creditCost) {
    return Response.json({ error: "Insufficient credits" }, { status: 402 });
  }

  // Create task record
  const task = await db.videoTask.create({
    data: {
      userId: session.userId,
      status: "PENDING",
      prompt,
      imageUrl,
      resolution,
      duration,
      creditsCharged: creditCost,
    }
  });

  // Submit to Seedance API (non-blocking)
  const seedanceTaskId = await submitToSeedance({
    prompt,
    imageUrl,
    resolution,
    duration
  });

  // Update task with external ID
  await db.videoTask.update({
    where: { id: task.id },
    data: { externalTaskId: seedanceTaskId, status: "PROCESSING" }
  });

  return Response.json({ 
    taskId: task.id, 
    creditsCharged: creditCost,
    estimatedTime: getEstimate(duration)
  });
}

Step 2: Polling Service

A background service polls the Seedance API for task completion:

// lib/services/video-poller.ts
export async function pollTaskCompletion() {
  const pendingTasks = await db.videoTask.findMany({
    where: { status: "PROCESSING" },
    take: 10 // Batch processing
  });

  for (const task of pendingTasks) {
    try {
      const result = await seedance.getTaskStatus(task.externalTaskId);

      if (result.status === "COMPLETED") {
        // Download and store the video
        const videoUrl = await downloadAndStore(result.videoUrl, task.id);

        await db.videoTask.update({
          where: { id: task.id },
          data: { 
            status: "COMPLETED",
            videoUrl,
            completedAt: new Date()
          }
        });

        // Notify user
        await notifyUser(task.userId, {
          type: "VIDEO_READY",
          taskId: task.id
        });
      } else if (result.status === "FAILED") {
        // Refund credits on failure
        await refundCredits(task.userId, task.creditsCharged);
        await db.videoTask.update({
          where: { id: task.id },
          data: { status: "FAILED", failureReason: result.error }
        });
      }
      // If still processing, just wait for next poll cycle
    } catch (error) {
      console.error(`Poll error for task ${task.id}:`, error);
    }
  }
}

Step 3: User-Facing Status

The frontend polls for task status with a progress indicator:

// components/VideoTaskStatus.tsx
export function VideoTaskStatus({ taskId }: { taskId: string }) {
  const [status, setStatus] = useState<TaskStatus>("PROCESSING");
  const [progress, setProgress] = useState(0);

  useEffect(() => {
    const interval = setInterval(async () => {
      const res = await fetch(`/api/studio/task/${taskId}`);
      const data = await res.json();
      setStatus(data.status);
      setProgress(data.progress);

      if (data.status === "COMPLETED" || data.status === "FAILED") {
        clearInterval(interval);
      }
    }, 3000); // Poll every 3 seconds

    return () => clearInterval(interval);
  }, [taskId]);

  return (
    <div className="task-status">
      <ProgressBar value={progress} />
      <StatusBadge status={status} />
      {status === "COMPLETED" && <VideoPlayer url={status.videoUrl} />}
    </div>
  );
}

The Credit System Design

Instead of per-video pricing (which feels unpredictable), I designed a credit bundle system:

Plan	Credits	Price	Per-Credit Cost
Starter	100	$5	$0.050
Professional	400	$15	$0.038
Business	1,000	$30	$0.030
Enterprise	2,500	$50	$0.020

Credit Cost Per Generation

Different parameters consume different credit amounts:

function calculateCredits(resolution: string, duration: number): number {
  const baseCost = {
    "480p": 2,
    "720p": 4,
    "1080p": 8
  };

  const durationMultiplier = duration <= 5 ? 1 : duration <= 10 ? 1.5 : 2;

  return Math.ceil(baseCost[resolution] * durationMultiplier);
}

Why Credits Work Better Than Per-Video Pricing

Predictable revenue: Users buy bundles upfront
Flexible usage: A credit can generate a 480p clip or contribute toward a 1080p video
Reduced decision fatigue: Users don't calculate cost per video
Upsell opportunity: Running low? Here's a bigger bundle at a better rate
Graceful degradation: If API costs change, adjust credit costs without changing user-facing prices

Pricing Strategy Thoughts

After 3 months of operation, here's what I've observed:

The $5 tier is the acquisition engine. Most users start here. It's low-risk enough to try, and 100 credits let them generate ~25 480p videos or ~12 720p videos.

The $30 tier is the sweet spot. Users who find value quickly upgrade here. The per-credit savings (40% vs Starter) feels significant.

Enterprise users negotiate. At $50 for 2,500 credits, businesses generating content at scale often reach out for custom pricing.

Key insight: The pricing isn't really about the credits — it's about removing friction. Users who buy credits generate more content, which makes the platform stickier, which reduces churn.

Cost Management

Seedance API costs aren't trivial. Here's how I keep margins healthy:

Resolution-tiered pricing: Higher resolution costs more credits, matching higher API costs
Batch processing: Group API calls to reduce overhead
Caching: Similar prompts with same seed get cached results
Failure handling: Failed generations refund credits immediately (maintaining trust)
Usage monitoring: Alert when a user's generation pattern suggests abuse

Lessons Learned

1. Set expectations early
Users need to know generation takes time. We show estimated wait times upfront and use optimistic UI updates.

2. Always refund on failure
Nothing destroys trust faster than charging credits for failed generations. We refund immediately and send a notification explaining why it failed.

3. Offer a free tier
We give 10 free credits on signup. This lets users experience the product before committing money. Conversion rate from free to paid is ~15%.

4. Monitor API costs vs. credit revenue
We track the ratio weekly. Target is 60%+ gross margin. If API costs spike, we adjust credit costs (not plan prices — that would break trust).

5. Content moderation is mandatory
AI-generated video can be misused. We run all prompts through a content filter before submission and have a reporting system for generated content.

Try It Out

The AI Video Studio is live and integrated into the VEIGO platform. It's particularly useful for:

Real estate agents creating property walkthrough videos
E-commerce sellers generating product demos
Content creators producing short-form video content
Marketers creating social media ads

🎬 AI Video Studio: shopveigo.com/studio
💳 Credit Plans: shopveigo.com/pricing
🏠 Full Platform: shopveigo.com

Have you integrated AI video generation into your product? What challenges did you face? Share your experience in the comments.

I Built an All-in-One Platform for Expats — Renting, Jobs, Freelancing, and AI Tools in One Place

PubliFlow — Sun, 02 Aug 2026 16:22:01 +0000

As an expat who's lived in multiple countries, I know the struggle: finding an apartment in a foreign city, landing a job that matches your skills, picking up freelance gigs to make ends meet — all while navigating language barriers and unfamiliar platforms. Each task lives in a different app, each with its own login, its own verification process, and zero integration with the others.

After years of dealing with this fragmented experience, I decided to build something different. VEIGO is an all-in-one platform designed specifically for the global Chinese community — expats, students, professionals, and immigrants — bringing renting, jobs, freelancing, and AI tools under one roof.

The Problem: A Fragmented Expat Experience

When you move to a new country, you quickly realize how siloed existing tools are:

Renting: Zillow doesn't work in Spain. Idealista doesn't cover Japan. Each country has its own dominant platform, often only in the local language.
Jobs: LinkedIn is global but generic. For Chinese speakers, BOSS直聘 dominates the domestic market but has no international presence.
Freelancing: Upwork and Fiverr are competitive and commission-heavy. Finding Chinese-speaking clients abroad is nearly impossible.
AI Tools: ChatGPT, Midjourney, Runway — each requires a separate subscription, often with region-locked pricing.

The result? You're juggling 5-10 different platforms, each with its own UX patterns, notification systems, and payment methods. It's exhausting.

The Solution: VEIGO's Unified Architecture

VEIGO (available at shopveigo.com) addresses this through a multi-tenant architecture built on Next.js. Here's how the platform is structured:

1. Housing & Rental Module

Covering 5 countries with localized listing systems, currency support, and lease management. The module includes:

Map-based property search with geocoding
Multi-currency rent calculation and conversion
Landlord verification and review system
Lease document templates adapted to local regulations

2. Recruitment Module (BOSS直聘 Model)

Instead of the traditional resume-submit-and-wait approach, VEIGO's job module implements a direct chat model:

Real-time messaging between candidates and employers
Skill-based matching algorithm
Work authorization verification (visa status, permits)
Salary range transparency requirements

3. Freelance & Gig Economy

A marketplace for short-term work, specifically designed for expats who need flexible income:

Gig posting and discovery
Escrow-based payment protection
Multi-language project descriptions
Rating and reputation system

4. Bidding & Procurement

For businesses and contractors operating across borders, this module handles:

Tender document submission
Bid comparison and evaluation
Compliance checking across jurisdictions

5. AI Tool Suite

Integrated directly into the platform:

AI writing assistant for resumes, cover letters, and listings
Image generation for property listings and marketing
Translation support across all modules

6. Video Production Studio

Technical Architecture

The platform is built with a Next.js frontend and a multi-tenant backend that handles:

┌─────────────────────────────────────────┐
│              Next.js Frontend            │
├─────────────────────────────────────────┤
│         API Gateway (Route Handler)      │
├─────────┬──────────┬──────────┬─────────┤
│ Rental  │  Jobs    │  Gigs    │  AI     │
│ Service │  Service │  Service │  Service│
├─────────┴──────────┴──────────┴─────────┤
│         Shared Auth & Tenant Layer       │
├─────────────────────────────────────────┤
│         Database (Multi-tenant Schema)   │
└─────────────────────────────────────────┘

Key technical decisions:

Tenant isolation: Each country operates as a logical tenant with localized content, currency, and legal compliance
Shared authentication: Single sign-on across all modules — your rental profile feeds into your job application
Modular API design: Each service is independently deployable but shares common utilities (auth, payment, i18n)
Edge-ready: Next.js API routes with ISR for content-heavy pages

What I Learned Building This

1. Localization is deeper than translation
Each country's rental market has different norms. In Japan, key money (礼金) is standard. In Spain, deposits are regulated differently. Your schema needs to accommodate these variations without becoming unmaintainable.

2. Trust is the real product
Expats are vulnerable to scams. Every module includes verification layers — ID verification for landlords, business registration checks for employers, portfolio verification for freelancers.

3. Cross-module data is the moat
The real value isn't any single module — it's how they connect. A tenant's rental history informs their creditworthiness for job applications. A freelancer's project portfolio doubles as a resume. This interconnectedness is what makes VEIGO more than the sum of its parts.

What's Next

We're expanding to more countries, adding more AI-powered features, and building out the video production studio for property marketing and personal branding.

If you're an expat, student abroad, or part of the global Chinese community, I'd love for you to try it out and share feedback.

🔗 Try VEIGO: shopveigo.com
🎬 AI Video Studio: shopveigo.com/studio
💳 Premium Plans: shopveigo.com/pricing

What's your biggest pain point as an expat? I'd love to hear in the comments.

Designing an 8-Layer Cognitive Memory Architecture for AI Agents

PubliFlow — Sun, 02 Aug 2026 04:11:55 +0000

Designing an 8-Layer Cognitive Memory Architecture for AI Agents

Why flat vector stores fail as agent memory

Every AI agent framework today follows roughly the same playbook: take user input, embed it, store it in a vector database, retrieve similar chunks when needed. It works well enough for demos. It falls apart in production.

The fundamental problem isn't retrieval quality — it's architectural. Human memory isn't a single system. It's a stack of specialized subsystems, each solving a different problem. When we collapse all of memory into "store embeddings, retrieve by cosine similarity," we're ignoring 60 years of cognitive science research.

I built the EdosAI Memory Framework to fix this. It's 23,000+ lines of Python across 51 modules, implementing an 8-layer cognitive memory architecture. This post is a deep dive into why we designed it this way and what each layer actually does.

The cognitive science foundation

Three research traditions informed the architecture:

1. The Atkinson-Shiffrin model (1968) established that memory flows through distinct stores: sensory → short-term → long-term. This is why our architecture has a clear information flow from L1 (sensory buffer) through L2 (working memory) to L3-L5 (long-term stores).

2. Tulving's episodic/semantic distinction (1972) showed that remembering an event and knowing a fact are fundamentally different operations. This is why we separate L3 (episodic) from L4 (semantic) rather than dumping everything into one store.

3. McClelland, McNaughton, and O'Reilly's Complementary Learning Systems theory (1995) demonstrated that the brain needs two complementary systems — fast learning (hippocampus) and slow consolidation (neocortex) — to avoid catastrophic interference. This directly inspired our L7 consolidation engine.

Layer-by-layer architecture

L1: Sensory Buffer — The 500ms window

Input → [Sensory Buffer] → Working Memory or Decay

The sensory buffer holds raw perceptual input for sub-second durations. In our implementation, this means the raw LLM response, tool outputs, and environmental signals before any processing.

Why does this matter? Because most agents immediately try to "understand" everything. The sensory buffer gives the system a moment to decide what's worth attending to. Not everything deserves working memory allocation.

Implementation: A ring buffer with configurable capacity. Items older than the decay threshold are dropped unless explicitly attended to.

L2: Working Memory — The active workspace

[Sensory Buffer] → [Working Memory] ← Central Executive
                        ↓
              Episodic / Semantic / Procedural

Baddeley's working memory model (1974) proposed multiple components: a central executive, a phonological loop, and a visuospatial sketchpad. We adapt this as:

Central Executive: Decides what gets processed and what gets dropped
Active Context: The current conversation/task state
Capacity Management: Enforces a hard limit on concurrent active items (inspired by Cowan's ~4±1 finding)

This is where most current agents operate 100% of the time. But without the layers below, working memory has nowhere to put things for long-term storage.

L3: Episodic Memory — What happened and when

Working Memory → [Episodic Store]
                  ├── Event boundary detection
                  ├── Temporal indexing
                  └── Contextual binding

Every significant event gets stored as an episode: timestamped, context-tagged, and linked to related episodes. The key insight from Tulving is that episodic memories are autonoetic — they carry the subjective experience of "reliving."

In practice, this means each episode stores:

What happened (the content)
When it happened (temporal index)
What else was happening (context)
How important it was (valence, from L6)

Event boundary detection is crucial. Not every token is an event. The system identifies meaningful transitions — topic changes, task completions, error states — and uses those as episode boundaries.

L4: Semantic Memory — What you know (not what happened)

Episodic Memory → [Consolidation] → Semantic Store
                                     ├── Knowledge graphs
                                     ├── Fact triples
                                     └── Concept hierarchies

Here's the key distinction: episodic memory stores events ("On Tuesday, the user asked about Python decorators"). Semantic memory stores facts ("Python decorators are used for modifying function behavior").

The semantic layer automatically extracts facts from episodic memories. Over time, you get a structured knowledge base that represents what the agent "knows" — not just what it "experienced."

Implementation: Knowledge graphs with entity-relationship-extraction triples. Periodic consolidation runs (from L7) transfer facts from episodic to semantic storage.

L5: Procedural Memory — Learning from doing

Episodic Memory + [Reward Signal] → Procedural Store
                                     ├── Action sequences
                                     ├── Success patterns
                                     └── Skill abstractions

This is the layer most agent frameworks completely ignore. Procedural memory is how you ride a bicycle — you can't explain it in words, but your body "knows."

For AI agents, procedural memory means: after solving a problem 10 times, the agent develops a skill for that problem type. It doesn't just retrieve similar past solutions — it internalizes the pattern.

Implementation: Action sequences are stored with their outcomes. Successful patterns get reinforced. Over time, common sequences get compressed into higher-level skills. This is the agent's equivalent of going from "I carefully follow these 15 steps" to "I just know how to do this."

L6: Emotional Valence — Not everything matters equally

All Layers ← [Valence Module]
              ├── Priority scoring
              ├── Salience detection
              └── Recall modulation

The amygdala modulates memory encoding and retrieval based on emotional significance. We implement this as a valence scoring module that:

Assigns importance scores to new information (novelty, relevance, user signals)
Modulates encoding strength (high-valence items get stored more robustly)
Modulates retrieval priority (important memories surface first)

Without this, every memory is "equally important," which means nothing is actually important. The agent treats a user's name with the same weight as their preferred coffee order.

L7: Consolidation Engine — The hippocampus at night

Episodic Store ←→ [Consolidation Engine] ←→ Semantic Store
                     ├── Replay mechanism
                     ├── Compression
                     ├── Abstraction
                     └── Interference resolution

This is arguably the most technically interesting layer. Inspired by the Complementary Learning Systems theory, the consolidation engine runs offline (between conversations or during low-activity periods) and performs:

Replay: Re-processes recent episodic memories, similar to hippocampal sharp-wave ripples during sleep
Compression: Multiple similar episodes get merged into a single semantic summary
Abstraction: Extracts general patterns from specific instances
Interference Resolution: Identifies and resolves contradictions between old and new knowledge

This is what separates the framework from "store everything and hope retrieval works." Without consolidation, memory grows linearly forever. With it, the agent's knowledge actually improves over time as raw experiences get distilled into structured understanding.

L8: Meta-cognitive Layer — Knowing what you know

All Layers → [Meta-cognitive Monitor]
              ├── Memory state awareness
              ├── Confidence estimation
              ├── Gap detection
              └── Strategic recall

The top layer lets the agent reason about its own memory state. This enables:

Confidence estimation: "I'm fairly sure I know this" vs. "I have no memory of this"
Gap detection: "I should know this but can't recall it"
Strategic recall: Trying different retrieval strategies when the first attempt fails

Nelson and Narens (1990) described meta-memory as a monitor-control loop. The monitor assesses memory state; the control decides what to do about it. L8 implements both.

How the layers interact

The layers aren't isolated. Information flows in multiple directions:

Forward flow (encoding):
L1 → L2 → L3 → L4 → L5
                ↑
L6 modulates encoding at every level

Backward flow (retrieval):
L8 initiates → L7 guides → L4/L3/L5 respond
L6 modulates retrieval priority

Consolidation flow:
L3 ←→ L7 ←→ L4 (offline replay and transfer)

This bidirectional flow is what makes the architecture more than a pipeline. It's a system.

Implementation reality

51 Python modules. 23,000+ lines of code. This isn't a toy. Here's what the engineering looked like:

Each layer is independently testable but designed for cross-layer communication
The consolidation engine runs as a background process with configurable scheduling
Memory stores are abstracted behind interfaces — swap the backing storage (SQLite, PostgreSQL, Redis, etc.) without touching the architecture
Hardware-bound licensing with AES-256 encryption protects intellectual property

How it compares to existing approaches

Approach	Architecture	Memory Types	Consolidation	Meta-cognition
LangChain Memory	Flat chain/summary	1-2 types	None	None
MemGPT/Virtual Context	Two-tier (main + archival)	2 types	Manual	Partial
Generative Agents	Memory stream + reflection	2 types	Reflection only	None
EdosAI	8 layers	5+ types	Automated	Full

The key differentiators:

Procedural memory (L5) — no other agent framework I know of implements skill learning from experience
Consolidation engine (L7) — automated, not manual; runs continuously
Meta-cognitive layer (L8) — the agent can reason about its own knowledge gaps

What this costs

I believe in transparent pricing:

Tier	What you get	Price
API Access	Full functionality via REST API	$299
Compiled SDK	Local deployment, compiled libraries	$2,999
Source Code	All 51 files, full modification rights	$9,999

Purchase links:

API Access: https://creem.io/payment/prod_6RHYa4HxvHSNaoPX3Y3f4w
Compiled SDK: https://creem.io/payment/prod_7MlHfmV5GE5veelIw3Qs2H
Source Code: https://creem.io/payment/prod_5KDcisVyJlZcNpwxmjG9Mf

Closing thoughts

The AI agent ecosystem is moving fast. But memory — actual, persistent, structured, self-improving memory — remains surprisingly underdeveloped. Most frameworks treat it as an afterthought.

I believe memory is the missing piece that separates "chatbot with tools" from "genuinely intelligent agent." The 8-layer architecture isn't over-engineering. It's the minimum viable complexity for memory that actually works.

If you're building agents that need to get better over time — not just accumulate context — take a look at EdosAI Memory Framework.

EdosAI Memory Framework — 8 layers, 51 modules, 23,000+ lines. Built for agents that need to remember.

Architecting Bulletproof SaaS Billing with Stripe: Webhooks, Proration, and Usage Metrics

PubliFlow — Sat, 01 Aug 2026 01:20:37 +0000

Architecting Bulletproof SaaS Billing with Stripe

Building a SaaS product is a marathon, but billing is where developers often trip over their own shoelaces. A buggy feature flag system costs you a weekend of debugging; a buggy billing system costs you revenue, triggers chargebacks, and destroys customer trust.

When you scale past a few hundred customers, the 'happy path' of Stripe integration falls apart. You encounter out-of-order webhooks, proration math that looks like witchcraft, and usage-based billing that accidentally double-charges users.

In this deep dive, we will architect a robust, production-grade billing system. We will cover asynchronous webhook processing, idempotent usage metering, and the dark arts of subscription proration.

The Architecture: Why Synchronous Webhooks Will Fail You

The most common mistake in SaaS billing is processing Stripe webhooks synchronously in the HTTP request handler.

[Stripe] --(Webhook)--> [Your API] --(DB Write)--> [Database]

If your database is slow, or you need to provision infrastructure (like creating a dedicated tenant workspace), the webhook takes too long. Stripe will retry. You will process the same webhook multiple times. Worse, if webhooks arrive out of order (which they do), your database state will corrupt.

The correct architecture introduces a message queue:

[Stripe] --(Webhook)--> [API Receiver] --(Push)--> [Message Queue]
                                                   |
[Database] <--- [Worker] <---(Pull & Process)------+

The API receiver's only job is to verify the signature and push the payload to a queue (like Redis, RabbitMQ, or AWS SQS). The worker processes the queue asynchronously, allowing for retries, rate limiting, and ordered processing.

Deep Dive 1: Idempotent Webhook Reception

Stripe guarantees at-least-once delivery. This means you will receive duplicate events. Your system must be idempotent.

Here is a production-ready Next.js API route that verifies the webhook, checks for idempotency, and queues the event.

import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';
import { redis } from '@/lib/redis';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(req: NextRequest) {
  const body = await req.text();
  const sig = req.headers.get('stripe-signature')!;

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
  } catch (err) {
    console.error('Webhook signature verification failed.');
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
  }

  // 1. Idempotency Check: Have we processed this exact event ID?
  const processedKey = `stripe_event_processed:${event.id}`;
  const alreadyProcessed = await redis.get(processedKey);

  if (alreadyProcessed) {
    return NextResponse.json({ received: true });
  }

  // 2. Queue the event for asynchronous processing
  await redis.rpush('stripe_webhook_queue', JSON.stringify({
    id: event.id,
    type: event.type,
    created: event.created,
    data: event.data.object
  }));

  // 3. Mark as processed with a 24-hour TTL
  await redis.set(processedKey, '1', 'EX', 86400);

  return NextResponse.json({ received: true });
}

Notice the 24-hour TTL on the idempotency key. Stripe event IDs are unique, but we don't want to store them in Redis forever.

Deep Dive 2: Usage-Based Billing and Metering

Usage-based billing (like charging per API call or per GB stored) is notoriously tricky. The naive approach is to calculate usage at the end of the month and call the Stripe API to create an invoice item. This is a race condition and hits Stripe's rate limits.

The modern approach is Stripe Billing Meters. You stream usage events to Stripe in real-time.

However, you must ensure idempotency here too. If your server crashes and retries a usage report, you don't want to charge the user twice for the same API call.

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function reportApiUsage(
  customerId: string,
  apiCalls: number,
  requestId: string
) {
  // The fingerprint ensures idempotency.
  const fingerprint = `usage_${customerId}_${requestId}`;

  try {
    await stripe.billing.meterEvents.create({
      event_name: 'api_call',
      payload: {
        stripe_customer_id: customerId,
        value: apiCalls.toString(),
      },
      identifier: fingerprint,
    });
    console.log(`Successfully reported ${apiCalls} calls for ${customerId}`);
  } catch (error) {
    if (error instanceof Stripe.errors.StripeInvalidRequestError) {
      console.error('Invalid meter event:', error.message);
    } else {
      throw error;
    }
  }
}

By using the identifier field with a deterministic fingerprint, you transform a potentially flaky network call into a robust, idempotent operation.

Deep Dive 3: The Dark Arts of Proration

Proration is the bane of every SaaS developer. When a user upgrades from a $20/mo plan to a $50/mo plan in the middle of the month, Stripe needs to calculate the exact credit for the unused days and charge the difference.

The pitfall? If you just call stripe.subscriptions.update(), Stripe's default proration behavior might immediately charge the user for the full new amount, ignoring their existing credit, or it might change their billing cycle anchor.

Here is how you handle a mid-cycle upgrade safely:

export async function upgradeSubscription(
  subscriptionId: string,
  newPriceId: string
) {
  const subscription = await stripe.subscriptions.retrieve(subscriptionId);
  const currentItem = subscription.items.data[0];

  try {
    const updatedSubscription = await stripe.subscriptions.update(
      subscriptionId,
      {
        items: [
          {
            id: currentItem.id,
            price: newPriceId,
          },
        ],
        proration_behavior: 'create_prorations',
        billing_cycle_anchor: 'unchanged',
        payment_behavior: 'default_incomplete',
      }
    );

    return updatedSubscription;
  } catch (error) {
    console.error('Failed to update subscription:', error);
    throw error;
  }
}

The billing_cycle_anchor: 'unchanged' parameter is the unsung hero here. Without it, a user who upgraded on the 15th of the month would suddenly have their billing date shifted to the 15th of every future month, breaking their accounting expectations.

Handling Edge Cases: Failed Payments and Dunning

What happens when a credit card expires? If you immediately revoke access, you create a terrible user experience for a simple banking hiccup.

Stripe's Smart Retries and Dunning emails handle the communication, but your application needs to respect the past_due status.

When processing the customer.subscription.updated webhook, check the status field.

function handleSubscriptionUpdate(subscription: Stripe.Subscription) {
  if (subscription.status === 'active') {
    grantFullAccess(subscription.customer);
  } else if (subscription.status === 'past_due') {
    // Show a warning banner in the UI, but DO NOT revoke access yet.
    flagAccountForSoftWarning(subscription.customer);
  } else if (subscription.status === 'canceled' || subscription.status === 'unpaid') {
    revokeAccess(subscription.customer);
  }
}

Always configure your Stripe Dashboard to keep subscriptions in past_due for at least 3-7 days before transitioning them to canceled. This gives Smart Retries time to work its magic.

Performance Considerations and Best Practices

Database Indexing: Ensure your subscriptions, customers, and invoices tables have indexes on the stripe_id columns. Webhook workers will query these constantly.
Avoid N+1 Queries in Workers: When a webhook updates a subscription, don't fetch the customer, then the subscription, then the invoices in separate queries. Use JOINs or dataloaders.
Dead Letter Queues (DLQ): If a webhook fails processing 3 times, move it to a DLQ. Don't let a poisoned message block your entire billing queue.

Key Takeaways

Never process webhooks synchronously. Always use a queue to handle retries and out-of-order delivery.
Enforce idempotency everywhere. Use Redis keys for webhook events and deterministic fingerprints for usage meters.
Protect the billing cycle anchor. When updating subscriptions, explicitly set billing_cycle_anchor: 'unchanged' to prevent shifting billing dates.
Graceful degradation for payments. Respect the past_due status and rely on Stripe's Smart Retries rather than immediately cutting off user access.

Building a billing system is an exercise in paranoia. You have to assume the network will fail, webhooks will duplicate, and users will change their cards at the worst possible time.

When I was architecting the billing layer for PubliFlow (publiflow.vip), a Next.js 15 SaaS Starter Kit I've been developing, the webhook ordering issue was my biggest headache. I initially processed them synchronously and ended up with users losing access for a few seconds during upgrades. Moving to a Redis-backed queue with strict idempotency checks completely solved it. It's patterns like these—born from actual production fires—that I've baked directly into the starter kit to save other developers from the same pain.

Treat your billing architecture with the same rigor as your core product logic, and your revenue (and your sanity) will thank you.

Mastering Supabase Auth and Row Level Security for Multi-Tenant SaaS

PubliFlow — Sat, 01 Aug 2026 01:19:13 +0000

Mastering Supabase Auth and Row Level Security for Multi-Tenant SaaS

If you have ever experienced the 3 AM panic of realizing Tenant A might have just accessed Tenant B's data, you know the sheer terror of multi-tenant data leaks. When building SaaS products, application-level security—where your Node.js or Next.js backend checks if a user has access before querying the database—is a fragile illusion. A single missed WHERE clause or a forgotten middleware check can lead to a catastrophic breach.

This is where Supabase Auth combined with PostgreSQL Row Level Security (RLS) becomes your ultimate safety net. By pushing authorization down to the database layer, you ensure that no matter what happens in your application code, the database will never leak unauthorized data.

In this guide, we will dive deep into architecting a secure, high-performance multi-tenant SaaS using Supabase. We will cover robust data modeling, injecting custom claims into JWTs, and writing database-level tests for your RLS policies.

Architecture: How Supabase Auth Talks to Postgres

Before writing code, we must understand the flow. When a user logs in via Supabase Auth, they receive a JSON Web Token (JWT). When your frontend makes a request to the Postgres database (via the Supabase client or PostgREST), this JWT is passed in the Authorization header.

PostgreSQL intercepts this request. Through a custom GUC (Grand Unified Configuration) variable, Postgres exposes the decoded JWT claims to your RLS policies via the auth.jwt() function. Your RLS policies then evaluate these claims against the row data to determine access.

This means your database is entirely self-sufficient for authorization. It does not need to call your application server to verify permissions.

Deep Dive 1: Designing a Bulletproof RLS Data Model

A common mistake in multi-tenant SaaS is tying permissions directly to the user. In reality, users belong to organizations (tenants), and their permissions are scoped to that organization.

Let's design a schema that enforces this relationship strictly.

-- 1. Create the organizations table
CREATE TABLE public.organizations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- 2. Create a mapping table for users and organizations
CREATE TABLE public.org_members (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID REFERENCES public.organizations(id) ON DELETE CASCADE,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  role TEXT NOT NULL CHECK (role IN ('owner', 'admin', 'member')),
  UNIQUE(org_id, user_id)
);

-- 3. Create a tenant-scoped resource table
CREATE TABLE public.documents (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  org_id UUID NOT NULL REFERENCES public.organizations(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  content TEXT,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- 4. Enable RLS on all tables
ALTER TABLE public.organizations ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.org_members ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;

Now, let's write the RLS policies. The golden rule of RLS is to always filter by the tenant ID (org_id) and verify the user's membership.

-- Policy for documents: Users can only see documents in their organizations
CREATE POLICY "Users can view documents in their orgs" 
ON public.documents 
FOR SELECT 
USING (
  org_id IN (
    SELECT org_id FROM public.org_members WHERE user_id = auth.uid()
  )
);

-- Policy for documents: Only admins and owners can update
CREATE POLICY "Admins and owners can update documents" 
ON public.documents 
FOR UPDATE 
USING (
  org_id IN (
    SELECT org_id FROM public.org_members 
    WHERE user_id = auth.uid() AND role IN ('admin', 'owner')
  )
);

-- Policy for org_members: Users can see their own memberships
CREATE POLICY "Users can view their own memberships" 
ON public.org_members 
FOR SELECT 
USING (user_id = auth.uid());

Notice that we didn't just check auth.uid(). We joined against org_members to ensure the user actually belongs to the organization that owns the document. This is the core of multi-tenant isolation.

Deep Dive 2: Injecting Custom Claims via Supabase Auth Hooks

While the subquery approach above works, running a SELECT inside an RLS policy for every single row can become a performance bottleneck at scale. Furthermore, what if you need to enforce role-based access control (RBAC) where the user's role is checked frequently?

Instead of querying the database on every request, we can inject the user's active org_id and role directly into the JWT as custom claims using Supabase Auth Hooks.

Supabase Auth Hooks allow you to intercept the token creation process. We will write a Deno Edge Function to fetch the user's primary organization and inject it into the JWT.

// supabase/functions/auth-hook/index.ts
import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'

serve(async (req) => {
  const { user, auth_event } = await req.json()

  // Initialize admin client to bypass RLS for reading user data
  const supabaseAdmin = createClient(
    Deno.env.get('SUPABASE_URL') ?? '',
    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? ''
  )

  let customClaims = {}

  if (auth_event.action === 'token_refreshed' || auth_event.action === 'signup') {
    // Fetch the user's primary organization and role
    const { data: membership } = await supabaseAdmin
      .from('org_members')
      .select('org_id, role')
      .eq('user_id', user.id)
      .limit(1)
      .single()

    if (membership) {
      customClaims = {
        org_id: membership.org_id,
        role: membership.role
      }
    }
  }

  return {
    claims: customClaims
  }
})

Once this hook is deployed and configured in your Supabase dashboard, every JWT issued to the user will contain org_id and role. Your RLS policies become incredibly simple and blazing fast:

CREATE POLICY "Fast document view policy" 
ON public.documents 
FOR SELECT 
USING (org_id = (auth.jwt() ->> 'org_id')::UUID);

By moving the tenant resolution to the JWT, we eliminate database joins inside the RLS policy, drastically reducing query execution time.

Deep Dive 3: Testing RLS Policies Without the API

One of the biggest pitfalls developers face with RLS is assuming it works because the API returns the correct data. But what if a developer writes a raw SQL query in a migration script? What if a new policy inadvertently opens up data?

You must test RLS at the database level. Fortunately, Postgres allows us to mock the auth.jwt() context using set_config.

Here is a robust testing strategy using raw SQL. You can run this in your Supabase SQL Editor or integrate it into your CI/CD pipeline.

-- 1. Create a test user in auth.users (if not using a test framework that handles this)
-- For this example, assume we have a user with ID '11111111-1111-1111-1111-111111111111'

-- 2. Mock the JWT for User A (Org 1, Admin)
SELECT set_config('request.jwt.claims', '{"sub": "11111111-1111-1111-1111-111111111111", "org_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "role": "admin"}', true);

-- 3. Attempt to select documents
-- This should return documents for Org A, but NOT Org B
SELECT id, org_id, title FROM public.documents;

-- 4. Assert the results (in a real test runner, you would check the row count)
-- If this returns rows with org_id != 'aaaaaaaa...', your RLS is broken.

-- 5. Now, switch context to User B (Org 2, Member)
SELECT set_config('request.jwt.claims', '{"sub": "22222222-2222-2222-2222-222222222222", "org_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "role": "member"}', true);

-- 6. Attempt an UPDATE on Org A's document
-- This should fail with a policy violation or return 0 rows updated
UPDATE public.documents SET title = 'Hacked' WHERE org_id = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';

-- 7. Reset the context after testing
SELECT set_config('request.jwt.claims', '', true);

This pattern allows you to write comprehensive integration tests for your security policies without needing to spin up the entire Supabase stack or mock HTTP requests. It tests the exact boundary where data leaks actually happen.

Performance Considerations and Common Pitfalls

While RLS is powerful, it introduces specific performance characteristics that mid-to-senior developers must navigate.

1. The Indexing Trap

RLS policies are essentially WHERE clauses appended to every query. If your policy filters by org_id, you must have an index on org_id. Without it, Postgres will perform a sequential scan on every table, bringing your database to its knees as data grows.

-- Always index your RLS filter columns!
CREATE INDEX idx_documents_org_id ON public.documents(org_id);
CREATE INDEX idx_org_members_user_id ON public.org_members(user_id);

2. The `security definer` Bypass

If you create a Postgres function with SECURITY DEFINER, it executes with the privileges of the user who created the function (usually postgres), completely bypassing RLS. If you must use SECURITY DEFINER (e.g., for a function that inserts into auth.users), ensure you explicitly set the search_path and manually re-apply RLS checks inside the function, or restrict its usage strictly.

3. JWT Bloat and Caching

If you inject too many custom claims into the JWT, the token size grows. Since the JWT is sent in the header of every request, bloated tokens increase latency and bandwidth. Furthermore, remember that JWTs are cached. If a user's role changes from 'member' to 'admin', the change won't reflect until their token expires or is refreshed. Always implement a mechanism to force token refresh when critical permissions change.

Key Takeaways

Never trust application-level security for multi-tenant data. Push authorization down to the database using RLS.
Design your schema around tenants. Use mapping tables (org_members) to link users to organizations, rather than assigning resources directly to users.
Optimize RLS with Custom Claims. Use Supabase Auth Hooks to inject tenant IDs and roles into the JWT, avoiding expensive joins inside your RLS policies.
Test at the database layer. Use set_config to mock JWTs and write SQL-based tests for your RLS policies. API tests are not enough.
Index your filter columns. RLS policies without corresponding database indexes will destroy your query performance.

When I was architecting the multi-tenant isolation for PubliFlow (publiflow.vip), a Next.js 15 SaaS starter kit I recently built, I found that relying solely on API-level tests was a massive blind spot. Implementing these exact SQL-based RLS testing patterns at the database level saved us from a critical data leak during load testing, proving that database-enforced security is the only true safety net. Building a SaaS is hard enough; let PostgreSQL do the heavy lifting for your security.

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

PubliFlow — Fri, 31 Jul 2026 01:51:49 +0000

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

For years, the React ecosystem relied on a predictable but verbose pattern for data mutations: build an API route, write a client-side fetch call, manage loading states, handle errors, and invalidate your cache. It worked, but it fractured our mental model. We were writing backend logic in one file and frontend state management in another, bridging them with HTTP.

Next.js Server Actions fundamentally shift this paradigm. By Next.js 15, Server Actions have matured from an experimental feature into the definitive, production-ready way to handle mutations. They allow us to write backend logic that can be invoked directly from our React components, collapsing the client-server boundary.

But as with any powerful abstraction, the magic can lead to misconceptions. If you treat Server Actions like standard JavaScript function calls, you will hit serialization walls, performance bottlenecks, and security vulnerabilities. This deep dive will explore the underlying mechanics of Next.js 15 Server Actions and provide battle-tested patterns for form handling, optimistic updates, and progressive enhancement.

Under the Hood: RPC over HTTP

To use Server Actions effectively, you must understand what happens when you invoke one. Server Actions are not magical local function calls; they are Remote Procedure Calls (RPC) over HTTP.

When a Client Component invokes a Server Action:

Next.js intercepts the function call.
It serializes the arguments passed to the action.
It sends an HTTP POST request to the current URL (or a specific action endpoint) with the serialized payload.
The server executes the action, interacts with your database or external APIs, and generates a response.
The server sends back a React Server Component (RSC) payload, which the client uses to patch the DOM and update the state.

Understanding this HTTP round-trip is crucial. It explains why you cannot pass non-serializable objects (like class instances or functions) as arguments, and why every Server Action invocation incurs a network request.

Pattern 1: Robust Form Handling with `useActionState`

In Next.js 15, useFormState has been officially renamed to useActionState, reflecting its broader utility beyond just forms. The most common pitfall developers face is returning raw errors or untyped data from a Server Action.

For SaaS applications, we need strict validation and predictable state shapes. We achieve this by combining Server Actions with Zod for schema validation.

The Server Action

First, define the action. Notice how we return a predictable state object rather than throwing errors for expected validation failures.

// app/actions/update-profile.ts
'use server';

import { z } from 'zod';
import { revalidatePath } from 'next/cache';
import { db } from '@/lib/db';
import { auth } from '@/lib/auth';

const ProfileSchema = z.object({
  displayName: z.string().min(2).max(50),
  bio: z.string().max(280).optional(),
});

type ActionState = {
  success: boolean;
  message: string;
  errors?: Record<string, string[]>;
};

export async function updateProfile(
  prevState: ActionState,
  formData: FormData
): Promise<ActionState> {
  const session = await auth();
  if (!session?.user?.id) {
    return { success: false, message: 'Unauthorized' };
  }

  const rawData = {
    displayName: formData.get('displayName'),
    bio: formData.get('bio'),
  };

  const validation = ProfileSchema.safeParse(rawData);

  if (!validation.success) {
    return {
      success: false,
      message: 'Invalid input',
      errors: validation.error.flatten().fieldErrors,
    };
  }

  try {
    await db.user.update({
      where: { id: session.user.id },
      data: validation.data,
    });

    revalidatePath('/dashboard/settings');
    return { success: true, message: 'Profile updated successfully' };
  } catch (error) {
    return { success: false, message: 'Database error. Please try again.' };
  }
}

The Client Component

On the client, we use useActionState to manage the submission lifecycle. This replaces the need for manual useState for loading and error states.

// app/dashboard/settings/profile-form.tsx
'use client';

import { useActionState } from 'react';
import { updateProfile } from '@/app/actions/update-profile';
import { useFormStatus } from 'react-dom';

const initialState = {
  success: false,
  message: '',
};

function SubmitButton() {
  const { pending } = useFormStatus();
  return (
    <button type="submit" disabled={pending} className="btn-primary">
      {pending ? 'Saving...' : 'Save Changes'}
    </button>
  );
}

export function ProfileForm() {
  const [state, formAction] = useActionState(updateProfile, initialState);

  return (
    <form action={formAction} className="space-y-4">
      <div>
        <label htmlFor="displayName">Display Name</label>
        <input id="displayName" name="displayName" defaultValue="John Doe" />
        {state.errors?.displayName && (
          <p className="text-red-500">{state.errors.displayName[0]}</p>
        )}
      </div>

      <div>
        <label htmlFor="bio">Bio</label>
        <textarea id="bio" name="bio" defaultValue="Software engineer" />
      </div>

      {state.message && (
        <p className={state.success ? 'text-green-600' : 'text-red-600'}>
          {state.message}
        </p>
      )}

      <SubmitButton />
    </form>
  );
}

Why this works: By returning a typed ActionState, we maintain a single source of truth for the form's status. The useFormStatus hook allows us to create isolated components (like the submit button) that react to the form's pending state without prop drilling.

Pattern 2: Optimistic Updates for Instant UI

SaaS dashboards need to feel snappy. Waiting 400ms for a server round-trip before updating a toggle or adding an item to a list feels sluggish. Next.js 15 provides the useOptimistic hook to update the UI immediately, rolling back if the Server Action fails.

Let's look at a task management feature where users can toggle a task's completion status.

// app/dashboard/tasks/task-list.tsx
'use client';

import { useOptimistic, useActionState, startTransition } from 'react';
import { toggleTaskStatus } from '@/app/actions/tasks';

type Task = {
  id: string;
  title: string;
  isCompleted: boolean;
};

export function TaskList({ initialTasks }: { initialTasks: Task[] }) {
  // 1. Set up optimistic state
  const [optimisticTasks, setOptimisticTasks] = useOptimistic(
    initialTasks,
    (state, updatedTaskId: string) => {
      return state.map((task) =>
        task.id === updatedTaskId
          ? { ...task, isCompleted: !task.isCompleted }
          : task
      );
    }
  );

  // 2. Wrap the server action to trigger the optimistic update
  async function handleToggle(formData: FormData) {
    const taskId = formData.get('taskId') as string;

    // Trigger optimistic update immediately
    startTransition(() => {
      setOptimisticTasks(taskId);
    });

    // Execute server action
    await toggleTaskStatus(formData);
  }

  return (
    <ul className="space-y-2">
      {optimisticTasks.map((task) => (
        <li key={task.id} className="flex items-center gap-3">
          <form action={handleToggle}>
            <input type="hidden" name="taskId" value={task.id} />
            <button type="submit" className="focus:outline-none">
              <span className={task.isCompleted ? 'line-through text-gray-400' : 'text-gray-900'}>
                {task.title}
              </span>
            </button>
          </form>
        </li>
      ))}
    </ul>
  );
}

The Mechanics of useOptimistic:
When startTransition is called, React immediately applies the reducer function to create a new optimistic state. The UI updates instantly. Simultaneously, the Server Action fires. If the server action succeeds, the component re-renders with the actual server data (which should match the optimistic data). If it fails, React automatically discards the optimistic state and reverts to the previous state.

Pattern 3: Progressive Enhancement and Revalidation

A major advantage of Server Actions over traditional fetch calls is Progressive Enhancement. Because Server Actions are fundamentally tied to HTML forms, they work even if JavaScript fails to load or is disabled.

However, to make this truly robust, we must handle redirects and revalidation correctly.

// app/actions/create-project.ts
'use server';

import { redirect } from 'next/navigation';
import { revalidateTag } from 'next/cache';
import { db } from '@/lib/db';

export async function createProject(formData: FormData) {
  const name = formData.get('name') as string;

  if (!name) {
    // For progressive enhancement, we can't just return an error state 
    // if we want to redirect. We must handle it via URL search params 
    // or rely on client-side JS for complex error UI.
    // Here, we assume basic validation passes.
    return;
  }

  const project = await db.project.create({
    data: { name, ownerId: 'user_123' },
  });

  // Granular revalidation using tags
  revalidateTag('projects-list');

  // Redirect to the new project
  redirect(`/projects/${project.id}`);
}

// app/projects/new-page.tsx
import { createProject } from '@/app/actions/create-project';

export default function NewProjectPage() {
  return (
    <div className="max-w-md mx-auto mt-10">
      <h1 className="text-2xl font-bold mb-4">Create New Project</h1>
      {/* This form works perfectly without JS! */}
      <form action={createProject} className="space-y-4">
        <input 
          name="name" 
          placeholder="Project Name" 
          className="w-full p-2 border rounded"
          required
        />
        <button type="submit" className="w-full bg-blue-600 text-white p-2 rounded">
          Create Project
        </button>
      </form>
    </div>
  );
}

Why this matters: By using redirect and revalidateTag inside the Server Action, the server handles the entire lifecycle. If the user has JS disabled, the form submits, the server creates the project, invalidates the cache tag, and sends a 303 See Other redirect to the new project page. The browser handles it natively. When JS is enabled, Next.js intercepts the form submission, performs the action via RPC, and handles the redirect client-side via the router.

Common Pitfalls and Performance Considerations

1. The Serialization Trap

Pitfall: Attempting to pass complex objects, Dates, or Maps directly to a Server Action.
Solution: Server Actions use a custom serialization protocol. While it handles primitives, arrays, and plain objects, it struggles with complex types. Pass IDs or primitive values, and re-fetch the complex data on the server.

2. Over-Revalidating

Pitfall: Using revalidatePath('/') after every mutation, which clears the entire router cache and forces a full data refetch.
Solution: Use revalidateTag for granular cache invalidation. Tag your data fetches (e.g., fetch('...', { next: { tags: ['projects'] } })) and only revalidate the specific tag that changed.

3. Security and Authorization

Pitfall: Hiding a "Delete" button in the UI and assuming the Server Action is secure because the button isn't visible.
Solution: Server Actions are just HTTP endpoints. A malicious user can inspect the network tab, find the action ID, and invoke it directly with curl. Always verify authentication and authorization inside the Server Action itself. Never trust the client.

4. Stale Closures in Client Components

Pitfall: Passing a client-side state variable into a Server Action, only to find the server receives an outdated value.
Solution: Because Server Actions are serialized and sent over the network, they capture the state at the time of invocation. If you need the most current state, pass it explicitly via FormData or ensure the state is updated before the action is called.

Key Takeaways

Think RPC, not REST: Server Actions are remote procedure calls. Treat them as such by passing primitives and handling serialization limits.
Embrace useActionState: It replaces boilerplate loading and error states, providing a unified way to handle form submissions and mutations.
Optimistic UI is a first-class citizen: Use useOptimistic combined with startTransition to make your SaaS dashboard feel instantaneous.
Progressive Enhancement is free: By relying on standard HTML forms and action attributes, you get robust fallbacks for free.
Security is your responsibility: Always enforce authorization checks inside the Server Action. The UI is just a suggestion.

These aren't just theoretical concepts. When I was architecting the dashboard mutations, billing forms, and team management features for PubliFlow (publiflow.vip), a Next.js 15 SaaS starter kit I've been building, these exact patterns were the backbone of the user experience. Getting the optimistic UI to roll back correctly on Stripe webhook failures was a specific challenge that the useOptimistic hook solved elegantly, and relying on progressive enhancement for the critical auth flows saved us from edge-case bugs. If you're building a SaaS and want to see how these Server Action patterns integrate with auth, database ORM, and billing in a production-ready codebase, checking out the starter might save you some late nights.

Next.js 15 has turned Server Actions into a mature, powerful tool. By understanding the underlying mechanics and applying these patterns, you can build SaaS applications that are not only faster and more responsive but also fundamentally more robust.

I Built an 8-Layer Memory Architecture for AI Agents — Here's Why

PubliFlow — Mon, 20 Jul 2026 11:49:58 +0000

I Built an 8-Layer Memory Architecture for AI Agents — Here's Why

Every AI agent I've ever worked with has the same fatal flaw: it forgets.

Close the session? Gone. New conversation? Start from zero. Even within a single session, important context slowly rots as the token window fills up and earlier instructions get evicted.

We've all been there — re-explaining your preferences for the third time this week, watching an agent repeat the same mistake it made yesterday, or seeing it miss a critical dependency because it has no way to connect past events to current decisions.

That's why I spent the last several months building EdosAI — an 8-layer cognitive memory architecture that gives AI agents the thing they need most: persistent, structured, reasoning-capable memory.

The Problem: Stateless Intelligence is an Oxymoron

Let's be honest. Most "AI agents" today are just stateless LLM wrappers with a fancy prompt. They might have:

A conversation buffer (resets every session)
A vector store (chunks of text, no structure)
Maybe a RAG pipeline (retrieval, not reasoning)

None of this is memory. It's caching. Real memory — the kind humans have — does way more than retrieve similar text. It:

Connects events across time (episodic recall)
Abstracts patterns from experience (semantic knowledge)
Learns workflows by doing (procedural skill)
Monitors its own performance (meta-cognition)
Understands cause and effect (causal reasoning)
Stays aligned with user values (alignment)

That's six distinct cognitive functions above raw perception and short-term context. Which means we need at least eight layers to do this right.

The Architecture: 8 Layers, Zero Amnesia

Here's the stack, bottom to top:

🔴 L0 — Perception Layer (Instant State Buffer)
The sensory input. Real-time state snapshots — what's happening right now. Fast, ephemeral, overwritten constantly. Like your brain's sensory register.

🟠 L1 — Short-Term Memory (Context Window)
The working memory. Holds the current conversation, task state, and recent context. Maps directly to the LLM's context window but with intelligent management — importance scoring, sliding windows, and compression.

🟡 L2 — Episodic Memory (Event Recall)
The diary. Stores timestamped events and experiences — what happened, when, and in what sequence. Enables temporal queries: "What did we decide about the database schema last Tuesday?"

🟢 L3 — Semantic Memory (ChromaDB Vectors)
The encyclopedia. Abstracted knowledge, facts, and relationships stored as vector embeddings in ChromaDB. Supports semantic search, entity resolution, and knowledge graph traversal.

🔵 L4 — Procedural Memory (Learned Workflows)
The muscle memory. Stores successful workflow patterns, tool-use sequences, and behavioral strategies. The agent gets better at tasks over time — not by being told how, but by remembering what worked.

🟣 L5 — Meta-Cognitive Layer (Self-Monitoring)
The inner critic. Monitors the agent's own reasoning quality, tracks confidence levels, detects contradictions, and triggers self-correction. The agent knows when it doesn't know.

🟤 L6 — Causal Reasoning Engine
The detective. Goes beyond correlation to model actual cause-and-effect relationships. If the agent observes that "deploying on Fridays causes outages," it can reason about why and make better decisions — not just avoid Fridays statistically.

🩷 L7 — Value Alignment (Constitutional AI)
The conscience. Ensures the agent's behavior stays aligned with user-defined values, ethical boundaries, and organizational policies. Not just rules — a living value system that the agent reasons about and respects.

What's Under the Hood

This isn't a weekend hack. The full system comprises:

23,000+ lines of Python across 51 modules
40+ test suites covering edge cases from memory decay to cross-context transfer
ChromaDB for semantic vector retrieval
Causal graph reasoning with explicit cause-effect chains
Constitutional AI self-healing engine
Cross-context transfer — lessons learned in one domain apply to another
OCEAN personality model integration — agents don't just remember facts, they maintain consistent behavioral patterns modeled on the Big Five personality dimensions (Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism)

Why OCEAN? Because an agent that changes its "personality" every session isn't reliable. Users need consistency. The Big Five gives us an empirically validated, tunable framework for engineering stable agent behavior — not random, but designed.

Why This Matters Right Now

If you think AI memory is a niche problem, consider this: MemTensor just closed a 100M+ RMB (~$14M) Pre-A round for MemOS, their memory operating system for AI agents. Investors include Huawei's venture arm, Honor, SenseTime, and Shenzhen Capital. Their thesis? Memory is becoming the infrastructure layer for the entire agent ecosystem.

They're right. The market is validating what we've been building: AI without persistent memory is a toy. AI with structured memory is a tool. And the gap between the two is where real products live.

MemTensor's approach is top-down — a full operating system for memory lifecycle management. Our approach at EdosAI is more granular: an 8-layer cognitive stack that you can plug into any agent framework, from LangChain to AutoGen to custom setups. Different starting points, same destination: agents that remember.

What You Can Do With This

Imagine an AI agent that:

Remembers your coding preferences across sessions and applies them without being told
Notices when a recurring bug pattern matches a past incident and proactively suggests the fix
Tracks its own error rate on different task types and adjusts its approach
Understands that your morning standup constraint means it shouldn't schedule deployments at 9 AM
Refuses to execute a command that conflicts with your stated security policies — not because of a hardcoded rule, but because it reasoned about alignment

That's not science fiction. That's what layered memory enables.

Ship It

If you're building AI agents and hitting the "amnesia wall," we've got three ways to get started:

SaaS API — $299/mo, cloud-hosted, full 8-layer stack, 10K requests/month
Compiled SDK — $2,999 one-time, self-hosted binary, permanent license, unlimited requests
Source License — $9,999 one-time, full source code + commercial rights

👉 Check out the pricing →

The memory problem isn't going away. Context windows will get bigger, RAG will get faster, but neither solves the fundamental issue: agents need structured, causal, self-aware memory — not just bigger buffers.

We built EdosAI because we were tired of agents that were smart but forgetful. If you're tired of it too, let's fix this together.

Building AI tools? Follow along at shopveigo.com or reach out — I'm always happy to talk memory architectures, agent design, or why your AI keeps forgetting your name.

I Built an 8-Layer Memory Architecture for AI Agents — Here's Why

PubliFlow — Mon, 20 Jul 2026 11:38:11 +0000

I Built an 8-Layer Memory Architecture for AI Agents — Here's Why

Every AI agent I've ever worked with has the same fatal flaw: it forgets.

Close the session? Gone. New conversation? Start from zero. Even within a single session, important context slowly rots as the token window fills up and earlier instructions get evicted.

The Problem: Stateless Intelligence is an Oxymoron

Let's be honest. Most "AI agents" today are just stateless LLM wrappers with a fancy prompt. They might have:

A conversation buffer (resets every session)
A vector store (chunks of text, no structure)
Maybe a RAG pipeline (retrieval, not reasoning)

None of this is memory. It's caching. Real memory — the kind humans have — does way more than retrieve similar text. It:

Connects events across time (episodic recall)
Abstracts patterns from experience (semantic knowledge)
Learns workflows by doing (procedural skill)
Monitors its own performance (meta-cognition)
Understands cause and effect (causal reasoning)
Stays aligned with user values (alignment)

That's six distinct cognitive functions above raw perception and short-term context. Which means we need at least eight layers to do this right.

The Architecture: 8 Layers, Zero Amnesia

Here's the stack, bottom to top:

What's Under the Hood

This isn't a weekend hack. The full system comprises:

23,000+ lines of Python across 51 modules
40+ test suites covering edge cases from memory decay to cross-context transfer
ChromaDB for semantic vector retrieval
Causal graph reasoning with explicit cause-effect chains
Constitutional AI self-healing engine
Cross-context transfer — lessons learned in one domain apply to another
OCEAN personality model integration — agents don't just remember facts, they maintain consistent behavioral patterns modeled on the Big Five personality dimensions (Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism)

Why This Matters Right Now

What You Can Do With This

Imagine an AI agent that:

Remembers your coding preferences across sessions and applies them without being told
Notices when a recurring bug pattern matches a past incident and proactively suggests the fix
Tracks its own error rate on different task types and adjusts its approach
Understands that your morning standup constraint means it shouldn't schedule deployments at 9 AM
Refuses to execute a command that conflicts with your stated security policies — not because of a hardcoded rule, but because it reasoned about alignment

That's not science fiction. That's what layered memory enables.

Ship It

If you're building AI agents and hitting the "amnesia wall," we've got three ways to get started:

SaaS API — $299/mo, cloud-hosted, full 8-layer stack, 10K requests/month
Compiled SDK — $2,999 one-time, self-hosted binary, permanent license, unlimited requests
Source License — $9,999 one-time, full source code + commercial rights

👉 Check out the pricing →

We built EdosAI because we were tired of agents that were smart but forgetful. If you're tired of it too, let's fix this together.

Building AI tools? Follow along at shopveigo.com or reach out — I'm always happy to talk memory architectures, agent design, or why your AI keeps forgetting your name.

I Built a Brain for AI Agents — 8 Cognitive Layers, 23,000+ Lines, Zero Bullshit

PubliFlow — Sun, 19 Jul 2026 13:07:42 +0000

I Built a Brain for AI Agents — 8 Cognitive Layers, 23,000+ Lines, Zero Bullshit

Your AI Agent Has an Amnesia Problem

Let's cut through the hype.

Every AI agent you've built? It has the memory of a goldfish.

You stuff it with RAG. You chain prompts. You call it "context-aware." But ask it what happened three weeks ago — silence. Ask it why it made that decision last Tuesday — blank stare. Ask it to learn from its mistakes — déjà vu, every single time.

That's not intelligence. That's a parrot with a search engine.

Real intelligence requires real memory. Not just "recall this document." I mean:

🧠 Remembering why something happened, not just what
🔮 Predicting what could have happened (counterfactual reasoning)
🪞 Knowing who it is across sessions — persistent identity
🎯 Evaluating its own confidence — knowing when it's bullshitting you

I spent 6 months building this from scratch. The result? EdosAI — an 8-layer cognitive memory architecture that gives AI agents something they've never had before: a mind.

The Architecture That Changes Everything

╔═══════════════════════════════════════════════╗
║  L8  Value Alignment — Constitutional AI     ║
║  L7  Self-Consciousness — Identity & Goals   ║
║  L6  Causal Reasoning — Counterfactual Engine ║
║  L5  Meta-Cognition — Self-Monitoring         ║
║  L4  Procedural Memory — Learned Workflows    ║
║  L3  Semantic Memory — Vectors + Knowledge Graph║
║  L2  Episodic Memory — Temporal Event Index   ║
║  L1  Working Memory — Dynamic Context Window  ║
║  L0  Perception — Real-Time Sensory Buffer    ║
╚═══════════════════════════════════════════════╝

23,000+ lines. 51 production modules. 40+ test suites. This is not a demo.

Where It Gets Dangerous (In a Good Way)

L5 — Meta-Cognition: Your Agent Knows When It's Lying

This isn't just "confidence scoring." This is your agent evaluating its own reasoning chain in real-time, flagging hallucinations before they reach the user. It knows what it doesn't know. That alone is worth the price of admission.

L6 — Causal Reasoning: Beyond Correlation

Most agents pattern-match. EdosAI reasons. It builds causal graphs, models cause-and-effect chains, and runs counterfactual simulations. "What would have happened if I took a different action?" — your agent can now answer that question.

L7 — Self-Consciousness: Identity That Survives Reboots

Based on Global Workspace Theory. Your agent maintains persistent identity across sessions. It has goals. It has values. It evolves. It knows who it is — and it remembers.

Battle-Tested Infrastructure

This isn't a weekend hack held together with prayers:

ChromaDB — Sub-second semantic vector search
PostgreSQL — Relational integrity you can trust
Constitutional AI — Safety baked into the foundation, not bolted on
51 independent modules — Plug in what you need, leave the rest
Full TypeScript types — Your IDE will thank you
Modular architecture — Use 2 layers or all 8

The Pricing (Because "Free" Kills Projects)

I've watched too many brilliant open-source projects die from maintainer burnout. This is built to last, and that requires sustainable funding.

Tier	Price	What You Get
SaaS API	$299/mo	Cloud-hosted. Zero setup. Full 8-layer access via REST API.
Compiled SDK	$2,999 one-time	Cython-compiled binaries. Deploy on your own infra. Permanent license.
Source License	$9,999 one-time	Full source code. Modify it. Customize it. Make it yours.

No enterprise sales calls. No "contact us for pricing" games. No bait-and-switch.

This Is For You If...

🏗️ You're building AI agents that need to actually remember their users
🚀 You're shipping a product where memory persistence = competitive advantage
🔬 You're researching cognitive architectures and want real code, not papers
🏢 You need production-grade infrastructure, not a Jupyter notebook demo

This Is NOT For You If...

❌ Your chatbot only needs 3-turn conversations
❌ You think chat_history.append() is "memory"
❌ You don't care if your agent has the same conversation 100 times

What's Coming Next

Multi-agent memory sharing — Agents that learn from each other's experiences
Memory compression — 10x storage reduction, zero quality loss
Custom embedding models — Fine-tuned specifically for agent memory patterns
Plugin marketplace — Community-built cognitive extensions

The Bottom Line

AI agents without real memory are just autocomplete with delusions of grandeur.

EdosAI gives your agents a brain — with 8 layers of cognition, persistent identity, causal reasoning, and the ability to know what they don't know.

→ See the full architecture & get started →

I built this because I was tired of the same broken patterns. If you're building something that matters, your agents deserve better than a goldfish brain.

Let's build agents that actually think.

23,000+ lines of code. 51 modules. 8 cognitive layers. 6 months of obsessive engineering. This is what happens when you take AI memory seriously.

AI #MachineLearning #ArtificialIntelligence #AgentFramework #CognitiveArchitecture #IndieHacker #BuildInPublic

I Was Tired of Scattered Classifieds Across 10 Different Sites — So I Built a Free Global Platform

PubliFlow — Sun, 19 Jul 2026 10:23:30 +0000

Moving to a new city is exciting — until you realize how painful it is to find an apartment, a job, or even someone to fix your sink.

Last year, I relocated to Toronto. I spent hours bouncing between Craigslist, Kijiji, Facebook Marketplace, Gumtree, and a dozen other niche boards. Some listings were outdated. Others were outright scams. And every platform had its own quirks, its own spam problems, its own "post and pray" culture.

I thought: why is finding basic life services still so fragmented in 2025?

That frustration became the seed for VEIGO — a free, global classifieds platform built to solve exactly this problem.

The Problem I Kept Running Into

Let me paint the picture. When you move to a new city, you typically need four things fast:

A place to live — rental listings scattered across 5+ sites, with wildly inconsistent formats and photo quality
A job — job boards that either require expensive subscriptions or drown you in irrelevant listings
Gig work or services — finding a plumber, tutor, or delivery driver means asking around on WhatsApp groups or scrolling through sketchy Facebook pages
Tenders and contracts — if you're a freelancer or small business owner, finding local bidding opportunities is like searching for a needle in a haystack

Each of these needs lives on a different platform. None of them talk to each other. And if you're in a foreign country, the language barrier and unfamiliar platforms make it 10x worse.

What I Built: VEIGO

VEIGO is a free global classifieds platform that brings all four of these categories under one roof:

🏠 Rentals

Find apartments, rooms, and houses for rent. Whether you're looking in New York, Los Angeles, Toronto, Sydney, Vancouver, or London — we've got you covered with a clean, searchable interface that doesn't make you squint at tiny photos or deal with auto-playing videos.

💼 Jobs

Post and browse job listings without the noise. VEIGO's job board is designed for clarity — clear titles, clear requirements, clear application process. No premium subscriptions needed to see contact information.

🔧 Gig Work

Need a handyman? Want to offer tutoring? Looking for local delivery gigs? VEIGO's gig section connects service providers with people who need them, without the middleman fees that platforms like TaskRabbit charge.

📋 Tenders & Bids

This is the one people overlook — but if you're a freelancer or small business, finding local tender opportunities is gold. VEIGO aggregates bidding and contract opportunities so you don't have to check 20 government and corporate procurement pages daily.

Why "Free" Isn't a Marketing Gimmick

I get it — "free" usually means "we'll monetize your data" or "free for 30 days, then pay up."

VEIGO is different. The core classifieds platform is completely free to use. Post listings, browse listings, contact people — no hidden fees, no "premium" tiers that gate essential features.

We believe that access to basic classified information — housing, employment, services — should not be locked behind a paywall. Especially when you're in a new city and every dollar counts.

The AI Tools That Make It Smarter

Beyond the classifieds themselves, VEIGO comes with a suite of AI-powered tools at tools.shopveigo.com that make the whole experience smoother:

Smart listing suggestions — describe what you're offering or looking for, and the AI helps you write better listings
Category optimization — the AI helps route your listing to the right category and city so it gets seen by the right people
Search assistance — natural language queries that actually understand what you mean, not just keyword matching

These tools aren't bolted on as an afterthought. They're core to the experience, because the whole point of VEIGO is to reduce friction in finding what you need.

Why This Matters for Indie Hackers and Builders

If you're building something in the classifieds or local services space, you know the challenges:

Trust — how do you verify listings without killing the open nature of the platform?
Coverage — how do you get enough listings in enough cities to be useful?
Monetization — how do you keep the lights on without charging users?

These are problems we're actively working on, and I'd love to connect with other builders in this space. The classifieds market is worth billions globally, yet most platforms still look and feel like they were built in 2005.

What's Next

We're currently live in New York, Los Angeles, Toronto, Sydney, Vancouver, and London, with more cities being added regularly. The platform is mobile-responsive and designed for the way people actually search — quickly, on their phones, while they're on the go.

If you've ever felt the pain of scattered classifieds, or if you're an indie hacker curious about building in this space, I'd love for you to check it out:

👉 VEIGO — Free Global Classifieds
👉 VEIGO AI Tools

Drop a comment if you have questions, feedback, or just want to chat about classifieds tech. I read every one.

Thanks for reading. If this resonated, share it with someone who's about to move to a new city — they'll thank you later.

How I saved $200 on my internet bill using an AI agent

PubliFlow — Sun, 19 Jul 2026 04:14:29 +0000

Last month, my internet bill jumped from $65 to $80. Again.

I called Comcast, waited 45 minutes, and they "found" a $10 discount. I hung up frustrated. Why do I have to do this every 6 months?

So I built an AI agent that does it for me.

The Problem

We all overpay on bills. Internet, phone, insurance, subscriptions â€” they quietly raise rates, hoping you won't notice. Calling customer service is:

Time-consuming (45+ min hold times)
Frustrating (scripted responses, limited authority)
Temporary (discounts expire in 6-12 months)

Most people don't bother negotiating. They just pay.

What I Built

BillSnip â€” an AI agent that:

ðŸ“„ Analyzes your bills (PDF or screenshot)
ðŸ” Finds overcharges and compares competitor pricing
ðŸ“§ Emails your provider with a personalized negotiation
ðŸ”„ Follows up until you get a better rate

How It Works

You upload your bill. The AI:

Extracts key data (provider, plan, price, usage)
Researches competitor pricing in your area
Identifies overcharges (hidden fees, expired promos, rate creep)
Generates a negotiation strategy based on your usage patterns
Emails your provider with a personalized argument

The AI uses DeepSeek for reasoning â€” it's fast, cheap, and good at negotiation language.

My First Test

I uploaded my Comcast bill ($80/month for 200Mbps).

The AI found:

Competitor offering 500Mbps for $65 in my area
My current plan had a "promo rate" that expired 8 months ago
I was paying $15 above market rate

The AI emailed Comcast:

"Hi, I've been a loyal customer for 3 years. I noticed [competitor] is offering 500Mbps for $65 in my area. My current bill is $80 for 200Mbps. Can you match or beat this rate?"

48 hours later, I got a response: $65/month for 500Mbps. Saved $15/month, $180/year.

The Business Model

I considered "percentage of savings" (take 20% of what we save you). But users hate sharing savings with a third party. Creates mistrust.

So I went with prepaid credits:

Buy $10-50 in credits upfront
Each analysis costs 30 credits, each negotiation email costs 20 credits
Credits never expire

Why this works:

Full transparency â€” you know exactly what you're paying
No conflict of interest â€” I'm not incentivized to under-negotiate
Predictable revenue â€” credits = upfront cash flow
User control â€” you choose when to spend

The Tech Stack

Next.js frontend (SSR for SEO)
FastAPI backend
DeepSeek API for AI reasoning
PostgreSQL for storage
Single VPS deployment ($6/month)

Total infrastructure cost: ~$50/month for the first 100 users.

What's Next

Expand to more provider types (insurance, medical, subscriptions)
Auto-switching (not just negotiation â€” actually switch providers for you)
Referral system for viral growth
Membership tiers that get cheaper over time

Try It Free

BillSnip is live at: https://billsnip.publiflow.vip/

Free tier: 100 credits on signup + 3 free bill analyses.

If the AI saves you $50 on a $10 credit purchase, that's a 5x return. Hard to argue with that.

How AI Agents Are Changing Personal Finance Management in 2026

PubliFlow — Sat, 18 Jul 2026 08:43:46 +0000

Personal finance tools have been around for decades — from spreadsheets to Mint to YNAB. But they all share the same fundamental limitation: they require you to do the work. They show you dashboards, send you alerts, and expect you to take action.

That era is ending. In 2026, a new class of tools powered by autonomous AI agents is replacing passive dashboards with active financial assistants that don't just tell you what's wrong — they fix it.

In this post, I'll break down how these systems work under the hood, walk through real code examples, and share what I learned building one.

The Shift: From Passive Dashboards to Autonomous Agents

The key difference between a traditional finance app and an AI agent is the decision loop:

Traditional:  Data → Dashboard → Human reads → Human decides → Human acts
AI Agent:     Data → LLM analysis → Agent decides → Agent acts → Monitors outcome

This isn't incremental. It's a fundamental architecture change. Instead of alerting you that your electricity bill went up 23%, an AI agent investigates why, determines it's because your promotional rate expired, drafts a negotiation email to your provider, sends it, tracks the response, and reports back the savings.

Architecture: Building a Personal Finance AI Agent

Let me walk through the core architecture. There are four main subsystems:

Data Ingestion Layer — Connects to banks, reads emails, parses bills
Analysis Engine — LLM-powered pattern recognition and anomaly detection
Action Planner — Decides what to do and in what order
Execution Layer — Sends emails, makes API calls, schedules follow-ups

Here's the data flow:

Bank APIs / Email / Uploaded Bills
         ↓
   [Data Ingestion]
         ↓
   [Analysis Engine] ← Historical data store
         ↓
   [Action Planner] ← Rule engine + LLM reasoning
         ↓
   [Execution Layer] → SMTP / APIs / Scheduling
         ↓
   [Monitoring & Reporting]

Code Example 1: The Data Ingestion Pipeline

The ingestion layer normalizes financial data from multiple sources into a unified format:

import imapclient
import json
from dataclasses import dataclass
from typing import Optional
from datetime import datetime

@dataclass
class FinancialEvent:
    source: str           # "bank", "email", "bill_upload"
    event_type: str       # "charge", "payment", "bill_received"
    amount: float
    currency: str
    provider: Optional[str]
    description: str
    date: datetime
    raw_data: dict

class BillEmailParser:
    """Parse billing notifications from email inbox."""

    PROVIDER_PATTERNS = {
        "xfinity": ["comcast", "xfinity"],
        "att": ["att.com", "at&t"],
        "verizon": ["verizon", "vzwpix"],
        "state_farm": ["statefarm", "sfemail"],
    }

    def __init__(self, imap_client):
        self.client = imap_client

    def fetch_recent_bills(self, days: int = 30) -> list[FinancialEvent]:
        """Scan inbox for billing-related emails."""
        since_date = datetime.now() - timedelta(days=days)

        self.client.select_folder("INBOX")
        messages = self.client.search(["SINCE", since_date])

        events = []
        for msg_id, data in self.client.fetch(messages, ["ENVELOPE", "BODY[TEXT]"]).items():
            envelope = data[b"ENVELOPE"]
            body_text = data[b"BODY[TEXT]"].decode("utf-8", errors="replace")

            # Detect if this is a billing email
            provider = self._detect_provider(envelope, body_text)
            if not provider:
                continue

            # Extract billing data using LLM
            bill_data = self._extract_with_llm(body_text, provider)
            if bill_data:
                events.append(FinancialEvent(
                    source="email",
                    event_type="bill_received",
                    amount=bill_data["total_amount"],
                    currency="USD",
                    provider=provider,
                    description=bill_data["summary"],
                    date=envelope.date,
                    raw_data=bill_data
                ))

        return events

    def _detect_provider(self, envelope, body_text) -> Optional[str]:
        """Identify the service provider from email metadata."""
        text_to_check = f"{envelope.sender} {envelope.subject} {body_text[:500]}".lower()

        for provider, patterns in self.PROVIDER_PATTERNS.items():
            if any(p in text_to_check for p in patterns):
                return provider
        return None

    def _extract_with_llm(self, body_text: str, provider: str) -> Optional[dict]:
        """Use LLM to extract structured billing data from email."""
        response = openai.chat.completions.create(
            model="gpt-4",
            messages=[
                {"role": "system", "content": """Extract billing information from this email.
                Return JSON with: total_amount, billing_period, line_items[], 
                any_promotional_notes, any_rate_changes."""},
                {"role": "user", "content": body_text[:3000]}
            ],
            temperature=0.1,
            response_format={"type": "json_object"}
        )

        return json.loads(response.choices[0].message.content)

Code Example 2: The Analysis Engine

The analysis engine is where the real intelligence lives. It combines rule-based checks with LLM reasoning to identify savings opportunities:

class FinanceAnalysisEngine:
    """Analyze financial events for optimization opportunities."""

    def __init__(self, llm_client, historical_store):
        self.llm = llm_client
        self.history = historical_store

    def analyze_all(self, events: list[FinancialEvent]) -> list[dict]:
        """Run full analysis across all financial events."""

        opportunities = []

        # Group events by provider
        by_provider = self._group_by_provider(events)

        for provider, provider_events in by_provider.items():
            # Check 1: Price increase detection
            increase = self._detect_price_increase(provider, provider_events)
            if increase:
                opportunities.append({
                    "type": "price_increase",
                    "provider": provider,
                    "amount": increase["delta"],
                    "confidence": 0.92,
                    "action": "negotiate",
                    "context": increase
                })

            # Check 2: Duplicate or double charges
            duplicates = self._detect_duplicates(provider_events)
            for dup in duplicates:
                opportunities.append({
                    "type": "duplicate_charge",
                    "provider": provider,
                    "amount": dup["amount"],
                    "confidence": 0.97,
                    "action": "dispute"
                })

            # Check 3: Subscription creep (gradual increases)
            creep = self._detect_subscription_creep(provider, provider_events)
            if creep:
                opportunities.append({
                    "type": "subscription_creep",
                    "provider": provider,
                    "amount": creep["total_overcharge"],
                    "confidence": 0.85,
                    "action": "renegotiate_or_cancel"
                })

        # Check 4: Cross-provider optimization (LLM-powered)
        switching_savings = self._analyze_switching_opportunities(events)
        opportunities.extend(switching_savings)

        # Rank by expected savings x confidence
        opportunities.sort(
            key=lambda x: x["amount"] * x["confidence"],
            reverse=True
        )

        return opportunities

    def _detect_price_increase(self, provider: str, events: list) -> Optional[dict]:
        """Detect unauthorized or unnotified price increases."""
        bills = sorted(
            [e for e in events if e.event_type == "bill_received"],
            key=lambda x: x.date
        )

        if len(bills) < 2:
            return None

        last_two = bills[-2:]
        delta = last_two[-1].amount - last_two[-2].amount

        if delta > 0 and (delta / last_two[-2].amount) > 0.05:
            return {
                "delta": delta,
                "previous": last_two[-2].amount,
                "current": last_two[-1].amount,
                "percentage": (delta / last_two[-2].amount) * 100
            }
        return None

    def _analyze_switching_opportunities(self, events: list) -> list:
        """Use LLM to identify cheaper alternatives."""
        provider_summary = self._summarize_spending(events)

        response = self.llm.chat.completions.create(
            model="gpt-4",
            messages=[
                {"role": "system", "content": """You are a personal finance expert.
                Given a user's current service providers and monthly costs,
                suggest specific cheaper alternatives with estimated savings.
                Return JSON array of {provider, current_cost, alternative, estimated_cost, savings}."""},
                {"role": "user", "content": json.dumps(provider_summary)}
            ],
            temperature=0.2,
            response_format={"type": "json_object"}
        )

        return json.loads(response.choices[0].message.content).get("recommendations", [])

Code Example 3: The Autonomous Action Planner

This is what makes the system an agent rather than just an analyzer. The action planner decides what to do, sequences the actions, and handles failures:

from enum import Enum
from typing import Callable

class ActionType(Enum):
    NEGOTIATE_BILL = "negotiate_bill"
    DISPUTE_CHARGE = "dispute_charge"
    SWITCH_PROVIDER = "switch_provider"
    CANCEL_SUBSCRIPTION = "cancel_subscription"
    ADJUST_BUDGET = "adjust_budget"
    NOTIFY_USER = "notify_user"

class ActionPlanner:
    """Decides and sequences autonomous financial actions."""

    AUTO_APPROVE_LIMIT = 50.0
    REQUIRE_APPROVAL_LIMIT = 500.0

    def __init__(self, execution_layer, notification_service):
        self.executor = execution_layer
        self.notifier = notification_service

    async def plan_and_execute(self, opportunities: list[dict]):
        """Plan and execute actions for identified opportunities."""

        action_plan = self._create_action_plan(opportunities)

        for step in action_plan:
            needs_approval = self._needs_approval(step)

            if needs_approval:
                approval = await self.notifier.request_approval(
                    action=step["action_type"],
                    provider=step["provider"],
                    estimated_savings=step["estimated_savings"],
                    details=step["rationale"]
                )

                if not approval.granted:
                    continue

            try:
                result = await self._execute_step(step)
                await self._schedule_followup(step, result)
            except ExecutionError as e:
                await self.notifier.alert_failure(step, e)

    def _create_action_plan(self, opportunities: list) -> list:
        """Convert opportunities into sequenced action steps."""
        steps = []

        for opp in opportunities:
            if opp["type"] == "price_increase":
                steps.append({
                    "action_type": ActionType.NEGOTIATE_BILL,
                    "provider": opp["provider"],
                    "estimated_savings": opp["amount"],
                    "rationale": f"Price increased {opp['context']['percentage']:.1f}% without notification",
                    "priority": opp["amount"] * opp["confidence"],
                    "execution": {
                        "method": "email",
                        "template": "negotiate_rate_increase",
                        "template_vars": {
                            "provider": opp["provider"],
                            "increase_amount": opp["amount"],
                            "previous_amount": opp["context"]["previous"]
                        }
                    }
                })

            elif opp["type"] == "duplicate_charge":
                steps.append({
                    "action_type": ActionType.DISPUTE_CHARGE,
                    "provider": opp["provider"],
                    "estimated_savings": opp["amount"],
                    "rationale": f"Duplicate charge of ${opp['amount']:.2f} detected",
                    "priority": opp["amount"] * opp["confidence"]
                })

        steps.sort(key=lambda x: x["priority"], reverse=True)
        return steps

    def _needs_approval(self, step: dict) -> bool:
        """Determine if action requires user approval."""
        savings = step["estimated_savings"]
        action = step["action_type"]

        if action == ActionType.NEGOTIATE_BILL and savings < self.AUTO_APPROVE_LIMIT:
            return False

        if action == ActionType.CANCEL_SUBSCRIPTION:
            return True

        return savings >= self.AUTO_APPROVE_LIMIT

Real-World Performance Data

After running an AI finance agent for 90 days across 12 service providers:

Metric	Without Agent	With Agent	Improvement
Monthly overspend	$247	$43	82.6% reduction
Time spent on finances	3.5 hrs/mo	12 min/mo	94.3% reduction
Missed billing errors	2.1/month	0.08/month	96.2% reduction
Annual savings	—	$2,460	—

The agent identified and recovered $2,460 in annual savings across bill negotiations, duplicate charge disputes, and subscription optimizations. The most impactful action type was bill negotiation — accounting for 61% of total savings.

Key Technical Challenges

1. Hallucination Prevention in Financial Actions

An AI agent that sends emails or disputes charges cannot afford hallucinations. We implement multiple safeguards:

class FinancialGuardrails:
    """Safety checks before executing financial actions."""

    def validate_before_execution(self, action_plan: dict) -> bool:
        # Rule 1: Never exceed account balance
        if action_plan["action_type"] == "dispute_charge":
            disputed_amount = action_plan["amount"]
            if disputed_amount > self.get_account_balance():
                return False

        # Rule 2: Rate of change limiter
        recent_actions = self.get_recent_actions(hours=24)
        if len(recent_actions) >= 3:
            return False  # Max 3 autonomous actions per day

        # Rule 3: Confidence threshold
        if action_plan["confidence"] < 0.85:
            return False

        # Rule 4: LLM self-review
        review = self.llm_review(action_plan)
        if not review["is_appropriate"]:
            return False

        return True

2. Provider Communication Patterns

Different providers respond to different negotiation strategies. The agent maintains a learned database:

NEGOTIATION_STRATEGIES = {
    "xfinity": {
        "best_channel": "email",
        "avg_response_time_days": 5,
        "success_rate": 0.71,
        "best_approach": "reference_competitor_pricing",
        "escalation_path": "twitter_dm"
    },
    "att_wireless": {
        "best_channel": "chat",
        "avg_response_time_days": 2,
        "success_rate": 0.63,
        "best_approach": "threaten_to_port",
        "escalation_path": "retention_dept"
    }
}

3. Privacy and Data Isolation

Financial data demands strict isolation:

All bill parsing happens in-memory (never persisted to disk)
LLM calls use structured output mode to prevent data leakage in prompts
Bank credentials stored in hardware security modules (HSM), never in config files
Audit log of every action taken, with full traceability

What This Means for Developers

If you're building in the personal finance space, the opportunity is clear: users don't want another dashboard — they want an agent that works while they sleep.

The technical stack that works well:

Python for the analysis pipeline (rich financial libraries)
GPT-4 / Claude for natural language understanding and generation
Celery/Redis for async task scheduling and monitoring
PostgreSQL + TimescaleDB for time-series financial data
SMTP + IMAP for provider communication (email APIs like SendGrid for scale)

The moat isn't in the AI — it's in the integration depth. The more providers you can connect to and the more negotiation patterns you learn, the more valuable the agent becomes.

Open Source

The core analysis engine and action planner are available: github.com/billsnip/billsnip-landing

If you want to see the agent in action or try it with your own bills: BillSnip — free to start, and we only charge when we actually save you money.

TL;DR: AI agents are replacing passive finance dashboards with autonomous systems that detect overcharges, negotiate bills, dispute errors, and optimize subscriptions — all without user intervention. The key technical challenges are hallucination prevention, provider-specific negotiation strategies, and privacy-preserving architecture. The result: 82% reduction in overspend and 94% reduction in time spent managing finances.

DEV Community: PubliFlow

How I Integrated AI Video Generation into a SaaS Platform — Seedance API + Credit System

The Challenge

Why Seedance 2.0 Mini

Architecture: The Async Task Pattern

Step 1: Task Creation

Step 2: Polling Service

Step 3: User-Facing Status

The Credit System Design

Credit Cost Per Generation

Why Credits Work Better Than Per-Video Pricing

Pricing Strategy Thoughts

Cost Management

Lessons Learned

Try It Out

I Built an All-in-One Platform for Expats — Renting, Jobs, Freelancing, and AI Tools in One Place

The Problem: A Fragmented Expat Experience

The Solution: VEIGO's Unified Architecture

1. Housing & Rental Module

2. Recruitment Module (BOSS直聘 Model)

3. Freelance & Gig Economy

4. Bidding & Procurement

5. AI Tool Suite

6. Video Production Studio

Technical Architecture

What I Learned Building This

What's Next

Designing an 8-Layer Cognitive Memory Architecture for AI Agents

Designing an 8-Layer Cognitive Memory Architecture for AI Agents

Why flat vector stores fail as agent memory

The cognitive science foundation

Layer-by-layer architecture

L1: Sensory Buffer — The 500ms window

L2: Working Memory — The active workspace

L3: Episodic Memory — What happened and when

L4: Semantic Memory — What you know (not what happened)

L5: Procedural Memory — Learning from doing

L6: Emotional Valence — Not everything matters equally

L7: Consolidation Engine — The hippocampus at night

L8: Meta-cognitive Layer — Knowing what you know

How the layers interact

Implementation reality

How it compares to existing approaches

What this costs

Closing thoughts

Architecting Bulletproof SaaS Billing with Stripe: Webhooks, Proration, and Usage Metrics

Architecting Bulletproof SaaS Billing with Stripe

The Architecture: Why Synchronous Webhooks Will Fail You

Deep Dive 1: Idempotent Webhook Reception

Deep Dive 2: Usage-Based Billing and Metering

Deep Dive 3: The Dark Arts of Proration

Handling Edge Cases: Failed Payments and Dunning

Performance Considerations and Best Practices

Key Takeaways

Mastering Supabase Auth and Row Level Security for Multi-Tenant SaaS

Mastering Supabase Auth and Row Level Security for Multi-Tenant SaaS

Architecture: How Supabase Auth Talks to Postgres

Deep Dive 1: Designing a Bulletproof RLS Data Model

Deep Dive 2: Injecting Custom Claims via Supabase Auth Hooks

Deep Dive 3: Testing RLS Policies Without the API

Performance Considerations and Common Pitfalls

1. The Indexing Trap

2. The security definer Bypass

3. JWT Bloat and Caching

Key Takeaways

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

Next.js 15 Server Actions Deep Dive: Patterns for Production SaaS

Under the Hood: RPC over HTTP

Pattern 1: Robust Form Handling with useActionState

The Server Action

The Client Component

Pattern 2: Optimistic Updates for Instant UI

Pattern 3: Progressive Enhancement and Revalidation

Common Pitfalls and Performance Considerations

1. The Serialization Trap

2. Over-Revalidating

3. Security and Authorization

4. Stale Closures in Client Components

Key Takeaways

I Built an 8-Layer Memory Architecture for AI Agents — Here's Why

2. The `security definer` Bypass

Pattern 1: Robust Form Handling with `useActionState`