DEV Community: Mohamed Sadok

I Built a Tool to Find the Tests Developers Have Stopped Trusting

Mohamed Sadok — Tue, 29 Sep 2026 08:36:54 +0000

I Built a Tool to Find the Tests Developers Have Stopped Trusting

A test fails in CI.

You look at it.

You run it again.

It passes.

You run it again.

It passes.

You rerun the pipeline.

Everything is green.

So you merge the pull request.

A few hours later, the same test fails again.

At some point, the team stops treating that failure as useful information.

That's the real problem with flaky tests.

They don't just make CI unreliable.

They make developers stop trusting CI.

The problem isn't writing tests

Modern JavaScript projects already have excellent testing tools.

Playwright is great for browser testing.

Vitest and Jest are great for unit and integration testing.

CI platforms can execute thousands of tests.

The problem starts after the tests exist.

A growing project eventually accumulates:

Tests that fail intermittently
Tests that take too long
Tests that haven't failed in months
Tests that fail only in CI
Tests that fail because of timing
Tests that produce almost identical errors
Tests that nobody wants to touch

The test suite becomes a second system that needs maintenance.

And most teams don't have a good way to measure its health.

So I built TestOps Kit

The idea is simple:

Don't replace the test runner. Analyze what it produces.

TestOps Kit consumes machine-readable test results and builds a reliability layer around them.

The workflow looks like this:

Playwright / Vitest / Jest
            ↓
       Test results
            ↓
       TestOps Kit
            ↓
 ┌──────────┼───────────┐
 ↓          ↓           ↓
History   Reliability  Performance
 ↓          ↓           ↓
Flaky     Quarantine   Slow tests
tests
            ↓
        Dashboard

The existing testing workflow stays intact.

TestOps simply adds another layer of information.

The first feature I wanted was flaky-test detection

A single failed test doesn't necessarily mean a test is flaky.

You need history.

For example:

Run 1 → PASS
Run 2 → PASS
Run 3 → FAIL
Run 4 → PASS
Run 5 → FAIL

That pattern is much more interesting than a single failure.

TestOps tracks test behavior across runs and calculates reliability metrics from the available history.

The goal isn't to say:

"This test is definitely broken."

The goal is to say:

"This test has demonstrated inconsistent behavior and deserves investigation."

That's a much more useful signal.

Then came quarantine

Once you identify unreliable tests, the next problem is operational.

What do you do with them?

TestOps can generate a quarantine manifest based on a configurable flakiness threshold.

For example:

Flaky tests

checkout/payment.spec.ts     42%
account/login.spec.ts        31%
orders/create.spec.ts        27%

Instead of relying on someone's memory, the team now has a concrete list.

The important part is that quarantine is treated as a temporary reliability workflow, not a way to permanently hide failures.

Slow tests are another form of test debt

A test doesn't have to fail to become expensive.

Imagine a suite containing:

1,200 tests

and a handful of tests account for a significant portion of the runtime.

Those tests affect every developer.

Every pull request.

Every CI run.

Every deployment.

So TestOps also tracks duration and highlights slow tests.

The goal is straightforward:

Find the tests that are costing the team time.

Visual regression belongs in the same conversation

Testing isn't only about pass and fail.

UI changes can also introduce unexpected regressions.

TestOps includes deterministic snapshot checking so a CI pipeline can detect changed snapshot content.

For example:

npx testops snapshot snapshots --strict

If a snapshot changes unexpectedly, the command returns a failure.

That makes it possible to use the same reliability workflow in CI.

I also wanted a boring CLI

Developer tools don't need complicated installation procedures.

The basic workflow should be something like:

npx testops analyze --input test-results.json

Then:

npx testops report

And you get a dashboard.

The dashboard focuses on the questions developers actually care about:

How many tests do we have?

How many are failing?

Which ones are flaky?

Which ones are slow?

What happened in previous runs?

Testing the tester

One of the most important parts of building a developer tool is testing it against something real.

A synthetic demo can prove that the software works in theory.

It doesn't prove that developers can use it in their projects.

So the validation workflow is:

Existing project
      ↓
Existing tests
      ↓
Generate real test report
      ↓
Feed report into TestOps
      ↓
Compare metrics
      ↓
Create intentional flaky test
      ↓
Run repeatedly
      ↓
Verify detection
      ↓
Create slow test
      ↓
Verify performance detection
      ↓
Modify snapshot
      ↓
Verify regression detection
      ↓
Run inside CI

This is the test that matters.

Not whether the landing page looks good.

Not whether the dashboard has impressive charts.

Whether it can survive a real repository.

What I learned

The interesting part of test infrastructure isn't necessarily generating more tests.

It's understanding the tests you already have.

A team can have 5,000 tests and still have a reliability problem.

More tests don't automatically mean more confidence.

Sometimes the real question is:

Which tests can we trust?

That's the problem TestOps Kit is designed around.

The goal

The long-term idea is bigger than a CLI.

A mature version could understand:

Test history
CI environments
Failure patterns
Code changes
Test ownership
Dependency relationships
Visual changes
Performance regressions
Failure clusters

Eventually, the system could answer questions like:

Which tests became unreliable after this deployment?

Or:

Which changed files are responsible for most of the tests we need to run?

Or:

Which tests have consumed the most CI time this month?

But the first version starts with something much simpler:

Measure test reliability instead of guessing about it.

Because once developers stop trusting their test suite, the test suite has already become technical debt.

And that's a problem worth measuring.

TestOps Kit — Flaky Test Detection, Test Reliability & CI Toolkit

TestOps KitProduction Test Reliability Toolkit for Modern JavaScript TeamsYour test suite is supposed to give you confidence.Instead, you get: Random CI failures Tests that pass locally but fail in CI Slow test suites Repeated failures nobody investigates Visual regressions Hundreds of test results to manually inspect Flaky tests that waste hours every week TestOps Kit turns raw test results into actionable test reliability data.It analyzes your existing test reports, tracks test history, detects flaky tests, identifies slow tests, generates quarantine manifests, checks visual snapshots, and produces a standalone reliability dashboard.No need to replace your existing test framework.What you getFlaky Test DetectionTrack test behavior across multiple runs and identify tests that repeatedly switch between passing and failing.See: Flakiness percentage Failure frequency Run history Test duration Failure information Test Reliability DashboardGet a single view of your test suite: Total tests Pass rate Failed tests Flaky tests Slow tests Test duration Historical runs Failure details Test QuarantineGenerate a quarantine manifest for tests that exceed your configured flakiness threshold.Instead of manually maintaining a list of unreliable tests, let TestOps identify them from actual test history.Slow Test DetectionFind tests that are consuming disproportionate CI time.Use duration history to identify tests that deserve optimization.Visual Regression ChecksCreate deterministic snapshot baselines and detect unexpected changes using content hashing.Useful for: HTML snapshots JSON snapshots Generated assets Test fixtures Visual regression workflows CI ReadyDesigned to fit into existing CI pipelines.Use it with GitHub Actions and your existing test infrastructure.Multiple Report FormatsThe toolkit supports common machine-readable test reports including: Playwright JSON Vitest/Jest-style JSON JUnit XML Test Impact AnalysisIdentify candidate tests related to changed files so you can focus testing where changes actually occurred.Stress TestingRun the same command repeatedly to expose intermittent failures.Example:npx testops stress --command "npm test" --runs 20 Developer CLIEverything is accessible from the command line.npx testops analyze --input test-results.json npx testops report npx testops quarantine npx testops snapshot snapshots --strict npx testops stress --command "npm test" --runs 20 Built for JavaScript developers TypeScript developers SaaS teams Freelancers Agencies QA engineers DevOps engineers CI/CD-heavy projects Teams using Playwright, Vitest or Jest Requirements Node.js 18+ npm Git Existing automated test reports Included TestOps CLI Reliability analyzer Flaky test detector Test history Quarantine generator Slow-test analysis Stress runner Visual snapshot checker Git impact analysis Standalone dashboard GitHub Actions integration Demo fixtures Complete documentation Example configuration MIT license Why TestOps?Test generation is only half the testing problem.The other half is knowing whether the tests you already have can actually be trusted.TestOps focuses on that problem.Know which tests are stable. Know which ones are flaky. Know which ones are slowing CI down.Build with confidence instead of debugging CI noise.

