DEV Community: Mahmoud Farouk

Designing an AI ad pipeline where a failed job never costs the customer a credit (Spring Boot)

Mahmoud Farouk — Mon, 12 Oct 2026 07:00:00 +0000

AdPlatformForge turns one product photo into a short video ad or a social post design, in Arabic, French or Hassaniya. It is a multi-tenant SaaS: Spring Boot on the back end, Angular on the front, PostgreSQL, FFmpeg for video, and an LLM for the script.

AI calls are slow, flaky and cost money. This post is about the four design choices that kept the system honest: the pipeline shape, the provider interfaces, the credit ledger and the safety checks.

The pipeline is a line of persisted steps

A generation is not one request. It is a production line, and each step writes its status and progress to the database before doing the work:

step(id, GenerationStatus.ANALYZING, 10);          // read the photo and the brief
step(id, GenerationStatus.ENHANCING_IMAGE, 25);    // clean up the product image
step(id, GenerationStatus.WRITING_SCRIPT, 40);     // headline, lines, call to action
// moderation check here
step(id, GenerationStatus.SYNTHESIZING_VOICE, 55); // video modes that speak
step(id, GenerationStatus.RENDERING, 70);          // design or video
// COMPLETED at 100

The method runs on a dedicated executor with @Async("studioExecutor"), and the tenant id is set on a thread-local at the start and cleared in a finally block, because the async thread does not inherit the request context.

Because every step is persisted, the front end just polls the job and shows real progress, and failures are never silent. There is one more detail I am glad I added. If the server restarts while jobs are running, they can never finish, so on startup they are failed explicitly:

@EventListener(ApplicationReadyEvent.class)
public void failInterruptedJobs() {
    // QUEUED, ANALYZING, ENHANCING_IMAGE, WRITING_SCRIPT, SYNTHESIZING_VOICE, RENDERING
    // -> FAILED, "The server restarted while this job was running. Please create it again."
}

A job stuck at "Rendering 70%" forever is the worst experience. A clear failure that refunds the customer is much better.

Every AI provider sits behind an interface

The pipeline never talks to a vendor directly. It depends on small interfaces: ScriptWriter, ImageEnhancer, VoiceSynthesizer, AvatarVideoGenerator, BrollVideoGenerator, KineticVideoRenderer, DesignComposer. Real implementations (an LLM for scripts, an image-cleanup service, a voice service, an avatar-video service, FFmpeg for kinetic video) sit next to mock implementations of the same interfaces.

This paid off three ways:

Development without keys. The whole pipeline runs end to end in a mock mode, so I could build and test the UI and billing without spending anything.
Swappable vendors. Changing a provider is a new class and a config change, not a pipeline rewrite.
A single error type. Providers throw a ProviderException with a message that is safe to show. Anything else becomes a generic "Something went wrong" while the real error goes to the log.

Credits: a failed ad must cost nothing

The product is billed in credits. Money-like numbers deserve a ledger, not a counter, so every movement is a row: plan grants, top-ups, charges, refunds and manual adjustments.

public enum CreditEntryType {
    PLAN_GRANT, PLAN_EXPIRE, TOPUP, GENERATION_CHARGE, REFUND, ADJUSTMENT
}

Two buckets exist per tenant. Plan credits are granted monthly and do not roll over. Top-up credits are purchased and never expire. Spending uses plan credits first. The tenant row is locked while a balance changes, so two parallel generations cannot both spend the same credit.

The refund is the part I care about most:

@Transactional
public void refund(String tenantId, Long generationId, String reason) {
    String ref = "gen-refund-" + generationId;
    if (ledger.existsByTenantIdAndReference(tenantId, ref)) return;   // safe to call twice
    // ...find the original charge, give back exactly what it took from each bucket
}

It is idempotent through a unique reference on the ledger, so retries and double calls cannot refund twice. It also handles an edge case: if the original charge used plan credits from a previous month, those credits would have expired, so they come back as top-up credits instead of vanishing.

The pipeline calls the refund from both failure paths, a provider failure and a blocked script:

/** A failed or blocked ad must never cost the customer anything. */
private void refund(String tenantId, Long id, String reason) { ... }

The affordability check also happens before anything is stored (assertAvailable), so a customer without enough credits fails fast, before any slow work starts.

Safety: a conservative guard plus a human

Generated ads can go wrong in ways that matter: politics, adult content, gambling, alcohol, unverifiable health promises. A ContentGuard checks the script before any rendering money is spent. It is keyword-based and covers three languages, and its own Javadoc is honest about the limits: it is a conservative safety net, not a replacement for the LLM's system-prompt rules or for manual approval.

