DEV Community: Mahmoud Farouk

Hibernate filters don't apply to findById: a multi-tenancy leak in Spring Boot 4

Mahmoud Farouk — Wed, 28 Oct 2026 12:00:00 +0000

Single-schema multi-tenancy with a Hibernate filter is a popular pattern. Every tenant table has a tenant_id column, a @Filter adds tenant_id = :tenantId to every query, and an aspect turns the filter on for each request. Lists, searches and reports are all isolated, and the tests for them pass.

There is one hole in it that is easy to miss, and my own starter kit had it. This is how it works and how version 5.3 closes it in two layers.

The gap described here is fixed in Arab Enterprise Kit 5.3, and the update is free for every v5.x license.

The hole

Spring Data's SimpleJpaRepository.findById calls EntityManager.find. Hibernate filters apply to queries (HQL, JPQL, Criteria and filtered collections). They do not apply to loading an entity by its primary key.

// Looks safe, is not: EntityManager.find ignores the tenant filter
Invoice invoice = invoiceRepository.findById(42L).orElseThrow();

So GET /api/invoices/42 sent by a user of company A can load company B's invoice, as long as A knows or guesses the id. Every list endpoint still looks perfectly isolated, because lists go through queries. A test suite that only checks listings will never see it.

deleteById goes through findById, so it has the same gap.

Layer 1: make findById a query

The fix at the repository level is to run the lookup as a JPQL query, so the filter applies. The kit does it once, in a repository base class:

public class TenantAwareRepository<T, ID> extends SimpleJpaRepository<T, ID> {

    private final EntityManager entityManager;
    private final JpaEntityInformation<T, ?> entityInformation;

    public TenantAwareRepository(JpaEntityInformation<T, ?> entityInformation, EntityManager entityManager) {
        super(entityInformation, entityManager);
        this.entityManager = entityManager;
        this.entityInformation = entityInformation;
    }

    @Override
    public Optional<T> findById(ID id) {
        if (id == null) {
            throw new IllegalArgumentException("The given id must not be null");
        }
        String idName = entityInformation.getRequiredIdAttribute().getName();
        String jpql = "select e from " + entityInformation.getEntityName() + " e where e." + idName + " = :id";
        return entityManager.createQuery(jpql, getDomainClass())
                .setParameter("id", id)
                .getResultStream()
                .findFirst();
    }
}

and registers it for every repository:

@EnableJpaRepositories(repositoryBaseClass = TenantAwareRepository.class)

Because deleteById calls findById, deletes are covered too. Entities that have no tenant filter (subscription plans, for example) behave exactly as before.

Layer 2: an explicit check in the services

A repository base class is easy to bypass later: someone adds a native query or calls the EntityManager directly. So the services that load tenant data by id also check ownership:

public final class TenantGuard {

    private TenantGuard() {}

    public static boolean ownedByCurrentTenant(BaseEntity entity) {
        return ownedByCurrentTenant(entity.getTenantId());
    }

    public static boolean ownedByCurrentTenant(String entityTenantId) {
        String tenantId = TenantContext.getTenantId();
        return tenantId != null && tenantId.equals(entityTenantId);
    }
}

Invoice existing = invoiceRepository.findById(id)
        .filter(TenantGuard::ownedByCurrentTenant)
        .orElseThrow(() -> new IllegalArgumentException("Invoice not found: " + id));

Note the error: another tenant's invoice looks exactly like a missing one. Answering "forbidden" would tell the caller that id 42 exists.

Fail closed when there is no tenant

The aspect that enables the filter has one more decision to make: what happens when no tenant is set at all? A scheduled job or a background thread that forgets to set it should not see every tenant's data.

if (tenantId == null) {
    if (isTenantAgnostic(joinPoint)) return;
    tenantId = NO_TENANT; // "__no_tenant__" matches no row
}
session.enableFilter("tenantFilter").setParameter("tenantId", tenantId);

The few services that really run without a tenant (sign-in, registration, payment webhooks that read the tenant from the payload) opt out with a @TenantAgnostic annotation. Everything else sees nothing instead of everything.

The tests that hold it in place

The kit's isolation tests seed two tenants and check each path, not just the listing:

listing as tenant A does not return tenant B's items
reading tenant B's item by id as tenant A is rejected
updating it by id is rejected and leaves it unchanged
deleting it by id is rejected and keeps the item
a background thread with tenant B's context sees only tenant B's items
a background thread with no tenant context sees no tenant data

If your isolation tests only cover the first line, they would not have caught this.

A checklist for your own code

Search for findById, getReferenceById, deleteById and any direct EntityManager.find or getReference on tenant entities.
Decide where the guarantee lives: a repository base class, a service check, or both.
Make "no tenant" mean "no data".
Write the by-id tests, not only the list tests.

Talk to me

This is the first post in a series about building Arab Enterprise Kit, an Arabic-first, multi-tenant SaaS foundation in Java 25, Spring Boot 4 and Angular 21. There's a free Lite edition on GitHub, and the full kit is on Gumroad. I build SaaS products and take freelance full-stack and backend projects: mahmoud-farouk-portfolio.vercel.app.

How does your multi-tenant app handle lookups by id?

Four details I check in any SaaS starter kit, and how mine handles them (Spring Boot 4 + Angular 21)

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

A starter kit's feature list tells you very little. Everyone has "auth, billing, multi-tenancy". What tells you whether a kit is safe to build a business on is a handful of small details: how it stores secrets, what happens when audit logging fails, how it trusts a payment webhook.

I maintain a SaaS starter kit called the Arab Enterprise Kit: Spring Boot 4 on Java 25, Angular 21 with PrimeNG, PostgreSQL, Docker, multi-tenancy with a Hibernate filter, Stripe billing, TOTP two-factor auth, Google OAuth2 and a three-language UI (English, Arabic right-to-left, French). Instead of touring the features, here are four details I would look at in any kit, with the real code behind each.

1. API keys are shown once and stored as hashes

If an API key table leaks, every key in it is compromised, unless you stored only hashes. The kit generates a key from 32 random bytes, stores a SHA-256 hash and a short prefix for display, and returns the raw key exactly once:

byte[] raw = new byte[32];
new SecureRandom().nextBytes(raw);
String rawKey = "ak_" + Base64.getUrlEncoder().withoutPadding().encodeToString(raw);

key.setKeyHash(sha256(rawKey));
key.setKeyPrefix(rawKey.substring(0, Math.min(10, rawKey.length())));
key.setIsActive(true);
key.setExpiresAt(req.resolvedExpiresAt());

ApiKey saved = repository.save(key);
// Return the raw key only once
return ApiKeyResponse.fromWithRaw(saved, rawKey);

Authentication hashes the presented key and looks the hash up, then checks that the key is active and not expired:

return repository.findByKeyHash(sha256(rawKey))
        .filter(ApiKey::getIsActive)
        .filter(k -> k.getExpiresAt() == null || k.getExpiresAt().isAfter(Instant.now()));

Revoking a key flips a flag, so a compromised key stops working immediately without deleting its history. API keys are high-entropy random values, which is why a fast hash is appropriate here; passwords are a different matter and use BCrypt.

2. Audit logging by annotation, and it must never break the request

Audit trails get forgotten when every service method has to remember to write one. In the kit a method opts in with an annotation:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Loggable {
    AuditAction action();
    String entityName();
    String description() default "";
}

An aspect runs after the method returns, reads the user from the security context, the client IP from the request, and the entity id from the returned entity, then saves the log entry:

@AfterReturning(pointcut = "@annotation(...Loggable)", returning = "result")
public void logActivity(JoinPoint joinPoint, Object result) {
    try {
        // username, ip, entityId from the result...
        auditLogService.saveAuditLog(loggable.action(), loggable.entityName(), entityId, username, ip, details);
        if (shouldSendNotification(action)) { /* only CREATE, UPDATE, DELETE */ }
    } catch (Exception e) {
        log.error("Audit Log Failed: {}", e.getMessage());
    }
}

Two decisions are worth copying. Reads do not send notifications, only create, update and delete do. And the whole body is wrapped in a try/catch, so a failure in the audit path is logged but cannot turn a successful business operation into an error.

That second choice is a trade-off, and you should make it consciously. If you need a guarantee that no action happens without an audit record, you want the opposite: fail the operation.