boukataya.gumroad.com

How We Built a Production-Ready SaaS Billing Engine (And How You Can Ship Yours Today)

Mohamed Sadok — Mon, 28 Sep 2026 15:53:44 +0000

The complete blueprint for handling subscriptions, customer billing portals, and edge-case webhooks without losing your sanity.*

Every developer building a SaaS eventually runs into the same wall: Monetization Architecture.

Building the core features of an application is exciting. Writing billing logic, managing recurring cycles, handling failed credit card charges, generating PDFs, and wiring up webhook endpoints is usually where momentum slows down.

In this article, we'll walk through the architecture of a production-ready SaaS billing engine and examine the critical patterns needed to accept recurring payments reliably.

1. The Billing State Problem

Handling payments is not just a single API call to charges.create(). A production billing system must manage state transitions across multiple scenarios:

What happens when a renewal payment fails at 3:00 AM?
How do you handle plan upgrades with prorated charges mid-cycle?
What happens if a user cancels their subscription before the cycle ends?

The Core Subscription State Machine

A resilient subscription model requires tracking distinct statuses:

trialing
active
past_due
canceled
incomplete

[ Checkout ] ──► [ Active ] ──► (Cycle Renewal)
                      │                │
                      ▼                ▼
                 [ Canceled ]    [ Past Due ] ──► [ Inactive ]

2. Webhooks: The Single Source of Truth

Never rely solely on client-side redirect URLs (e.g., /checkout/success) to grant access to paid tiers. Network disconnects, closed browser tabs, or client-side crashes can prevent access from being granted.

Recommended Webhook Pipeline

Verify Signature: Ensure the payload originated from your payment gateway.
Idempotency Check: Store incoming event_id values to prevent processing duplicate events.
Queue Processing: Immediately return a 200 OK response to the payment provider and dispatch the actual processing task to a background worker.

// Example: Verifying and dispatching webhooks asynchronously
public function handleWebhook(Request $request)
{
    $event = $this->verifySignature($request);

    if ($this->hasBeenProcessed($event->id)) {
        return response()->json(['status' => 'already_processed'], 200);
    }

    ProcessBillingEventJob::dispatch($event);

    return response()->json(['status' => 'queued'], 200);
}

3. Customer Self-Service: The Billing Portal

Modern users expect to manage their own billing:

Updating expired credit cards
Downloading past VAT / Tax invoices
Upgrading or downgrading plans

Using hosted billing portals (like Stripe Customer Portal) eliminates the need to build custom PCI-compliant credit card updating forms on your frontend.

4. Get the Starter Kit

Rather than spending 40+ hours wiring up database schemas, webhook listeners, environment configs, and test suites, you can grab the complete SaaS Billing Engine Starter Kit.

Includes:

Complete source code with local DDEV / Docker support
Production-tested webhook handlers
Seeders, migrations, and plan definitions
Detailed documentation

https://boukataya.gumroad.com/l/shouoa

saa-s-billing-starter-kit-demo.vercel.app

How I Built a 1970s Retro Vinyl Store Web App in 1 Single HTML File (No Frameworks, No Build Step)

Mohamed Sadok — Fri, 25 Sep 2026 10:17:29 +0000

Every modern e-commerce website seems to look the same.

Clean white backgrounds.
Minimal cards.
Rounded buttons.
The same fonts.
The same SaaS-style layouts.

It works, but sometimes it feels completely soulless.

So I decided to build something different.

I wanted to recreate the feeling of walking into a small record store in the late 1970s — old vinyl sleeves, warm paper textures, bold typography, imperfect print effects, and even the subtle sound of vinyl crackling in the background.

The result is GrooveHaus, a retro vinyl store web app built entirely inside one HTML file.

No framework.
No build process.
No node_modules.
No complicated setup.

Just HTML, CSS, JavaScript, and a lot of experimentation.

🎧 Live Demo & Template

Live Demo:
https://groove-haus.vercel.app/

Template:
https://boukataya.gumroad.com/l/ytowj

The Idea Behind GrooveHaus

The goal wasn't simply to make an "old-looking" website.

I wanted the interface itself to feel like a physical object.

Think:

Vintage record sleeves
Printed paper textures
1970s-inspired typography
Burnt orange, mustard, cream and burgundy colors
Grain and imperfect print effects
Records that physically slide out of their sleeves
Analog vinyl crackle
Simple page transitions
A store experience that feels more like browsing a record shop than using a typical e-commerce dashboard

The interesting part was trying to create those sensations using only browser-native technologies.

The Constraint: One HTML File

I deliberately gave myself a strict constraint:

Everything had to live inside a single .html file.

That means no React.

No Vue.

No build system.

No npm installation.

No bundler.

No component library.

The page contains the markup, styling and JavaScript needed to run the application.

External resources are limited to things like fonts and CDN-hosted libraries.

This sounds restrictive, but it actually made the project more interesting.

Instead of asking:

"Which framework should I use?"

I could focus on:

"How much can I build with the browser itself?"

The Stack

The technology stack is intentionally simple:

HTML5 handles the structure and application views.

Tailwind CSS via CDN provides the utility classes and makes it easy to create the visual system.

Vanilla JavaScript handles routing, application state, rendering, filtering and interactions.

Web Audio API generates the vinyl crackle effect directly in the browser.

Google Fonts and Font Awesome provide typography and icons.

There is no backend because the goal was to create a self-contained frontend template.

Making the Browser Sound Like Vinyl

One of my favorite parts of the project is the analog noise effect.

Instead of shipping an audio file containing vinyl crackle, GrooveHaus generates the sound dynamically using the Web Audio API.

The browser creates an audio buffer containing low-level random noise combined with occasional louder pops.

The result is a subtle background texture that resembles an old record playing.

The important part is keeping it subtle.

The effect isn't supposed to become annoying background music. It's more like an atmospheric layer that you notice when you stop and listen.

Users can also turn the effect on or off.

This was a good reminder that the Web Audio API can do much more than simply play MP3 files.

