DEV Community: PubliFlow

Building a Production-Ready SaaS Starter Kit from Scratch: Architecture & Implementation

PubliFlow — Sat, 15 Aug 2026 01:24:10 +0000

Building a Production-Ready SaaS Starter Kit from Scratch: Architecture & Implementation

Every SaaS journey begins with the "blank canvas" problem. You have a brilliant product idea, but before you can write a single line of business logic, you need to wire up authentication, set up a database, integrate Stripe, configure transactional emails, and establish a CI/CD pipeline. By the time you reach your first paying customer, you’ve spent three weeks just building the scaffolding.

As mid-to-senior developers, we know that a SaaS starter kit isn't just about saving time; it's about establishing a robust architectural foundation. A poorly designed starter kit will haunt you with scaling issues, security vulnerabilities, and developer friction down the line.

In this deep dive, we will architect a production-ready SaaS starter from scratch. We’ll bypass the superficial tutorials and focus on the critical architecture decisions that separate hobby projects from scalable, enterprise-grade SaaS products.

High-Level Architecture

Before writing code, we must define our boundaries. A modern SaaS architecture should leverage the edge for performance and keep the database strictly isolated.

[Client] --> [Edge Network / CDN] --> [Next.js Edge Middleware (Auth/Routing)]
                                              |
                                              v
                                     [Next.js API Routes / Server Actions]
                                              |
                       +----------------------+----------------------+
                       |                      |                      |
               [PostgreSQL DB]       [Stripe Webhooks]       [Resend/Email API]

This architecture relies on Next.js App Router, utilizing Edge Middleware for zero-latency route protection, Server Actions for mutations, and a strict multi-tenant database design.

1. Authentication & Edge Middleware

The most common pitfall in SaaS authentication is checking user permissions inside individual API routes or components. This leads to duplicated logic and security holes. The solution is to centralize auth at the edge.

We use Auth.js (formerly NextAuth) with a JWT strategy. Why JWT? Because it allows the Edge Middleware to verify sessions without hitting the database on every request, keeping latency under 10ms.

The Pitfall: Over-fetching in Middleware

A common mistake is trying to fetch the full user object in the middleware. Middleware runs on the Edge (V8 isolates), which has strict limitations on Node.js APIs and database connections.

The Solution: Lightweight JWT Payloads

Keep the JWT payload minimal. Only include the userId, email, and role. Fetch the full user profile in Server Components or Server Actions where you have full database access.

Here is a production-grade Edge Middleware that handles route protection, role-based access, and tenant routing:

// src/middleware.ts
import { NextResponse, type NextRequest } from 'next/server';
import { getToken } from 'next-auth/jwt';

const PUBLIC_PATHS = ['/', '/login', '/register', '/api/webhooks', '/api/auth'];

export async function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // 1. Allow public paths and static assets
  if (PUBLIC_PATHS.some(path => pathname.startsWith(path)) || pathname.includes('.')) {
    return NextResponse.next();
  }

  // 2. Verify JWT at the edge (No DB hit)
  const token = await getToken({ req: request, secret: process.env.AUTH_SECRET });

  if (!token) {
    const loginUrl = new URL('/login', request.url);
    loginUrl.searchParams.set('callbackUrl', pathname);
    return NextResponse.redirect(loginUrl);
  }

  // 3. Role-based route protection
  if (pathname.startsWith('/admin') && token.role !== 'ADMIN') {
    return NextResponse.redirect(new URL('/dashboard', request.url));
  }

  // 4. Inject user context into headers for downstream Server Actions/RSC
  const response = NextResponse.next();
  response.headers.set('x-user-id', token.sub!);
  response.headers.set('x-user-role', token.role || 'USER');

  return response;
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

Performance Consideration: By handling auth at the edge, we prevent unauthorized requests from ever reaching your origin servers, saving compute costs and improving security.

2. Multi-Tenant Database & Data Isolation

Multi-tenancy is where many SaaS products fail. Whether you choose a shared database with row-level security (RLS) or a database-per-tenant, the biggest risk is data leakage.

If you are using Prisma, relying on developers to manually add where: { tenantId: ctx.tenantId } to every single query is a recipe for disaster. One forgotten clause, and Tenant A sees Tenant B's data.

The Solution: Prisma Client Extensions

Instead of manual scoping, we can use Prisma Client Extensions to automatically inject the tenantId into all read and write operations. This creates a bulletproof abstraction layer.

// src/lib/db/tenant-client.ts
import { PrismaClient } from '@prisma/client';