The riskiest feature, using a licensed likeness of a public figure, never relies on a keyword list. It is gated by a valid license, an approval queue, a usage log of every request (approved or not) and a kill switch. A blocked request is marked REJECTED, logged and refunded.

What I would tell my past self

Persist every pipeline step. Progress bars and failure handling come for free.
Put each vendor behind an interface and build the mocks first.
Treat credits as a ledger with idempotent operations and exact refunds.
Run cheap checks (balance, moderation) before expensive work.
Be honest in code comments about what a safety check does not cover.

Talk to me

I build SaaS products, async pipelines and billing systems end to end, and I take freelance full-stack and backend projects: mahmoud-farouk-portfolio.vercel.app.

How do you handle refunds and idempotency in your own billing code? I would like to compare notes.

I build my Notion templates as code: generate, review on disk, then push

Mahmoud Farouk — Mon, 05 Oct 2026 07:00:00 +0000

Most Notion templates are built by hand: click a database into existence, add properties, drag views around, copy the page. That works once. It does not work when you want to rebuild it after a Notion change, review exactly what it will create, or ship several templates that share a style.

So I build mine as code. Each template is a small Node.js project that generates a list of Notion API calls, lets me read them, and only then pushes them. This post walks through the design using one of them, an Architecture Snippet Vault: a Snippets database and a Collections database linked both ways, six views, a dashboard page and sample content.

Two steps, and a review in between

The script works in two steps:

Local review. It writes the exact API payloads to schema.json and the page text to layout.md. No token and no network needed.
Push. It shows what it will create, asks for confirmation, and on yes runs the files on disk through the official @notionhq/client.

The second point matters. What gets pushed is not regenerated in memory. It is the file I (or a buyer) just edited, so a changed property name or a deleted view in schema.json is exactly what reaches Notion.

Command	Regenerates files	Prompts	Pushes
`npm run review`	yes	no	no
`npm start`	yes (overwrites edits)	yes	on `yes`
`npm run push`	no	yes	on `yes`

The confirmation is a plain yes. Anything else exits without contacting Notion.

An allowlist instead of trust

schema.json is an ordered list of API calls (33 of them for this template). A file that tells a script what to call is a file that could call anything, so the runner only accepts a fixed set:

// The only API calls schema.json may make. An edited or foreign schema cannot call anything else.
const CALLS = {
  "pages.create": (notion, payload) => notion.pages.create(payload),
  "pages.updateMarkdown": (notion, payload) => notion.pages.updateMarkdown(payload),
  "databases.create": async (notion, payload) => { /* ... */ },
  "dataSources.update": (notion, payload) => notion.dataSources.update(payload),
  "views.create": (notion, payload) => notion.views.create(payload),
  // plus retrieve/list/update helpers
};

for (const [i, step] of schema.steps.entries()) {
  if (!CALLS[step.call]) throw new Error(`schema.json step ${i + 1}: unsupported call "${step.call}".`);
}

The whole schema is validated before the first request is sent, so a bad step fails early instead of half way through a push.

IDs that do not exist yet

The awkward part of building Notion structures through an API is that IDs only exist after something is created: the page, the database, every property. A relation needs the other database's ID, and a view refers to properties by ID.

The generated steps solve this with placeholders and a capture map. A step says which fields of its response to remember, and later steps use them as {{...}}:

async function runStep(notion, step, ctx, chunks) {
  const response = await CALLS[step.call](notion, resolve(step.payload, ctx, chunks));

  for (const [key, dotted] of Object.entries(step.capture ?? {})) {
    const value = getPath(response, dotted);
    if (value == null) throw new Error(`The ${step.call} response has no "${dotted}" to keep as ${key}.`);
    ctx[key] = value;
  }
  // View configurations refer to properties by ID, which Notion only reveals after creation.
  if (step.captureProperties) { /* remember PROPERTY_ID:<database>:<name> */ }
  return response;
}

If a placeholder has no value, the error says which step should have provided it and that it "failed, was skipped, or comes later in schema.json". The message points straight at the step that is missing something, instead of leaving you to guess.

Order matters too. Databases are appended to the end of a page, so the text around them has to be inserted in between. layout.md carries two  markers, and the script splits the text at them into three chunks and interleaves them with the database creation.

A formula that keeps itself honest

The vault tracks whether each snippet is still trustworthy. A Review Health formula labels it:

const REVIEW_HEALTH_FORMULA =
  'if(prop("Status") == "Deprecated", "⚫ Deprecated", ' +
  'if(empty(prop("Last Reviewed")), "⚪ Not reviewed", ' +
  'if(dateBetween(now(), prop("Last Reviewed"), "days") > 180, "🔴 Stale", "🟢 Fresh")))';