3. A payment webhook is untrusted input until it is verified

Stripe tells your server about payments by calling a public endpoint, so that endpoint cannot use your normal login. The kit excludes it from JWT authentication and relies on Stripe's signature instead:

@PostMapping("/webhook")
public ResponseEntity<String> handleWebhook(
        @RequestBody String payload,
        @RequestHeader("Stripe-Signature") String sigHeader) {

    Event event;
    try {
        event = Webhook.constructEvent(payload, sigHeader, webhookSecret);
    } catch (SignatureVerificationException e) {
        return ResponseEntity.badRequest().body("Invalid signature");
    }

    switch (event.getType()) {
        case "checkout.session.completed"    -> stripeWebhookService.handleCheckoutSessionCompleted(event);
        case "invoice.payment_succeeded"     -> stripeWebhookService.handleInvoicePaymentSucceeded(event);
        case "invoice.payment_failed"        -> stripeWebhookService.handleInvoicePaymentFailed(event);
        case "customer.subscription.deleted" -> stripeWebhookService.handleSubscriptionDeleted(event);
        case "customer.subscription.updated" -> stripeWebhookService.handleSubscriptionUpdated(event);
        default -> log.debug("Unhandled Stripe event type: {}", event.getType());
    }
    return ResponseEntity.ok("Received");
}

The raw body is passed to Webhook.constructEvent exactly as received, because re-serialising it would break the signature. Anything that fails verification gets a 400 and is never parsed into an event. The secret defaults to a placeholder value, so an unconfigured install rejects every call instead of accepting them.

4. A rate limiter that is honest about what it is

Login endpoints attract brute force. The kit ships a deliberately small limiter for /api/auth/**: 20 requests per IP per 60-second window, then HTTP 429.

RequestCount bucket = ipBuckets.compute(ip, (key, existing) -> {
    if (existing == null || now.isAfter(existing.windowStart().plusSeconds(WINDOW_SECONDS))) {
        return new RequestCount(new AtomicInteger(1), now);
    }
    existing.count().incrementAndGet();
    return existing;
});

Its own comment is the part I like: it says it is an in-memory, zero-dependency implementation, and that for production behind multiple instances you should replace it with Redis-based limiting. Per-account lockout is a separate layer: after 5 failed attempts the account is locked for 15 minutes.

A starter kit does not have to be perfect. It has to tell you where its limits are, so you can decide what to harden before real traffic arrives.

What I would tell my past self

Store only hashes of secrets you can show once.
Make cross-cutting concerns (audit, notifications) annotations, and decide deliberately whether their failure may break the request.
Verify webhook signatures against the raw body, and fail closed when the secret is not configured.
Document the limits of every "simple" component in the component itself.

Talk to me

The kit is also on Gumroad. I build SaaS products and take freelance full-stack and backend projects: mahmoud-farouk-portfolio.vercel.app.

What is the first thing you check when you evaluate a starter kit?

A Next.js 16 portfolio you edit in one file, with accessibility and video behaviour under test

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

A developer portfolio is a small project that tends to rot. The copy lives in ten components, the video autoplays on a phone with data saver on, the contact form validates in two places that slowly disagree, and nobody has run an accessibility check since launch.

I built a portfolio template (Next.js 16 App Router, React 19, Tailwind CSS v4, TypeScript) to avoid exactly that. This post is about the five design decisions that made it easy to keep correct, with the real code behind each.

1. All content in one typed file

Every word, link, project and SEO value lives in lib/content.ts. Components import from it and contain no copy. To personalise the site you edit that one file.

The point is not only convenience. A single typed source of truth can be tested. The unit tests check things a reviewer would otherwise check by eye:

there are exactly three services, and each one is selectable in the contact form;
the navigation links match the section ids the page uses;
every image path in the content points at a file that really exists in public/.

const publicFile = (p: string) => path.join(process.cwd(), "public", p);

// ...inside a test
expect(existsSync(publicFile(file)), file).toBe(true);

A broken image path fails a unit test instead of showing a broken image in production.

2. A demo video that costs nothing until you need it

Demo videos are heavy, and autoplaying them is rude. The ScrollVideo component is a small state machine documented in its own comment:

Before scroll: poster only, no source, nothing downloaded.
Within 200px of the viewport: the sources are attached.
At least 55% visible: plays muted and looped. Below that: pauses.

It uses two IntersectionObservers, one with a rootMargin to attach sources early and one with thresholds to start and stop playback:

useEffect(() => {
  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
  const connection = (navigator as Navigator & { connection?: { saveData?: boolean } }).connection;
  autoplayAllowed.current = !reducedMotion && !connection?.saveData;

  const nearViewport = new IntersectionObserver(
    (entries) => { if (entries.some((e) => e.isIntersecting)) { setAttached(true); nearViewport.disconnect(); } },
    { rootMargin: "200px 0px" },
  );
  // a second observer with threshold [0, 0.55, 1] starts and pauses playback
}, [play]);

Three details I care about:

People who asked for less motion get less motion. With prefers-reduced-motion or data saver on, nothing autoplays. The poster stays and an explicit play button is available.
There is always a visible pause button (WCAG 2.2.2), with the project name in screen-reader-only text, and a manual pause is remembered so scrolling does not restart it.
The state is observable. The wrapper exposes data-state="idle | playing | paused", which makes the behaviour testable instead of a matter of faith.

3. One validation function for the browser and the server

The contact form calls validateContact in the browser, and the API route calls the same function again on the server. There is no second set of rules to drift out of sync.

/** Validates the contact payload. `company` is a honeypot: humans never see it. */
export function validateContact(input: unknown): ContactResult {
  // ...
  if (text(raw.company) !== "") return { ok: false, errors: {}, spam: true };
  // name, email pattern, service in the allowed list, message length 40..4000
}