// We extend the base client to enforce tenant isolation
export function createTenantClient(tenantId: string) {
  const prisma = new PrismaClient().$extends({
    query: {
      $allModels: {
        async findMany({ model, args, query }) {
          // Automatically inject tenantId into all findMany queries
          args.where = { ...args.where, tenantId };
          return query({ model, args });
        },
        async create({ model, args, query }) {
          // Automatically inject tenantId into all create mutations
          args.data = { ...args.data, tenantId };
          return query({ model, args });
        },
        async update({ model, args, query }) {
          args.where = { ...args.where, tenantId };
          return query({ model, args });
        },
        async delete({ model, args, query }) {
          args.where = { ...args.where, tenantId };
          return query({ model, args });
        },
        // Note: In a real app, you'd also cover findFirst, findUnique, updateMany, deleteMany, etc.
      },
    },
  });

  return prisma;
}

In your Server Actions or API routes, you simply initialize this client:

const db = createTenantClient(session.user.tenantId);
const projects = await db.project.findMany(); // tenantId is automatically applied!

Pitfall Avoided: This completely eliminates the risk of accidental cross-tenant data leakage due to developer error. The database layer itself enforces the business logic.

3. Billing, Webhooks, and Idempotency

Integrating Stripe is easy; handling Stripe webhooks reliably is hard. The most common failure mode is processing the same webhook twice (e.g., due to Stripe retrying after a timeout), leading to duplicated subscriptions or double-charged credits.

The Solution: Idempotency Keys and Signature Verification

Every webhook event from Stripe has a unique ID. We must store this ID and check it before processing the event. Furthermore, we must verify the webhook signature to ensure the payload wasn't tampered with.

Here is a robust Next.js Route Handler for Stripe webhooks:

// src/app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers';
import Stripe from 'stripe';
import { createAdminClient } from '@/lib/db/admin-client';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
const db = createAdminClient(); // Admin client bypasses tenant scoping for webhooks

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

  let event: Stripe.Event;

  try {
    // 1. Verify signature to prevent spoofing
    event = stripe.webhooks.constructEvent(body, signature!, webhookSecret);
  } catch (err: any) {
    console.error(`Webhook signature verification failed: ${err.message}`);
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }

  // 2. Idempotency check: Have we already processed this exact event?
  const existingEvent = await db.processedWebhook.findUnique({
    where: { stripeEventId: event.id },
  });

  if (existingEvent) {
    // Already processed, return 200 to tell Stripe to stop retrying
    return new Response(JSON.stringify({ received: true }), { status: 200 });
  }

  // 3. Process the event based on type
  try {
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session;
        // Fulfill the order, create subscription, etc.
        await fulfillCheckout(session);
        break;
      }
      case 'customer.subscription.updated': {
        const subscription = event.data.object as Stripe.Subscription;
        await updateSubscriptionStatus(subscription);
        break;
      }
      // Handle other events...
    }

    // 4. Record the event as processed to ensure idempotency
    await db.processedWebhook.create({
      data: { stripeEventId: event.id, type: event.type },
    });

    return new Response(JSON.stringify({ received: true }), { status: 200 });
  } catch (error) {
    console.error(`Webhook handler failed for event ${event.id}:`, error);
    // Return 500 so Stripe will retry the webhook
    return new Response(`Webhook handler failed`, { status: 500 });
  }
}

Performance Consideration: Webhook handlers should be fast. If your fulfillment logic takes too long (e.g., sending emails, generating reports), offload it to a background job queue (like Inngest, Trigger.dev, or BullMQ) immediately after recording the webhook ID.

4. Email, Deployment, and Developer Experience

Transactional Email

For emails, we use React Email combined with Resend. The key architectural decision here is never sending emails synchronously in the request lifecycle. Always queue them. Using a tool like Trigger.dev or a simple database-backed queue ensures that a slow email API doesn't block your user's UI.

Deployment Strategy

Deploy to Vercel or Cloudflare Pages. Utilize the Edge Runtime for API routes where possible to take advantage of global distribution. However, keep database-heavy routes in the standard Node.js runtime to avoid cold starts and connection pool exhaustion.

Developer Experience (DX)

A starter kit is only as good as its DX.

Monorepo: Use pnpm workspaces and Turborepo. Keep your web app, shared UI components, and database schema in one repository.
Strict Typing: Enable strict: true in tsconfig.json. Use Zod for runtime validation of API inputs.
Linting & Formatting: Biome or ESLint + Prettier configured to run on pre-commit via Husky.

Key Takeaways

Shift Security Left: Handle auth and tenant isolation at the lowest possible layer (Edge Middleware and DB extensions) rather than in UI components.
Embrace Idempotency: Assume webhooks will be delivered multiple times. Design your billing and state-mutation logic to be safely re-runnable.
Optimize for the Edge: Use JWTs for edge auth, keep payloads small, and separate your edge-compatible routes from your heavy database routes.
Abstract the Boring Stuff: A good starter kit removes the cognitive load of boilerplate so you can focus on your unique value proposition.