A Tiny SPA Without a Framework

The application behaves like a small single-page application.

There are different views for things like:

Storefront
Catalog
Product details
Artists
Journal
Cart
Settings

Instead of installing a routing library, I used the browser's native URL hash.

For example, different hash routes determine which application view should be displayed.

When the URL changes, JavaScript hides the previous view, displays the appropriate one and renders the required content.

It's obviously not a replacement for a full routing solution in a large production application.

But for a self-contained template?

It works surprisingly well.

And there is something satisfying about realizing that you don't always need another dependency to solve a relatively small problem.

Making Vinyl Records Feel Physical

One of the visual details I wanted was the feeling of pulling a record out of its sleeve.

When hovering over a product card, the vinyl disc slides out from behind the album artwork while rotating.

It's a small interaction, but it changes how the product card feels.

Instead of:

Image → title → price → button

you get something closer to interacting with a physical record.

The effect is entirely CSS-based, using transforms and transitions.

No animation library required.

This is one of those cases where a few lines of CSS can create much more personality than another UI component ever could.

Recreating Printed Paper

Modern websites are usually extremely clean.

GrooveHaus deliberately isn't.

The background uses warm paper tones combined with subtle radial patterns to imitate the texture of printed material.

The color palette is built around:

Cream
Aged paper
Dark brown
Burnt orange
Mustard
Burgundy

Typography also plays a major role.

Instead of using one generic UI font everywhere, the design combines display and serif typefaces to create something closer to vintage posters, record sleeves and printed magazines.

The goal isn't perfect realism.

It's controlled imperfection.

Why I Didn't Use React

This project probably could have been built faster with React.

But that wasn't the point.

Sometimes constraints are useful.

Removing the framework forced me to think about what the browser already provides:

DOM APIs
URL hashes
CSS transitions
Web Audio
browser storage
native events
modern JavaScript

It also makes the final result extremely portable.

There is something nice about downloading one HTML file and knowing that most of the application is sitting right there.

Where Single-File Apps Actually Make Sense

I'm not suggesting everyone should abandon frameworks.

For a large SaaS platform, complex dashboard or production application with dozens of developers, a single HTML file would quickly become painful.

But there are some cases where this architecture makes a lot of sense.

For example:

Templates

A customer can download one file and immediately start customizing it.

Prototypes

You can experiment with an idea without spending time setting up infrastructure.

Landing pages

For a relatively simple marketing experience, a build pipeline may be unnecessary.

Digital products

A self-contained template is easy to distribute through marketplaces and digital stores.

Experiments

Sometimes you simply want to see how far native browser APIs can take you.

The Bigger Lesson

The most interesting part of building GrooveHaus wasn't actually the vinyl store.

It was realizing how much you can do before reaching for another dependency.

A browser already gives you a lot:

HTML for structure.

CSS for animation and visual effects.

JavaScript for application logic.

Web Audio for sound.

The URL for simple routing.

And modern browser APIs for everything in between.

Frameworks are incredibly useful.

But they aren't mandatory for every project.

Sometimes putting yourself inside a few artificial constraints leads to more creative solutions.

Final Thoughts

GrooveHaus started as a visual experiment:

"Can I make a website feel like a physical record store?"

It ended up becoming an experiment in something else:

"How much can I build with nothing more than a browser and a single HTML file?"

The answer is: quite a lot.

And honestly, building something that doesn't look like another SaaS dashboard was probably the most refreshing part.

Live Demo:
https://groove-haus.vercel.app/

Template:
https://boukataya.gumroad.com/l/ytowj

What retro web design trend would you bring back?

How I Built Multi-Tenant SaaS Architecture with Next.js, Supabase, and PostgreSQL RLS

Mohamed Sadok — Wed, 23 Sep 2026 13:38:14 +0000

Building the first version of a SaaS application is usually straightforward.

Building the part that makes sure Customer A can never access Customer B's data is where things get serious.

A typical B2B SaaS eventually needs:

Authentication
Organizations
Team members
Roles and permissions
Invitations
Protected routes
Tenant-scoped data
Database-level security

You can implement all of this incrementally.

But there is a problem with that approach:

Multi-tenancy affects almost every layer of the application.

So I wanted to build a reusable architecture where tenant isolation was part of the foundation rather than something added after the application had already grown.

This article explains the architecture I used with Next.js, Supabase, TypeScript, and PostgreSQL Row-Level Security.

The basic architecture

The core relationship is:

User
 │
 ▼
Organization Membership
 │
 ▼
Organization
 │
 ├── Projects
 ├── Invitations
 └── Other Tenant Resources

A user doesn't directly own the application's business data.

Instead:

User → Membership → Organization → Resource

This distinction becomes important when a user belongs to multiple organizations.

For example:

Alice
 ├── Acme Inc.       → Admin
 ├── Startup Labs    → Member
 └── Example Corp.   → Owner

The same authenticated user can therefore work across multiple tenants without creating separate accounts.

Why Row-Level Security Matters

One of the easiest mistakes in a multi-tenant application is relying entirely on application-level filtering.

Imagine:

const projects = await getProjects()

The developer is expected to remember that every query must be scoped to the current organization.

Usually that becomes something like:

const projects = await getProjects(organizationId)

This is better.

But there is still a problem.

What happens when somebody forgets the filter?

Or introduces a new API endpoint six months later?

Or accidentally exposes a query through another code path?

This is why I wanted PostgreSQL itself to enforce the tenant boundary.

The goal becomes:

Application
     │
     ▼
PostgreSQL
     │
     ▼
RLS Policy
     │
     ├── User belongs to organization → ALLOW
     │
     └── User does not belong → DENY

The database becomes another security boundary.

Organizations and Memberships

A simplified database model looks like this:

profiles
   │
   │
   ▼
organization_members
   │
   ▼
organizations
   │
   ├── projects
   └── invitations

The membership table connects users to organizations.

Conceptually:

organization_members

user_id
organization_id
role
created_at

This allows the same user to have different roles in different organizations.

For example:

Acme Inc.
Mohamed → OWNER

Startup Labs
Mohamed → MEMBER

The role belongs to the membership, not globally to the user.

That distinction makes the system much more flexible.

RBAC

The starter uses three basic roles:

OWNER
ADMIN
MEMBER

A simplified permission model could look like:

Permission	Owner	Admin	Member
View projects	✓	✓	✓
Create projects	✓	✓	✓
Manage members	✓	✓	—
Change roles	✓	✓	—
Remove members	✓	✓	—
Manage organization	✓	—	—

The important thing isn't the specific roles.

It's keeping authorization centralized instead of scattering checks throughout the application.

For example:

if (!can(user, "members.update")) {
  throw new Error("Forbidden")
}

As the application grows, additional roles and permissions can be introduced without rewriting every feature.

Invitations

Invitations are another part of multi-tenancy that looks deceptively simple.

The expected workflow is:

Admin
  │
  ▼
Create invitation
  │
  ▼
Generate token
  │
  ▼
Send invitation
  │
  ▼
User opens link
  │
  ▼
Verify invitation
  │
  ▼
Create membership

The invitation record contains information such as:

organization_id
email
token
role
expires_at
accepted_at

The implementation also verifies that the email associated with the invitation matches the account accepting it.

That prevents a forwarded invitation link from automatically granting access to the wrong account.

The invitations in this implementation expire after seven days.

The Important Part: RLS

Consider a projects table:

projects

id
organization_id
name
description
created_at

Every project belongs to an organization.

Now imagine a user belonging to:

organization_id = abc

The user should only be able to access:

projects.organization_id = abc

and nothing belonging to:

organization_id = xyz

The RLS policy expresses this relationship at the database level.

Conceptually:

Current User
     │
     ▼
Is member of organization?
     │
   ┌─┴─┐
  YES  NO
   │    │
   ▼    ▼
 ALLOW DENY

This is fundamentally different from simply hiding records in the frontend.

Frontend Checks Are Not Security

This is worth emphasizing.

This:

{isAdmin && <DeleteButton />}

is useful.

But it isn't security.

A user can bypass the interface and send a request directly.

That's why I prefer multiple layers:

┌──────────────────────────┐
│        UI checks         │
├──────────────────────────┤
│   Server authorization   │
├──────────────────────────┤
│ PostgreSQL RLS policies  │
└──────────────────────────┘

The UI controls the experience.

Server-side authorization controls the operation.

RLS protects the data.

Each layer has a different responsibility.

Avoiding Recursive RLS Policies

One problem I encountered was recursive policy evaluation.

Suppose a project policy checks:

Is the user a member of this organization?

That requires reading:

organization_members

But if organization_members also has RLS policies, the database can end up evaluating policies that depend on other policies.

Conceptually:

projects
   ↓
organization_members
   ↓
RLS
   ↓
organization_members
   ↓
...

To avoid this, the architecture uses carefully controlled SECURITY DEFINER helper functions for membership checks.

The result is a reusable authorization primitive that can be referenced by multiple RLS policies without creating recursive policy evaluation.

Next.js Authentication

The application uses Supabase Auth with Next.js server-side authentication.

The important part is keeping authentication state available correctly across server and browser contexts.

The flow is roughly:

Browser
   │
   ▼
Supabase Auth
   │
   ▼
Session Cookie
   │
   ▼
Next.js Server
   │
   ▼
Authenticated User

Protected routes can then determine:

Who is the user?
        ↓
Which organizations do they belong to?
        ↓
Which organization are they currently accessing?
        ↓
What can they do?

This makes the organization context explicit rather than relying on client-side state alone.

Tenant-Scoped Projects

Projects are used as the example tenant resource.

A project belongs to exactly one organization:

Acme Inc.
 ├── Website Redesign
 ├── Mobile Application
 └── Marketing Platform

Startup Labs
 ├── AI Assistant
 └── Analytics Dashboard

When the current organization changes, the project dataset changes accordingly.

The application doesn't need a separate codebase for each tenant.

The same application handles all organizations.

Organization Switching

The organization selector is another important part of the UX.

A user may belong to several organizations:

┌──────────────────────┐
│ Acme Inc.          ▼ │
└──────────────────────┘

Opening it:

Acme Inc.
Startup Labs
Example Corp.

Selecting an organization changes the tenant context.

The application then loads resources belonging to that organization.

The database still enforces the final access boundary.

Application Structure

The resulting route structure is intentionally simple:

/
├── login
├── signup
├── dashboard
│
├── org/[orgId]
│   ├── members
│   ├── projects
│   └── invites
│
├── invite/[token]
│
└── auth/callback

This creates a clear distinction between:

Public pages
Authentication
Organization context
Tenant resources
Invitation flows

It also leaves plenty of room for additional modules.

Why I Chose Supabase

The goal wasn't to assemble dozens of services.

Supabase gives the project several important pieces in one ecosystem:

Supabase
 ├── Authentication
 ├── PostgreSQL
 └── Row-Level Security

That combination is particularly useful for multi-tenant applications because authentication and database authorization can work together.

Instead of building a separate authentication system and then trying to synchronize it with a separate database authorization layer, the application can use the authenticated identity directly in PostgreSQL security policies.

What This Architecture Doesn't Solve

This isn't a complete SaaS business.

There are deliberately no:

Stripe subscriptions
OAuth providers
File storage
Background jobs
Audit logs
Usage-based billing
Automated test suite

Those features depend heavily on the actual product being built.

A CRM may need billing and audit logs.

An AI application may need usage limits and model providers.

A project management platform may need file storage and background processing.

The foundation should stay generic.

The Takeaway

The biggest lesson from building this wasn't a specific Supabase feature.

It was this:

Multi-tenancy should be treated as an architectural boundary, not simply a database column.

A scalable model starts with:

User
 ↓
Membership
 ↓
Organization
 ↓
Tenant Resource

Then security is enforced at multiple levels:

UI
 ↓
Server Authorization
 ↓
PostgreSQL RLS

This gives you a much stronger foundation for building B2B SaaS applications.

Instead of repeatedly solving authentication, organizations, roles, invitations, and tenant isolation, you can start with those pieces already established and focus on the actual product.

What I Built

I packaged this architecture into a reusable Next.js + Supabase Multi-Tenant SaaS Starter.

It includes:

Next.js 16
TypeScript
Supabase Auth
PostgreSQL
Row-Level Security
Organizations
RBAC
Invitations
Tenant-scoped Projects CRUD
Member management
DDEV support
Vercel deployment support
Database migrations
Documentation
Static demo

You can explore the working demo here:

https://demo-supabase-multi-tenant-saa-s-st.vercel.app/

The article above is intentionally focused on the architecture rather than the product. If you are building a multi-tenant SaaS, the important part is understanding the security model and tenant boundaries before the application grows around them.

The 3 Lines of Stripe Webhook Code That Will Eventually Cost You Money

Mohamed Sadok — Fri, 18 Sep 2026 12:54:13 +0000

Stripe Webhooks in Laravel: 3 Production Failure Modes You Need to Handle

Your Stripe integration works.

You tested it with stripe trigger. The subscription appeared in the database. The happy path works.

So you move on to the next feature.

Then a customer emails you:

“I was charged twice.”

Or worse, nobody emails you.

Stripe stopped reaching your webhook endpoint three weeks ago, and you only discover it when your MRR chart starts looking wrong.

I spent the last few weeks building a production-grade Stripe webhook layer for Laravel 11 + Cashier. It has 40 tests and is now packaged as a standalone kit.

This article covers the three failure modes that repeatedly show up in real-world Stripe integrations—and the implementation patterns that prevent them.

The finished kit: https://boukataya.gumroad.com/l/nggzho

The lessons below are free, whether you buy the kit or build everything yourself.

Stripe Retries Webhooks — So Your Handler Must Be Idempotent

This is the failure mode everyone knows about.

And one of the easiest to implement incorrectly.

Stripe retries webhook deliveries when your endpoint doesn't return a 2xx response. Retries can continue for up to three days.

The dangerous part is that your first request may still be running when Stripe sends the retry.

For example, imagine your webhook handler does this:

Receives invoice.paid
Calls the Stripe API
Sends a welcome email
Updates several database records
Finally returns 200