The route treats the honeypot differently from a normal error:

// Pretend success to bots so they do not learn the honeypot exists.
if (result.spam) return NextResponse.json({ ok: true });

Delivery goes through Resend when three environment variables are set. When they are not, the route answers 503 with a clear message and the UI falls back to a direct email link, so a half-configured deployment degrades into something usable instead of a dead form.

4. Analytics events defined in one place

Custom events are a classic source of drift: cta_click in one file, ctaClick in another. Here every event is a member of one union type:

export type AnalyticsEvent =
  | { name: "cta_click"; props: { id: "start_project" | "resume"; location: string } }
  | { name: "service_interest"; props: { service: string } }
  | { name: "video_play"; props: { project: string; trigger: "scroll" | "button" } }
  | { name: "form_submit"; props: { result: "success" | "error" | "invalid" } }
  | { name: "outbound_click"; props: { target: OutboundTarget } };

export function trackEvent(event: AnalyticsEvent) {
  try { track(event.name, event.props); } catch { /* Analytics must never break the page. */ }
}

TypeScript now rejects a misspelled event name or a missing property, and the try/catch means an analytics failure can never break a page.

5. Accessibility is a test, not a hope

The end-to-end suite runs axe against the page, including WCAG 2.2 AA rules, after scrolling through the whole page so lazy content is present, and again with the mobile menu open. Serious and critical violations fail the build:

const results = await new AxeBuilder({ page })
  .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
  .analyze();
expect(blocking(results.violations).map((v) => `${v.id}: ...`)).toEqual([]);

Two further checks are plain DOM assertions: every image has an alt attribute and every form control has a label. A separate reduced-motion test group checks the video behaviour from section 2, and CI runs lint, typecheck, unit tests and the browser suite on every pull request and on pushes to main.

Automated tools find only part of the accessibility problems, so this is a floor and not a certificate. But a floor that runs on every commit beats a manual audit that happened once.

What I would tell my past self

Put the content in one typed file and write tests against it.
Treat video as a progressive enhancement with a visible off switch.
Share validation between client and server, and give spam a different path.
Define analytics events as a union type.
Run axe in CI from day one.

Talk to me

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

What would you add to the checklist for a portfolio that has to stay correct for years?

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.

Update, October 2026: one case this filter does not cover. Hibernate filters do not apply to findById, so 1.1 adds an explicit tenant check on every lookup by id. The write-up of how we found and fixed it goes up on October 28.

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

Live demo: https://inventory-shop-management-production.up.railway.app (sign in as shop.admin / demo123; card payments are simulated).

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! 👇