Building a SaaS is a marathon, not a sprint. The architecture you choose on day one will dictate your velocity on day one hundred. When I was architecting PubliFlow (publiflow.vip), a Next.js 15 SaaS starter kit I recently released, I applied this exact tenant-scoped database pattern and edge middleware setup. Finding the right balance between edge performance and database consistency was the biggest hurdle, but abstracting it into a reusable starter made all the difference.

Take these patterns, adapt them to your stack, and stop reinventing the wheel. Your future self, staring at a scaling production app, will thank you.

Building a Multi-Platform Content Publishing System with Next.js 15

PubliFlow — Mon, 10 Aug 2026 03:20:38 +0000

Building a Multi-Platform Content Publishing System with Next.js 15

If you've ever tried to publish the same article across Dev.to, Medium, and Hashnode, you know it's not as simple as copy-pasting. Each platform has its own API, its own Markdown flavor, its own image handling, and its own SEO metadata requirements. Automating this pipeline is a genuinely interesting engineering problem.

In this post, I'll walk through how to build a multi-platform content publishing system using Next.js 15, covering the key technical challenges and how to solve them. I'll use patterns from PubliFlow — a template I built for content-first SaaS products — as a practical reference.

Let's get into it.

The Architecture Overview

Before writing any code, here's the high-level architecture:

┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Content     │────▶│  Transformation  │────▶│  Platform       │
│  Editor      │     │  Pipeline        │     │  Adapters       │
│  (Markdown)  │     │  (Normalize +    │     │  (Dev.to,       │
│              │     │   Transform)     │     │   Medium, etc.) │
└─────────────┘     └──────────────────┘     └─────────────────┘
                            │
                     ┌──────┴──────┐
                     │  Image CDN   │
                     │  Upload &    │
                     │  Rewrite     │
                     └─────────────┘

The flow is:

Author writes content in standard Markdown through the editor
Content passes through a transformation pipeline that normalizes it and generates platform-specific variants
Images are uploaded to a CDN and references are rewritten
Platform adapters handle the final formatting and API calls for each destination

Step 1: Setting Up the Content Model

The first decision is how to model content in a way that's platform-agnostic but still captures platform-specific needs.

// lib/content/schema.ts

export interface ContentArticle {
  id: string;
  title: string;
  slug: string;
  body: string;                // Raw Markdown
  excerpt?: string;
  coverImage?: string;
  tags: string[];
  status: 'draft' | 'published' | 'scheduled';
  seo: SEOConfig;
  platformConfig: Map<Platform, PlatformOverrides>;
  createdAt: Date;
  updatedAt: Date;
}

export interface SEOConfig {
  metaDescription: string;
  canonicalUrl?: string;
  ogImage?: string;
  ogTitle?: string;
  structuredData?: Record<string, unknown>;
}

export interface PlatformOverrides {
  title?: string;         // Some platforms benefit from different titles
  tags?: string[];        // Tag taxonomies differ per platform
  publishedAt?: Date;     // Schedule per-platform independently
  canonicalUrl?: string;  // Cross-platform canonical management
}

export type Platform = 'devto' | 'medium' | 'hashnode';

The key insight here is the PlatformOverrides pattern. You don't want to force identical content across all platforms — Dev.to audiences respond to different titles than Medium audiences. But you do want a single source of truth for the body content.

Step 2: The Markdown Transformation Pipeline

This is the heart of the system. Raw Markdown from your editor needs to be transformed in several ways before it's ready for each platform.

2.1 Markdown Normalization

Different editors produce slightly different Markdown. Some use **bold**, others might produce HTML <strong> tags. Some preserve code block language annotations, others don't.

// lib/content/transformer.ts

import { unified } from 'unified';
import remarkParse from 'remark-parse';
import remarkGfm from 'remark-gfm';
import remarkRehype from 'remark-rehype';
import rehypeStringify from 'rehype-stringify';
import rehypeSanitize from 'rehype-sanitize';

export async function normalizeMarkdown(rawMarkdown: string): Promise<string> {
  const result = await unified()
    .use(remarkParse)
    .use(remarkGfm)            // GitHub Flavored Markdown support
    .use(remarkRehype)
    .use(rehypeSanitize)       // Strip potentially dangerous HTML
    .use(rehypeStringify)
    .process(rawMarkdown);

  return String(result);
}

Using the unified/remark/rehype ecosystem gives you a composable transformation pipeline. You can add plugins for syntax highlighting, custom containers, or any platform-specific extensions.