If that takes too long, Stripe can retry while the first request is still executing.

Now you have two workers processing the same event.

The Idempotency Check That Looks Correct

A common implementation is:

if (WebhookEvent::where('stripe_event_id', $event->id)->exists()) {
return response()->json(['received' => true]);
}

WebhookEvent::create([...]);

Looks reasonable.

It isn't safe.

The Race Condition

Two requests can execute the check at almost exactly the same time:

Worker A: SELECT ... → no row found
Worker B: SELECT ... → no row found
↑ both pass the check

Worker A: INSERT → succeeds
Worker B: INSERT → duplicate key error
↓
HTTP 500
↓
Stripe retries

This is a classic time-of-check-to-time-of-use race condition.

The application-level exists() check cannot close that window.

And webhooks are exactly the type of traffic that exposes small concurrency windows: retries, bursts, and overlapping requests.

Put the Guarantee in the Database

The real protection belongs at the database level:

$table->string('stripe_event_id', 191)->unique();

Now the database guarantees that the same Stripe event cannot be inserted twice.

When a concurrent request hits the unique constraint, catch the duplicate-key exception and treat it as a successful duplicate delivery.

The important distinction is:

A duplicate webhook is not a failure. It is an already-processed event.

Your responsibility is to make sure the resulting state change happens once.

Handle Multiple Database Engines

If you develop with SQLite but deploy to MySQL or PostgreSQL, don't hard-code a single error code.

For example:

private function isUniqueViolation(QueryException $e): bool
{
$sqlState = $e->errorInfo[0] ?? null;
$driverCode = $e->errorInfo[1] ?? null;

// MySQL 23000/1062, PostgreSQL 23505, SQLite 23000/19.
return $sqlState === '23000'
    || $sqlState === '23505'
    || $driverCode === 1062
    || str_contains(
        $e->getMessage(),
        'UNIQUE constraint failed'
    );

}
Test the Race, Not Just the Happy Path

A normal unit test won't prove that your implementation is concurrency-safe.

You need to simulate the race itself.

One approach is to use DB::listen() in Pest, inject a conflicting insert during the controller's own insert, and assert that the webhook still returns 200 with something like:

{
"duplicate": true
}

rather than returning 500.

That's exactly the kind of test that catches bugs hidden behind otherwise-green test suites.

Don't Do Real Work Inside the Webhook Request

The second problem is closely related to the first.

Stripe has a timeout.

Your application does not control how long Stripe is willing to wait.

If your webhook handler spends too much time processing the event, Stripe can give up and retry.

Now you have overlapping executions again.

The Webhook Should Be Boring

The HTTP endpoint should do roughly four things:

Verify the signature
Store the event
Dispatch a job
Return 200

That's it.

For example:

// Signature verified above

$record = WebhookEvent::create([...]);

ProcessStripeWebhook::dispatch(
$record->getKey(),
$eventId,
$eventType,
);

return response()->json(['received' => true]);

Everything expensive happens asynchronously.

Queue IDs, Not the Entire Payload

There is another detail that is easy to overlook.

Pass identifiers to the queue—not the entire Stripe payload.

ProcessStripeWebhook::dispatch(
$record->getKey(),
$eventId,
$eventType,
);

Why?

A large invoice.paid event containing dozens of line items can be hundreds of kilobytes.

If Stripe retries the request three times and you serialize that entire payload into your queue on every attempt, you're unnecessarily multiplying your Redis memory usage.

The event payload is already stored durably in your database.

The queue only needs the IDs required to retrieve it.

Configure Your Retry Policy

The default queue configuration is rarely ideal for payment webhooks.

For example:

public int $tries = 3;

public int $timeout = 60;

public function backoff(): array
{
return [10, 30, 60];
}

This gives failed processing attempts some breathing room without retrying aggressively.

But retries aren't enough.

You also need a proper failure strategy.

Failed Events Must Remain Replayable

This is the subtle part.

When the job fails permanently, do not mark the webhook as processed.

public function failed(?Throwable $exception): void
{
Log::error('Stripe webhook job failed permanently.', [
'stripe_event_id' => $this->stripeEventId,
'error' => $exception?->getMessage(),
]);

// Deliberately NOT marking processed_at.
// The event remains replayable.

}

Why?

Imagine this sequence:

Stripe event received
↓
Event stored
↓
Job dispatched
↓
Redis/API/database problem
↓
Job fails permanently
↓
Event marked "processed"

You've now created a much worse problem.

A temporary infrastructure failure has effectively deleted a payment event.

Keep failed events replayable.

A Failed Payment Shouldn't Immediately Lock Your Customer Out

This one has a direct impact on customer experience.

A card gets declined.

Your webhook receives the failed payment event.

Your application immediately revokes access.

The customer was planning to update their card tomorrow.

Now they can't access their account.

Meanwhile, Stripe's Smart Retries may still be attempting to recover the payment.

Your application has effectively given up before Stripe has.

Give Failed Payments a Grace Period

Instead of immediately terminating access, move the subscription into a recoverable state:

$subscription->forceFill([
'stripe_status' => 'past_due',
'ends_at' => $subscription->ends_at
?? now()->addDays($graceDays),
])->save();

With Laravel Cashier, ends_at determines when access stops.

By pushing that date into the future, your application can continue treating the customer as subscribed while Stripe continues its payment recovery process.

For example:

Payment fails
↓
past_due
↓
7-day grace period
↓
Stripe retries payment
↓
Payment succeeds
↓
Subscription restored
The Part People Forget: Reversal

When payment succeeds again, remove the grace-period state:

// on invoice.paid

$subscription->forceFill([
'stripe_status' => 'active',
'ends_at' => null,
'trial_ends_at' => null,
])->save();

Clearing ends_at matters.

Otherwise, a customer who successfully recovered their payment can remain flagged as cancelling.

Your UI might say:

“Your subscription is ending.”

Your dunning emails might say:

“Your subscription will expire soon.”

Even though the customer already paid.

That's a state-management bug.

Two More Details That Are Easy to Get Wrong

The three issues above are the big ones.

But there are two smaller implementation details worth getting right.

Verify the Signature Against the Raw Request Body

Stripe signs the exact bytes it sends.

Don't decode and re-encode the JSON before verification.

Correct
$payload = $request->getContent();
Broken
$payload = json_encode($request->all());

Those are not guaranteed to produce identical bytes.

The safe sequence is:

Raw request body
↓
Signature verification
↓
JSON decoding
↓
Event processing

Not:

Request
↓
Decode JSON
↓
Re-encode JSON
↓
Verify signature

Nothing upstream should modify the request body before verification.

In Laravel 11, keeping the webhook route in routes/api.php also avoids unnecessary session/CSRF middleware around the endpoint.

Enforce the Timestamp Tolerance

A valid signature from last week is still a replayable request.

Signature verification should therefore include an appropriate timestamp tolerance.

Fail Closed When the Webhook Secret Is Missing

Never do this:

if (!$secret) {
// Skip verification
}

That turns a configuration mistake into a security vulnerability.

If STRIPE_WEBHOOK_SECRET is missing, reject the request.

Make the problem obvious:

[stripe-kit] Stripe configuration incomplete:
STRIPE_WEBHOOK_SECRET not set.

The webhook endpoint will reject every request
until this is configured.

A loud failure in production is much better than silently accepting unsigned payment events.

What I Actually Built

I packaged these patterns into a drop-in Laravel + Cashier Stripe webhook kit.

Not a course.

Not a complete SaaS boilerplate.

Just the parts that tend to break.

Test Coverage

The current test suite:

40 tests passed
106 assertions

Duration: 2.49s

Tested against:

Laravel 11.56
Cashier 15.8
Stripe PHP SDK 16.6
Pest 3.8

The tests run against MySQL rather than SQLite because the unique-index and concurrency behaviour are central to the implementation.

Testing only on SQLite could give you a false sense of confidence.

What's Included
Raw-body Stripe signature verification with configurable tolerance
Database-enforced webhook idempotency
Concurrency-safe duplicate handling
Queue-based processing
Three attempts with exponential backoff
Replayable failed events
Subscription synchronization for seven relevant Stripe event types
Failed-payment grace periods
Correct grace-period reversal after successful payment
php artisan stripe:status for pipeline health checks
php artisan stripe:replay for unfinished events
DDEV environment with PHP, MySQL 8, Redis, Mailpit, and Stripe CLI
Six documentation guides covering deployment and troubleshooting
Supervisor and systemd deployment configurations
Symptom → cause → fix troubleshooting reference

Get the kit: https://boukataya.gumroad.com/l/nggzho

What It Doesn't Include

I'd rather make this explicit before you buy it.

No frontend

There is no:

Blade frontend
Inertia
Livewire
SPA
Checkout UI

The part that creates subscriptions is yours.

This kit handles what happens after Stripe starts sending events back to your application.

No authentication scaffolding

There is no auth system or admin panel.

Use something like Breeze or Filament depending on your application.

No Stripe account or products

You still need to configure your own:

Stripe account
Products
Prices
Webhook endpoint
API credentials
No magic guarantee

Stripe has edge cases.

This isn't a promise that your billing system can never fail.

It's a tested foundation built around Cashier's established patterns, with the failure modes that are easy to overlook handled explicitly.

If You're Building This Yourself

If you take nothing else from this article, take these three points:

Put the uniqueness guarantee in the database $table->string('stripe_event_id', 191)->unique();

Application-level exists() checks are not enough.

Queue the work

Your webhook should follow this flow:

Verify
↓
Store
↓
Dispatch
↓
Return 200

Don't perform expensive business logic inside the HTTP request.

Don't revoke access on the first failed payment

Stripe may still be retrying.

Give the customer a grace period and clear that grace period when the payment succeeds.

The Bigger Lesson

Stripe webhooks aren't difficult because the happy path is complicated.

They're difficult because distributed systems don't care about your happy path.

Requests overlap.

Networks fail.

Queues fail.

Payments fail.

Retries happen.

And the database has to be the final source of truth when two workers believe they're processing the same event.

That's where most of the bugs live.

If you're building this yourself, hopefully this saves you a week of debugging.

If you'd rather not rediscover these details at 3 AM:

https://boukataya.gumroad.com/l/nggzho

And if you've built a Stripe integration yourself, the interesting question isn't whether it works.

It's:

What happens when it doesn't?

I Built a Production-Ready Laravel SaaS Starter Kit

Mohamed Sadok — Sat, 05 Sep 2026 11:12:42 +0000

Starting a new SaaS project often means rebuilding the same foundation:

Authentication
Password reset
Email verification
Dashboard layouts
User management
Settings pages
Database structure
Docker configuration
Email testing
Authorization and validation
That repetitive setup can take days before the actual product work begins.

I built Laravel SaaS Starter Kit to provide a clean, extensible starting point for SaaS products, MVPs, internal tools, and client applications.

What’s included?
Laravel 13 and PHP 8.3+
Registration, login, logout, and remember me
Password reset and email verification
Login throttling and secure password hashing
Responsive Blade and Tailwind dashboard
Database-backed dashboard statistics
Admin-only user management
Search and pagination
User roles and authorization policies
Profile, password, and account settings
MySQL migrations and seeders
Docker Compose support
Mailpit for local email testing
Vite and Tailwind CSS
PHPUnit feature tests
Production setup and deployment documentation
Custom error pages and reusable Blade components
The project includes realistic demo data so the dashboard feels useful immediately after seeding the database.

Why I built it
I wanted a Laravel foundation that felt closer to something a professional developer or small agency would actually use, rather than a basic tutorial project.

The goal is to remove repetitive infrastructure work while keeping the code familiar and easy to customize. It uses Laravel-native patterns such as controllers, policies, Eloquent models, Blade components, migrations, factories, and feature tests.

Built for
Freelance developers
SaaS founders
Web agencies
Full-stack developers
Small development teams
Internal tools and MVPs
The starter kit is available as a downloadable product for developers who want to move from idea to working SaaS foundation faster.

I’d love to hear what you usually build first when starting a new Laravel SaaS project. Which repetitive setup task takes the most time for you?

laravel #php #saas #opensource #webdev

link :https://boukataya.gumroad.com/l/zeovfd

Build a Premium Developer Portfolio in Minutes with This Next.js Template

Mohamed Sadok — Sat, 29 Aug 2026 23:51:00 +0000

If you want a portfolio that looks premium, feels modern, and helps you land freelance work or job opportunities, this template is built for that.

I created a polished Next.js portfolio template designed for developers, freelancers, and founders. It includes a clean landing page, project showcase, blog, resume section, contact page, and modern dark/light theming.

Demo:
https://portex-blue.vercel.app/

Product:
https://boukataya.gumroad.com/l/gdnxr

Why I built it
A lot of portfolio templates feel generic or outdated. I wanted something that feels more like a premium product site than a basic starter template.

This template is built with:

Next.js
TypeScript
Tailwind CSS
Framer Motion
Responsive layout
Modern portfolio sections
What’s included
Hero section
About page
Projects showcase
Blog section
Resume page
Contact form
Theme switcher
Clean and editable content structure
Why this helps
Instead of spending days building a portfolio from scratch, you can start with a strong, production-ready foundation and customize it to your brand.

It’s especially useful if you want to:

showcase your work
attract freelance clients
land product or engineering jobs
present yourself as a polished developer
Demo & product
Live preview:
https://portex-blue.vercel.app/

Buy the template:
https://boukataya.gumroad.com/l/gdnxr

If you want a portfolio that looks more premium and feels closer to a real product website, this is a great starting point.

Launch Your AI SaaS Website Without Starting From Scratch

Mohamed Sadok — Wed, 19 Aug 2026 14:01:05 +0000

Building an AI product is difficult enough. Your website should not be another six-week project.

Many AI startups spend too much time assembling basic marketing pages: a hero section, feature grid, pricing table, FAQ, blog, contact page, responsive navigation, and SEO setup. Each part seems simple on its own, but together they create a large amount of design and development work.

That is why I built Lumen, a premium AI SaaS landing page template for founders, developers, and small teams.

A Complete Starting Point for AI Products
Lumen is designed for AI SaaS products, developer tools, productivity apps, internal knowledge platforms, and technical startups.