A "Review Queue" view is built on top of it, so the next thing to re-check is easy to find.

Formulas that depend on now() create a problem for templates: sample data ages. If the sample snippets carry fixed review dates, a template built once slowly turns every sample red. I handle it two ways:

Sample dates are set relative to the day the build runs, so a fresh build always shows a mix of Fresh and Stale.
A refresh command re-dates the samples later. It lists the dates it will set, asks for yes, and only touches pages whose title matches a sample in the seed file, so anything the user added is left alone.

Things I was honest about in the docs

Views are marked optional. If Notion rejects a view, the script warns and carries on, because all the data is already there.
Running the push twice creates a second copy. The IDs of everything created are saved to push-result.json, and the README says to delete the first copy before re-running.
The review step is not decoration. The README tells you to open schema.json and layout.md and edit them. The tool is built around the idea that you read before you push.

What I would tell my past self

Treat a template as a build artifact. Keep the source (seed data, schema builder, layout text) and generate the rest.
Put a human-readable review step between generating and sending.
Restrict what a data file can make your script do.
Anything that depends on now() needs a plan for sample data that ages.
When an API hands out IDs late, design placeholders and capture rules up front.

Talk to me

I build developer tools, automation and full-stack products, and I take freelance projects: mahmoud-farouk-portfolio.vercel.app.

If you build Notion templates, do you generate them or click them together? I am curious where the API still makes you fall back to the UI.

Building a multi-tenant POS and inventory system with Spring Boot and Angular: three design decisions that paid off

Mahmoud Farouk — Sat, 03 Oct 2026 10:33:24 +0000

Small shops need three things from software: sell quickly, know what is in stock and trust the numbers. I built a self-hosted inventory, point-of-sale and purchasing system for them, with Spring Boot 4 (Java 25), Angular 21 and PostgreSQL, running in Docker. It works in English, Arabic (right-to-left) and French, and every shop is an isolated tenant.

This post is not a feature tour. It covers three design decisions I would make again, with the real code behind each.

1. Tenant isolation that nobody can forget to apply

In a multi-tenant system the worst bug is a missing WHERE tenant_id = ?. One forgotten filter in one repository method and a shop sees another shop's sales.

So I do not rely on developers remembering. A Hibernate filter is switched on by an aspect before every service method runs:

@Aspect
@Component
public class TenantAspect {

    @PersistenceContext
    private EntityManager entityManager;

    @Before("execution(* com.enterprise.starter.kit.modules..service..*(..))")
    public void enableTenantFilter() {
        String tenantId = TenantContext.getTenantId();
        if (tenantId == null) return;

        Session session = entityManager.unwrap(Session.class);
        session.enableFilter("tenantFilter").setParameter("tenantId", tenantId);
    }
}

The tenant id comes from the authenticated user's JWT and lives in a TenantContext. Entities that carry the filter definition are restricted automatically; global tables such as subscription plans are skipped.

What I like about this: the rule is enforced in one place, new modules inherit it for free, and a code reviewer only has to check that an entity declares the filter, not that every query remembers it.

The trade-off is that it is implicit. Anything that runs outside the service layer (scheduled jobs, raw SQL) does not pass through the aspect, so it needs its own care.

2. A stock ledger you never edit directly

The product table has a quantityOnHand column, and it is tempting to just update it. I did not. Every change goes through an append-only stock_movements table:

/**
 * Audit ledger of every stock change. Positive quantity = stock in,
 * negative quantity = stock out. Never written directly - only via
 * the catalog adjust-stock, purchase-order receive, and sale-create flows,
 * so it always stays consistent with CatalogItem#getQuantityOnHand().
 */
@Entity
@Table(name = "stock_movements")
public class StockMovement extends BaseEntity {
    // catalogItem, movementType, quantity (+in / -out),
    // referenceType + referenceId (which sale or purchase order caused it),
    // optional variant id, note, occurredAt
}

There are only three ways stock moves: a manual adjustment, receiving a purchase order and creating a sale. Each writes a movement that points back to the thing that caused it.

That gives the shop owner a per-item history ("why is this at 3?") and gives me a debugging tool: when a number looks wrong, the ledger says which sale or purchase order did it.

3. A checkout that keeps working when the Wi-Fi does not

Shops lose connectivity. A cashier should not have to stop selling. The Angular POS queues cash sales locally and replays them when the browser reports it is online again:

const STORAGE_KEY = 'pos_offline_sale_queue';
const FAILED_STORAGE_KEY = 'pos_offline_sale_failed';