2.2 Image Extraction and CDN Upload

One of the trickiest parts of cross-platform publishing is image handling. Dev.to, Medium, and Hashnode all handle images differently:

Dev.to: You can reference external image URLs
Medium: Prefers images uploaded through their API (with size limits)
Hashnode: Has its own image hosting but also supports external URLs

The safest approach is to upload all images to your own CDN first, then reference the CDN URLs everywhere:

// lib/content/image-pipeline.ts

import { visit } from 'unist-util-visit';

interface ImageResult {
  markdown: string;
  uploadedUrls: Map<string, string>;  // original -> CDN URL
}

export async function processImages(
  markdown: string,
  uploadFn: (buffer: Buffer, filename: string) => Promise<string>
): Promise<ImageResult> {
  const tree = unified().use(remarkParse).parse(markdown);
  const uploadedUrls = new Map<string, string>();

  // Find all image nodes
  const imageNodes: ImageNode[] = [];
  visit(tree, 'image', (node) => {
    imageNodes.push(node);
  });

  // Upload each image to CDN in parallel
  const uploadPromises = imageNodes.map(async (node) => {
    const originalUrl = node.url;

    // Skip if already a CDN URL
    if (originalUrl.startsWith(process.env.CDN_BASE_URL!)) {
      return { original: originalUrl, cdn: originalUrl };
    }

    const buffer = await fetchImageBuffer(originalUrl);
    const filename = generateFilename(originalUrl);
    const cdnUrl = await uploadFn(buffer, filename);

    uploadedUrls.set(originalUrl, cdnUrl);
    return { original: originalUrl, cdn: cdnUrl };
  });

  await Promise.all(uploadPromises);

  // Rewrite image URLs in the Markdown AST
  visit(tree, 'image', (node) => {
    const cdnUrl = uploadedUrls.get(node.url);
    if (cdnUrl) {
      node.url = cdnUrl;
    }
  });

  return {
    markdown: unified().use(remarkStringify).stringify(tree),
    uploadedUrls,
  };
}

2.3 Platform-Specific Transformations

Each platform needs its content formatted slightly differently:

// lib/content/platform-transformers.ts

export interface PlatformContent {
  body: string;
  title: string;
  tags: string[];
  metadata: Record<string, unknown>;
}

// Dev.to expects frontmatter-style metadata and has a tag limit of 4
export function transformForDevTo(article: ContentArticle): PlatformContent {
  const tags = article.tags.slice(0, 4);  // Dev.to limit

  const body = [
    '---',
    `title: "${article.title}"`,
    `published: ${article.status === 'published'}`,
    `cover_image: ${article.coverImage || ''}`,
    `description: "${article.seo.metaDescription}"`,
    `tags: ${tags.join(', ')}`,
    '---',
    '',
    article.body,
  ].join('\n');

  return { body, title: article.title, tags, metadata: { published: true } };
}

// Medium API expects JSON fields, not frontmatter
export function transformForMedium(article: ContentArticle): PlatformContent {
  // Medium requires content in HTML or Markdown
  // Canonical URL is critical for Medium to avoid duplicate content penalties
  return {
    body: article.body,
    title: article.title,
    tags: article.tags.slice(0, 5),  // Medium limit
    metadata: {
      contentFormat: 'markdown',
      canonicalUrl: article.seo.canonicalUrl,
      publishStatus: article.status === 'published' ? 'public' : 'draft',
    },
  };
}

// Hashnode has its own content format
export function transformForHashnode(article: ContentArticle): PlatformContent {
  return {
    body: article.body,
    title: article.title,
    tags: article.tags.map(tag => ({
      name: tag,
      // Hashnode requires tag slugs for existing tags
      slug: tag.toLowerCase().replace(/\s+/g, ''),
    })),
    metadata: {
      coverImage: article.coverImage,
      // Hashnode-specific: enable cover image stickiness
      stickCoverToBottom: false,
      // Delivered to Hashnode's newsletter if enabled
      enableNewsletter: true,
    },
  };
}

Step 3: Platform API Adapters

Each platform adapter encapsulates the API communication logic:

// lib/platforms/adapter.ts

export interface PublishingResult {
  platform: Platform;
  success: boolean;
  articleUrl?: string;
  articleId?: string;
  error?: string;
  publishedAt?: Date;
}

export interface PlatformAdapter {
  name: Platform;
  authenticate(token: string): Promise<boolean>;
  publish(content: PlatformContent): Promise<PublishingResult>;
  update(articleId: string, content: PlatformContent): Promise<PublishingResult>;
  delete(articleId: string): Promise<boolean>;
}

// lib/platforms/devto.ts