Instead of beginning with an empty project, you get a complete marketing website with:

A conversion-focused homepage
Product mockups and feature sections
Use cases and customer testimonials
Pricing with monthly and yearly billing options
FAQ accordion
Blog index and article pages
About and contact pages
Privacy policy and terms pages
Custom 404 page
Responsive mobile navigation
Light and dark themes
The demo content presents an AI document intelligence product that connects company knowledge sources and returns answers with citations. Every section is structured so you can replace the copy with your own product details.

Built for Modern Development
Lumen uses a straightforward, maintainable stack:

Next.js 16
React 19
TypeScript
Tailwind CSS v4
Lucide icons
next-themes
The project uses the Next.js App Router and follows a clean component-based structure. Site content is separated into typed files, making it easy to update your brand, navigation, pricing, features, testimonials, FAQ entries, and blog posts.

You do not need to hunt through every component to change basic content.

Designed to Be Customized
The template includes a central site configuration file for the most important brand details:

Product name
Tagline
Description
Website URL
Contact email
Social links
Call-to-action labels
Announcement banner
Homepage statistics
The visual system is also easy to adapt. Update the theme colors and font configuration to create a brand identity that feels specific to your product rather than looking like a generic starter template.

Ready for Real Product Integrations
Lumen is a frontend marketing template, but it is prepared for the services most products need.

You can connect:

Stripe payment links or checkout
Formspree, Resend, or your own form endpoint
Authentication providers
Analytics platforms
Your own API routes
A custom backend
The template does not force you into a particular SaaS architecture. It gives you the presentation layer, structure, and visual foundation while leaving the product-specific integrations up to you.

SEO and Deployment Included
The project includes essential SEO infrastructure out of the box:

Page-specific metadata
Sitemap generation
Robots configuration
Open Graph image generation
Static blog routes
Semantic HTML
Accessible focus states
Keyboard-friendly FAQ interactions
Once your content is customized, the project can be deployed to Vercel with the standard Next.js workflow:

Who Is Lumen For?
Lumen is a good fit for:

AI startup founders
Indie hackers
SaaS developers
Agencies building AI product sites
Product designers creating a fast MVP
Teams launching a developer tool
Anyone who needs a professional SaaS website quickly
It is especially useful when the product is still evolving and you need a strong public-facing website before building every marketing feature from scratch.

Start With the Product, Not the Boilerplate
A landing page should communicate what your product does, who it helps, and why people should trust it.

Lumen gives you those essential building blocks in one polished project, so you can spend more time refining your product and less time recreating common website patterns.

Get the template on Gumroad:

demo :

Lumen — AI SaaS Landing Page Template

Lumen — AI SaaS Landing Page TemplateLaunch your AI product with a polished, conversion-focused website built with Next.js, React, TypeScript, and Tailwind CSS.Lumen gives you the complete marketing foundation for an AI SaaS, startup, or developer tool. Replace the demo content with your own brand, connect your forms and payments, and deploy to Vercel.Included Complete responsive homepage Hero section with product mockup Features and use cases sections How-it-works workflow Testimonials and logo cloud Pricing page with monthly/yearly toggle FAQ accordion Blog index and article pages About, contact, privacy, and terms pages Light and dark mode Mobile navigation SEO metadata, sitemap, robots.txt, and Open Graph image generation Accessible components and keyboard-friendly interactions Clean TypeScript architecture Zero-config Vercel deployment Built With Next.js 16 React 19 TypeScript Tailwind CSS v4 Lucide icons next-themes Important NotesThis is a frontend marketing template. Forms, authentication, analytics, and payment links are prepared for integration but are not connected to external services. No database is required for the landing page.Use Lumen to create a professional AI product website without starting from an empty project.demo : demo: https://lumenv-2.netlify.app/

boukataya.gumroad.com

Lumen: The AI SaaS Landing Page Template That Ships in Hours

Mohamed Sadok — Tue, 18 Aug 2026 13:59:35 +0000

Launching an AI product is hard. Marketing it shouldn’t be.

For indie hackers and startup founders building AI-powered tools, the biggest friction point isn’t always the product — it’s getting it in front of customers. A professional landing page matters more than ever in a crowded market. But building one from scratch? That’s hours of design tweaking, component wrangling, SEO setup, and deployment configuration.

Enter Lumen: a premium, dark-first landing page template designed specifically for AI products and SaaS startups. It’s the answer to founders who ask, “Can I launch a beautiful, conversion-focused marketing site this afternoon — not this weekend?”

What is Lumen?

Lumen is a production-ready landing page template built with modern web technologies. While the template itself showcases a document Q&A engine (turning PDFs and Notion pages into cited answers), Lumen is versatile enough to market any AI product: an LLM wrapper, a data analytics tool, a generative design platform, or a specialized AI agent.

Core Concept:

Turn messy documents into accurate answers in seconds
A source-backed Q&A engine for documents and knowledge bases
Plain English queries with every answer cited

But here’s the beauty: the template is completely customizable. Change the copy, rebrand the colors, swap the use cases, and it works for your AI product.

The Technical Foundation

Built on a modern, no-bloat stack:

Next.js App Router — Server components, streaming, optimized builds
TypeScript (strict mode) — Type safety from day one
Tailwind CSS v4 — Utility-first styling, minimal bundle size
next-themes — Seamless light/dark mode switching
Lucide icons — Beautiful, lightweight icon system

The philosophy: No UI library dependencies. No backend database. No environment variables. Deploy to Vercel with one click.

What You Get

9 Complete Pages

Homepage — 13 conversion-focused sections
Pricing — Monthly/yearly toggle, interactive comparisons
Blog — Index page + individual post pages with related content
About — Team and mission storytelling
Contact — Email capture form (ready to wire up to Formspree/Resend)
Privacy & Terms — Legal pages with placeholder copy
Custom 404 — Branded error page

13 Homepage Sections

Navbar — Sticky header with light/dark toggle
Hero — Promise + CTAs + proof stats + CSS-only product mockup
Logo Cloud — Marquee of fake customer logos
Problem — Paint the pain point
Features — Highlight 3–4 key capabilities
How It Works — 3-step workflow visualization
Product Preview — Full fake app screenshot
Use Cases — Real-world applications
Testimonials — Social proof with quotes + avatars
Pricing — Plans with feature matrices
FAQ — Accessible, animated accordion
Final CTA — Email capture or signup button
Footer — Links, socials, copyright

Design System

Dark-first aesthetic — Deep ink backgrounds, premium feel
Warm accents — Amber highlights + soft teal secondary
Textures — Subtle grain and grid overlays for depth
Glass panels — Semi-transparent surfaces with backdrop blur
Rounded cards — rounded-2xl for modern, friendly feel
Micro-interactions — Button shine sweep, card hover lift, animated accordions

Key Features

1. SEO Ready Out of the Box

Per-page metadata with Open Graph
sitemap.ts for search engine crawling
robots.txt for crawler directives
Semantic HTML with clean heading hierarchy
Canonical URLs for duplicate prevention

2. Accessibility First