constructor() {
  window.addEventListener('online', () => { this.isOnline.set(true); this.syncQueue(); });
  window.addEventListener('offline', () => this.isOnline.set(false));
}

A few rules keep this honest:

Only cash and "other" sales are queued. Card payments need a live round trip to create and confirm a payment intent, so they cannot be faked offline.
The receipt is a preview. The server allocates the real invoice numbers when the sale syncs, so the offline receipt is built from a stored snapshot (totals, tax, line items), not from numbers I invented on the client.
Failures are never swallowed. If the server rejects a queued sale, for example because stock ran out while offline, it moves to a "failed sales" list for the cashier to review.

Signals (isOnline, queue, syncing, failedSales) keep the UI simple: the template just reacts to connectivity, the queue length and the failed list.

A grounded assistant, without sending data anywhere

The same system has a chat assistant that answers questions such as "which items are low on stock?". It runs on a local model through Ollama, so shop data never goes to a third-party AI service.

Two choices make a small local model usable:

Each question is sent with a fresh snapshot of that tenant's data, through the same tenant filter as every other screen.
The snapshot starts with a summary and every product carries a precomputed OK or LOW status, so the model never has to compare numbers itself. The prompt tells it to answer only from the snapshot and to say so when the answer is not there.

The assistant is read-only: it cannot sell, adjust stock or place orders.

What I would tell my past self

Put the safety rule (tenant filter) where it cannot be skipped, not in a coding guideline.
Treat stock as a ledger, not a number.
Design the offline path around what cannot work offline, and be explicit about it.
Small local models need pre-digested data, not raw tables.

Try it or talk to me

The system is part of a larger Spring Boot and Angular SaaS starter I maintain (the Arab Enterprise Kit). I also take freelance full-stack, backend and architecture projects: mahmoud-farouk-portfolio.vercel.app.

What would you do differently for the offline queue? I am curious how others handle replay conflicts.

Stop Starting with Microservices: Why I Built a Modular Monolith for my B2B SaaS Boilerplate

Mahmoud Farouk — Sun, 12 Apr 2026 22:46:28 +0000

If you've ever started a new B2B SaaS project, you know the drill. Before you write a single line of feature code that actually brings value to your users, you spend weeks (or months) wrestling with the exact same infrastructure:

Setting up Multi-tenancy (and worrying about data leakage).

Configuring stateless JWT authentication.

Handling database migrations.

Integrating payment webhooks safely (idempotency, anyone?).

As a Principal Software Developer, I realized this "setup fatigue" was killing momentum. So, I decided to build the ultimate boilerplate to solve this once and for all: the Arab Enterprise Kit (AEK).

But when it came to the architecture, I made a controversial choice for 2026: I completely ignored Microservices.

Here is why I went with a strict Modular Monolith instead, and how I structured the tech stack.

The Microservices Trap for Early-Stage SaaS
Microservices are fantastic for scaling massive engineering teams. But for solo founders or small teams launching a B2B SaaS, they introduce a DevOps nightmare:

Distributed tracing becomes mandatory.

Data consistency and distributed transactions (Saga patterns) slow down feature delivery.

Infrastructure costs spike before you even have your first paying customer.

The Modular Monolith Solution
Instead of splitting by network boundaries, I split by logical boundaries within the same deployment unit.

Here is the tech stack I chose for the AEK:

Backend: Java 25 & Spring Boot 4. We use Single-Schema Multi-Tenancy with Hibernate Filters. It ensures strict data isolation at the ORM level without the overhead of spinning up a new database per tenant.

Frontend: Angular 21 (Zoneless UI using Signals). Combined with native Tailwind RTL/LTR support, making it perfectly suited for global and MENA region applications.

Integrations: * Stripe Webhooks: Fully configured with idempotency keys to prevent double-charging during network retries.

Local AI (Ollama): Because B2B enterprise clients care deeply about privacy, sending data to 3rd party LLMs is often a dealbreaker. Integrating local AI ensures zero data leaks.

The Result?
By keeping everything in a well-structured monolith, you get the deployment simplicity of a single .jar file, but the clean separation of domains. If one module ever needs to scale independently, extracting it is straightforward because the boundaries are already respected in the code.

🎁 Get the Full 37-Page Architectural Blueprint
Before I even wrote the code for the AEK, I documented every single architectural decision, tradeoff, and pattern into a comprehensive blueprint.

If you are a technical founder or developer struggling with the initial architecture of your SaaS, you can grab the complete 37-page Architectural Blueprint for free here:

👉 https://mahmoudfarouk28.gumroad.com/l/sdmeap

I'd love to hear your thoughts. Have you fallen into the microservices trap early on, or are you team a monolith? Let's discuss in the comments! 👇