export class DevToAdapter implements PlatformAdapter {
  name = 'devto' as const;
  private apiKey: string;
  private baseUrl = 'https://dev.to/api';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async authenticate(): Promise<boolean> {
    const response = await fetch(`${this.baseUrl}/users/me`, {
      headers: { 'api-key': this.apiKey },
    });
    return response.ok;
  }

  async publish(content: PlatformContent): Promise<PublishingResult> {
    const response = await fetch(`${this.baseUrl}/articles`, {
      method: 'POST',
      headers: {
        'api-key': this.apiKey,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        article: {
          title: content.title,
          body_markdown: content.body,
          published: content.metadata.published,
          tags: content.tags,
        },
      }),
    });

    if (!response.ok) {
      return {
        platform: this.name,
        success: false,
        error: `Dev.to API error: ${response.status} ${await response.text()}`,
      };
    }

    const data = await response.json();
    return {
      platform: this.name,
      success: true,
      articleUrl: data.url,
      articleId: String(data.id),
      publishedAt: new Date(data.published_at),
    };
  }

  // ... update and delete implementations
}

Step 4: Orchestrating the Publishing Pipeline

Now tie it all together with a pipeline that handles the full flow:

// lib/content/publish-pipeline.ts

export async function executePublishPipeline(
  article: ContentArticle,
  adapters: PlatformAdapter[],
  imageUploadFn: ImageUploadFunction
): Promise<PublishingResult[]> {
  // Step 1: Normalize the base Markdown
  const normalizedBody = await normalizeMarkdown(article.body);
  article.body = normalizedBody;

  // Step 2: Process and upload images
  const { markdown: processedBody, uploadedUrls } = await processImages(
    article.body,
    imageUploadFn
  );
  article.body = processedBody;
  if (article.coverImage && uploadedUrls.has(article.coverImage)) {
    article.coverImage = uploadedUrls.get(article.coverImage);
  }

  // Step 3: Transform for each target platform in parallel
  const transformedContent = adapters.map(adapter => ({
    adapter,
    content: transformForPlatform(article, adapter.name),
  }));

  // Step 4: Publish to all platforms in parallel
  // Using allSettled ensures one failure doesn't block others
  const results = await Promise.allSettled(
    transformedContent.map(({ adapter, content }) =>
      adapter.publish(content)
    )
  );

  // Step 5: Aggregate results
  return results.map((result, index) => {
    if (result.status === 'fulfilled') {
      return result.value;
    }
    return {
      platform: adapters[index].name,
      success: false,
      error: `Pipeline error: ${result.reason?.message || 'Unknown error'}`,
    };
  });
}

Step 5: SEO Considerations for Multi-Platform Publishing

When the same content lives on multiple platforms, SEO can become a nightmare if you're not careful. Here are the critical things to get right:

Canonical URLs

Always set a canonical URL pointing to your own site. This tells search engines where the original content lives and prevents duplicate content penalties.

// Every platform transform should include canonical URL management
function setCanonicalUrl(content: PlatformContent, originalUrl: string): PlatformContent {
  return {
    ...content,
    metadata: {
      ...content.metadata,
      canonicalUrl: originalUrl,
    },
  };
}

Staggered Publishing

Consider publishing to your own site first, then to platforms 24-48 hours later. This gives search engines time to index your original version before the syndicated copies appear.

// lib/content/scheduler.ts

export function scheduleStaggeredPublish(
  article: ContentArticle,
  platforms: Platform[]
): Map<Platform, Date> {
  const schedule = new Map<Platform, Date>();
  const baseTime = new Date();

  // Your own site publishes immediately
  // Dev.to: +24 hours
  // Medium: +48 hours
  // Hashnode: +24 hours (different audience from Dev.to)
  const delays: Partial<Record<Platform, number>> = {
    devto: 24 * 60 * 60 * 1000,
    hashnode: 24 * 60 * 60 * 1000,
    medium: 48 * 60 * 60 * 1000,
  };

  platforms.forEach(platform => {
    const delay = delays[platform] || 0;
    schedule.set(platform, new Date(baseTime.getTime() + delay));
  });

  return schedule;
}

Open Graph and Social Metadata

Each platform generates its own OG tags, but you should ensure your content includes rich metadata that platforms can use for social sharing previews:

High-quality cover image (at least 1200x630px for optimal social previews)
Compelling meta description (150-160 characters)
Article tags that match the platform's taxonomy

Handling Rate Limits and Errors

Platform APIs have different rate limits:

Dev.to: 30 requests per 30 seconds
Medium: Not publicly documented, but aggressive
Hashnode: Generous but undocumented

Build retry logic with exponential backoff:

async function publishWithRetry(
  adapter: PlatformAdapter,
  content: PlatformContent,
  options: { maxRetries: number; baseDelay: number } = { maxRetries: 3, baseDelay: 1000 }
): Promise<PublishingResult> {
  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    const result = await adapter.publish(content);

    if (result.success) return result;

    // Don't retry on authentication errors
    if (result.error?.includes('401') || result.error?.includes('403')) {
      return result;
    }

    // Exponential backoff
    if (attempt < options.maxRetries) {
      const delay = options.baseDelay * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  return {
    platform: adapter.name,
    success: false,
    error: `Max retries (${options.maxRetries}) exceeded`,
  };
}

Putting It All Together in a Next.js 15 Route

Here's how the entire pipeline looks as a Next.js 15 server action:

// app/dashboard/articles/publish/action.ts

'use server';

export async function publishArticle(articleId: string) {
  const article = await getArticle(articleId);
  const user = await getCurrentUser();

  // Initialize adapters for user's connected platforms
  const adapters = getActiveAdapters(user.platformTokens);

  // Execute the publishing pipeline
  const results = await executePublishPipeline(
    article,
    adapters,
    uploadToCDN  // Your CDN upload function
  );

  // Update article status based on results
  await updateArticlePublishStatus(articleId, results);

  // Revalidate the dashboard cache
  revalidatePath('/dashboard/articles');

  return results;
}

What I Learned Building This

A few non-obvious lessons from building a real multi-platform publishing system:

Content transformation is never "done." Each platform updates its API and content requirements regularly. Build your adapters to be easily modifiable.
Image handling is 50% of the complexity. If you underestimate image pipeline requirements, the whole system will suffer. Upload to your own CDN first, always.
Error handling per platform is critical. One platform being down shouldn't prevent publishing to others. Promise.allSettled is your friend.
Test with real API responses. Dev.to and Medium API documentation is decent but incomplete. Build your adapters against the actual API, not just the docs.
SEO requires platform-specific thinking. It's not just about canonical URLs — it's about understanding how each platform handles content discovery.

Want to See a Full Implementation?

If you want to see these patterns implemented in a complete, production-ready codebase, check out PubliFlow — a Next.js 15 SaaS template built for content-first products. It includes the multi-platform publishing pipeline described here, plus authentication, Stripe payments, AI writing assistance, and an affiliate system.

PubliFlow: https://publiflow.vip/
Starter: $149 · Pro: $399 · Enterprise: $999 (one-time payment)

Whether you use PubliFlow or build your own, I hope this gives you a solid foundation for thinking about multi-platform content publishing architecture. The patterns here are battle-tested and designed to scale.

Got questions about the implementation? Drop a comment — happy to dive deeper into any part of the pipeline.

My Other Projects

VEIGO — An all-in-one platform for overseas life. Find rental housing, job listings, gig work, and bidding services. Simplify your life abroad with a single platform.

VEIGO: https://shopveigo.com/ — Your one-stop overseas life platform
PubliFlow: https://publiflow.vip/ — Multi-platform content publishing SaaS template

Building a Bulletproof Multi-Platform Content Publishing Architecture

PubliFlow — Sat, 08 Aug 2026 01:20:18 +0000

Building a Bulletproof Multi-Platform Content Publishing Architecture

If you’ve ever written a high-quality technical article, you know the drill. You finish the draft, hit publish on your personal blog, and then the real work begins. You copy the text into Medium, only to find your code blocks lost their syntax highlighting. You paste it into Dev.to, and realize your cover image is broken because they require images to be uploaded to their specific CDN. You try Hashnode, and the GraphQL mutation rejects your payload because of a missing canonical URL tag.

Copy-pasting and manually tweaking content across platforms is a massive waste of time and a breeding ground for inconsistencies. As developers building SaaS products or personal brands, we need a unified engine. We need a "Write Once, Publish Everywhere" (WOPE) architecture.

In this article, we’ll dive deep into designing a robust, multi-platform content publishing system. We will cover content normalization, the adapter pattern for disparate APIs, and resilient job queuing.

The Core Architecture: Normalization, Adaptation, and Execution

A scalable publishing pipeline isn't just a script that loops through an array of API keys. It requires a decoupled architecture that separates the content representation from the platform delivery.

The architecture consists of three main phases:

Normalization Engine: Converts raw Markdown/MDX into a normalized Abstract Syntax Tree (AST), resolving platform-specific quirks (like image hosting or liquid tags).
Adapter Layer: Translates the normalized payload into the specific API formats required by Medium (GraphQL), Dev.to (REST), and Hashnode (GraphQL).
Execution & Scheduling Layer: A message queue (like BullMQ) that handles rate limiting, retries, idempotency, and scheduled publishing.

Let’s break down each layer with production-ready code.

Phase 1: Content Normalization via AST Transformation

The biggest mistake developers make is treating Markdown as a raw string. Markdown parsers have subtle differences. To build a reliable system, we must parse the Markdown into an AST, transform it, and serialize it back. We'll use the unified ecosystem (specifically remark) to handle this.

A common pitfall is image hosting. Medium rejects external image URLs, and Dev.to requires images to be uploaded to their CDN to prevent hotlinking. Instead of handling this in the API adapter, we handle it in the normalization phase.

Here is a robust remark plugin that extracts external image URLs, flags them for a secondary upload queue, and replaces them with platform-specific placeholders.

import { visit } from 'unist-util-visit';
import { Plugin } from 'unified';
import { Root, Image } from 'mdast';

// Define a custom node type for our upload placeholders
interface UploadPlaceholder {
  type: 'uploadPlaceholder';
  originalUrl: string;
  placeholderId: string;
}

export const remarkImageExtractor: Plugin<[], Root> = () => {
  return (tree, file) => {
    const imageQueue: { originalUrl: string; placeholderId: string }[] = [];

    visit(tree, 'image', (node: Image, index, parent) => {
      if (node.url.startsWith('http')) {
        const placeholderId = `img_${Math.random().toString(36).substring(7)}`;

        // Queue the image for async uploading to platform CDNs
        imageQueue.push({ originalUrl: node.url, placeholderId });

        // Replace the image node with a placeholder that the adapter will resolve
        const placeholder: any = {
          type: 'uploadPlaceholder',
          originalUrl: node.url,
          placeholderId,
          alt: node.alt,
          title: node.title
        };

        if (parent && typeof index === 'number') {
          parent.children[index] = placeholder;
        }
      }
    });

    // Attach the queue to the file data for the orchestrator to process
    file.data.imageQueue = imageQueue;
  };
};

By the time the content reaches the adapter, all external images have been swapped with {{upload_image:img_xxx}} placeholders. The orchestrator processes the imageQueue, uploads the images to the target platform's API, and replaces the placeholders with the final CDN URLs.

Phase 2: The Adapter Pattern for Platform APIs

Every platform has a different API paradigm. Dev.to uses REST, Medium uses GraphQL, and Hashnode uses a slightly different GraphQL schema. Hardcoding these into a single service violates the Open/Closed Principle. We need an Adapter pattern.

We define a strict contract for what a "published post" requires, and let each adapter handle the platform-specific translation.

import { z } from 'zod';

// Strict schema for our normalized internal payload
export const PublishPayloadSchema = z.object({
  title: z.string().min(1),
  contentMarkdown: z.string().min(1),
  tags: z.array(z.string()).max(5), // Dev.to limits to 5 tags
  canonicalUrl: z.string().url().optional(),
  publishedAt: z.date().optional(),
  coverImageUrl: z.string().url().optional(),
});

export type PublishPayload = z.infer<typeof PublishPayloadSchema>;

export interface PlatformAdapter {
  readonly name: string;
  publish(payload: PublishPayload): Promise<{ postId: string; url: string }>;
  update(postId: string, payload: Partial<PublishPayload>): Promise<void>;
}

export class DevToAdapter implements PlatformAdapter {
  readonly name = 'dev.to';
  private apiKey: string;

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async publish(payload: PublishPayload) {
    const response = await fetch('https://dev.to/api/articles', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'api-key': this.apiKey,
      },
      body: JSON.stringify({
        article: {
          title: payload.title,
          body_markdown: payload.contentMarkdown,
          published: true,
          tags: payload.tags,
          canonical_url: payload.canonicalUrl,
          series: null, // Dev.to specific
        },
      }),
    });

    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`Dev.to API Error: ${response.status} - ${errorText}`);
    }

    const data = await response.json();
    return { postId: data.id.toString(), url: data.url };
  }

  async update(postId: string, payload: Partial<PublishPayload>) {
    // Implementation for PUT /api/articles/{id}
    // ...
    throw new Error('Not implemented');
  }
}