Keyboard navigation throughout
Visible focus states on all interactive elements
ARIA-wired forms and navigation
Reduced-motion support for animations
Screen reader friendly structure

3. Light & Dark Mode

Toggle in the navbar
Persistent across sessions (via next-themes)
Automatic OS preference detection
No layout shift on theme change

4. All Copy is Centralized

Want to rebrand Lumen for your AI product? Every marketing message lives in /lib files:

site.ts — Brand name, tagline, email, CTAs, stats
nav.ts — Navigation and footer links
pricing.ts — Pricing plans and features
features.ts — Core feature descriptions
testimonials.ts — Social proof quotes
faq.ts — Frequently asked questions
blog.ts — Blog post metadata
legal.ts — Privacy and terms copy

No digging through components. No hunting through JSX. One place to edit everything.

5. Zero Configuration Deployment

Push to GitHub
Import into Vercel
One click deploy
No environment variables
No database migrations
HTTPS by default
Global CDN

Customization: The 10-Minute Rebrand

Want to make Lumen your own? Three changes:

| What | Where |

| — — | — — |

| Brand name, tagline, stats, CTAs | src/lib/site.ts |

| Colors (amber/teal accents, ink backgrounds) | CSS variables in src/app/globals.css |

| Marketing copy | All src/lib/*.ts files |

Update these three places and your entire site rebrands itself — navbar, footer, metadata, everything.

Built-in TODOs for Developers

Search the codebase for TODO to find integration points:

Email capture — Connect to Formspree, Resend, or your email service
Payment links — Point pricing CTAs at Stripe checkout
Analytics — Add Plausible, PostHog, or Google Analytics snippet
Authentication — Wire up your login/signup flow

Who Should Use Lumen?

Ideal For:

AI founders launching their first product
SaaS startups in crowded markets (need to stand out fast)
Document processing tools — Q&A, RAG, summarization
AI agents — Specialized LLM wrappers
Data intelligence platforms — Analytics, insights, predictions
Anyone who wants a professional site yesterday

Not For:

Marketing teams needing highly custom design
Enterprise deployments with complex authentication
Products requiring a headless CMS
Teams wanting to build from scratch (template removes that option)

The Competition

Let’s be honest: landing page builders exist. Webflow, Framer, Wix. But they require:

Monthly subscriptions
Slow design/deploy cycles
Vendor lock-in
Limited customization without designers

Lumen is different:

Download the Medium App

✅ Own it. It’s yours. Full source code.
✅ Fast. Ship in hours, not days.
✅ Cheap. One-time purchase, no recurring fees.
✅ Flexible. Change anything, deploy anywhere.
✅ Modern. Built with current best practices.
✅ Scalable. Handles millions of visitors on Vercel’s edge network.

Real-World Use Cases

1. AI-Powered Document Q&A

A startup building a tool to turn company wikis into searchable AI assistants. Uses Lumen to launch with gorgeous product preview, feature breakdown, and pricing tiers.

2. Specialized LLM Wrapper

An indie developer created a domain-specific language model for medical research. Lumen’s hero section and testimonials sell the accuracy and speed. Blog section builds SEO credibility.

3. Data Analytics Tool

A team built an AI-powered analytics dashboard. Lumen’s “How It Works” section explains the 3-step process, and the pricing section handles different team sizes.

4. AI Content Generator

A founder’s side project for generating product copy. Lumen’s blog section drives organic traffic. Pricing tiers separate freemium from pro users.

Technical Deep Dive

Performance

Next.js App Router ensures fast client-side navigation
Server components by default reduce JavaScript bundle
Tailwind CSS v4 generates only used styles
Image optimization via next/image
Font optimization via next/font
Vercel Edge Functions for global CDN delivery

Result: Core Web Vitals in the green zone out of the box.

Styling Architecture

Lumen uses Tailwind CSS with custom design tokens defined in CSS variables:


— color-accent: hsl(var( — accent) / <alpha-value>);

— color-accent-soft: hsl(var( — accent-soft) / <alpha-value>);

Change a single variable, and the theme updates everywhere. No cascading issues. No specificity wars.

Component Structure


components/

├── layout/ # Navbar, Footer, Container, Section

├── sections/ # 13 homepage sections

├── ui/ # Reusable: Button, Badge, Card, Accordion

└── blog/ # BlogCard, BlogContent

Each section is self-contained, making it easy to move, hide, or reorder sections on the homepage.

Cost of Ownership

Upfront:

Template purchase (one-time)

Recurring (minimal):

Vercel hosting (~$20/month, or free for small sites)
Optional: Email service (Formspree, Resend, SendGrid)
Optional: Analytics (Plausible, PostHog)
Optional: Blog CMS if you want (headless CMS like Sanity, not required)

Total Cost: $0–$50/month depending on scale. Compare that to a custom agency build ($5K–$50K) or a Webflow subscription ($12/month + designer time).

Deployment

Vercel (Recommended)

Push repo to GitHub
Import project in Vercel
One click deploy
Automatic SSL, domain setup, branch previews

Other Platforms

Works anywhere Node.js runs:

AWS EC2 + ECS
DigitalOcean App Platform
Railway
Render
Self-hosted VPS

SEO & Marketing

Lumen is built for organic discovery:

Semantic HTML — Proper heading hierarchy, structured data
Fast load times — Top Core Web Vitals
Mobile responsive — Works beautifully on all devices
Blog system — Build authority with keyword-targeted posts
Open Graph meta tags — Pretty social media previews
Sitemap & robots.txt — Search engines index everything
Canonical URLs — Avoid duplicate content penalties

For AI products especially, a strong marketing site + blog = SEO authority.

Limitations & Honest Assessment

What Lumen is NOT:

A CMS (blog posts are data files, not database records)
A backend as a service (you integrate with external services)
A drag-and-drop builder (requires code edits for major changes)
A design tool replacement (opinions baked into the template)

Best Practices:

Customize copy before launching (don’t use fake product names)
Replace fake logos with real customer logos (or remove the section)
Update testimonials with real reviews (or remove)
Wire up email capture forms before promoting them
Add analytics to track conversions

Getting Started

Installation (5 minutes)


# Clone or download the template

cd lumen

# Install dependencies

npm install

# Start dev server

npm run dev

# Open http://localhost:3000

Customization (10 minutes)

Edit src/lib/site.ts with your product name and tagline
Update colors in src/app/globals.css
Edit copy in src/lib/*.ts files
Replace favicon and OG image
Deploy to Vercel

Ready for Launch


npm run build

npm start # test production build locally

# Then push to GitHub and deploy

Conclusion

Lumen is a powerful tool for founders who want to move fast. It removes the friction of building a marketing site from scratch while remaining flexible enough to customize for any AI product.

In a market where first impressions matter — and where founders have limited time — Lumen lets you ship a professional, conversion-focused landing page today. The template handles the design, performance, and SEO. You focus on the product and marketing.

The result? A beautiful marketing site that doesn’t look like a template, loads like a dream, and converts like it was designed by a professional agency.

Ship fast. Stand out. Win customers.

— -

Quick Links

buy : https://boukataya.gumroad.com/l/tfwgq
preview: https://celadon-longma-d9d6cd.netlify.app/