Notice how the DevToAdapter maps our internal PublishPayload to Dev.to's specific article wrapper. If we add Hashnode tomorrow, we just write a HashnodeAdapter that maps the same payload to their GraphQL mutation. The core business logic remains untouched.

Phase 3: Resilient Execution with BullMQ

Publishing to multiple APIs simultaneously is a recipe for rate-limit bans and partial failures. If Dev.to succeeds but Medium fails, you end up with fragmented content. Furthermore, API calls are slow. You shouldn't block the user's HTTP request while waiting for three external APIs.

We must offload this to a background queue. We'll use BullMQ (backed by Redis) to handle job scheduling, retries, and concurrency control.

import { Queue, Worker, Job } from 'bullmq';
import IORedis from 'ioredis';
import { DevToAdapter, PublishPayload } from './adapters';

const connection = new IORedis(process.env.REDIS_URL!);

// 1. Define the Queue
export const publishingQueue = new Queue('multi-platform-publish', { connection });

// 2. Define the Job Data Type
interface PublishJobData {
  payload: PublishPayload;
  platforms: string[]; // e.g., ['dev.to', 'medium']
  idempotencyKey: string; // Crucial for preventing duplicate posts
}

// 3. The Worker
export const publishingWorker = new Worker<PublishJobData>(
  'multi-platform-publish',
  async (job: Job<PublishJobData>) => {
    const { payload, platforms, idempotencyKey } = job.data;

    // Check idempotency key in DB to ensure we haven't already processed this exact draft
    const alreadyPublished = await db.checkIdempotency(idempotencyKey);
    if (alreadyPublished) {
      console.log(`Job ${job.id} already processed. Skipping.`);
      return { status: 'skipped' };
    }

    const adapters = getAdaptersForPlatforms(platforms);
    const results: Record<string, any> = {};

    // Process sequentially or with controlled concurrency to respect rate limits
    for (const adapter of adapters) {
      try {
        console.log(`Publishing to ${adapter.name}...`);
        const result = await adapter.publish(payload);
        results[adapter.name] = result;

        // Add a small delay between API calls to avoid triggering rate limits
        await new Promise(resolve => setTimeout(resolve, 1500));
      } catch (error) {
        console.error(`Failed to publish to ${adapter.name}:`, error);
        // Depending on your business logic, you might throw here to trigger a BullMQ retry,
        // or log and continue to publish to the remaining platforms.
        // For critical platforms, throw an error to trigger exponential backoff.
        if (adapter.name === 'dev.to') {
          throw error;
        }
      }
    }

    // Mark idempotency key as processed
    await db.markIdempotencyProcessed(idempotencyKey);

    return { status: 'success', results };
  },
  {
    connection,
    limiter: {
      max: 10, // Max 10 jobs
      duration: 60000, // per 60 seconds (Global rate limiting)
    },
  }
);

This worker implementation includes three critical features for production systems:

Idempotency Keys: Prevents duplicate posts if a job is retried or manually re-queued.
Global Rate Limiting: The limiter config ensures we don't blast the platforms with concurrent requests.
Inter-job Delays: The setTimeout between adapter calls prevents hitting per-minute rate limits on specific endpoints.

Common Pitfalls and Performance Considerations

When building this architecture, you will inevitably run into a few edge cases. Here is how to avoid them:

The Canonical URL Trap: Always set the canonical_url to your own domain. If you publish to Medium and Dev.to without a canonical URL, those platforms will index the content first, destroying your personal blog's SEO.
Tag Normalization: Dev.to limits tags to 5 and requires them to be lowercase without spaces. Medium uses "topics". You need a normalization function in your payload validation (using Zod, as shown above) to strip spaces and enforce limits before the data reaches the adapters.
Handling API Token Expiry: OAuth tokens for Medium expire. Your adapter layer needs a mechanism to refresh tokens or alert the user via a webhook when a token becomes invalid, rather than just failing silently in the queue.
Performance: Image processing is CPU intensive. If you are resizing or optimizing images before uploading them to platform CDNs, do not do this in the BullMQ worker if it's running on the same Node.js instance as your web server. Offload image processing to a separate service or use edge functions to prevent blocking the event loop.

Key Takeaways

Never treat Markdown as a raw string. Parse it into an AST to handle platform-specific transformations reliably.
Use the Adapter Pattern. Abstract the API differences behind a common interface to keep your core logic clean and extensible.
Embrace Asynchronous Execution. Use a robust queue like BullMQ to handle retries, rate limiting, and idempotency.
Protect your SEO. Always inject canonical URLs and normalize tags before publishing.

Building a resilient multi-platform publishing system transforms content distribution from a manual chore into an automated, scalable asset. When I was architecting the content delivery layer for PubliFlow (publiflow.vip), my Next.js 15 SaaS Starter Kit, I relied heavily on this exact adapter-and-queue pattern. Handling multi-tenant content distribution at scale taught me that the queue layer isn't just a nice-to-have; it's the backbone of a resilient publishing system. If you're building a SaaS that involves content generation or distribution, looking into how Next.js 15 handles server actions and background queues can save you weeks of debugging edge cases.

By implementing these patterns, you can ensure your content reaches your audience, wherever they read, without compromising on quality or your own sanity.

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