Coder Legion - Recent posts tagged framework

Building a static blog with Sitelo, one function per page

Fri, 30 Oct 2026 14:35:56 +0000

In my last post on DEV I explained why I built Sitelo: most websites are documents, and documents shouldn't need a JavaScript application to reach the browser. That post was the argument. This one is the practice.

We'll build a small blog from an empty folder: a home page, post pages generated from JSON files, and a comments section that stays fresh on an otherwise static page. Along the way I'll point out what Sitelo is doing at each step, and what it deliberately doesn't do.

The whole framework fits in one sentence, and it's worth keeping in mind as we go:

Files are routes. Functions return HTML. Browser code is explicit.

Everything below is that sentence, applied.

Step 1: one page is one function

Start with an empty folder and install Sitelo. It needs Node 20.19+ or 22.12+, and Vite is bundled, so there's nothing else to install or configure.

npm init -y
npm pkg set type=module
npm install -D sitelo

Add two scripts to package.json:

"scripts": {
  "dev": "sitelo",
  "build": "sitelo build"
}

Now the first page. Any file in src/ ending in .ht.js is a page, and its default export returns HTML:

// src/index.ht.js
export default () => `
  <html lang="en">
    <head>
      <title>My blog</title>
      <link rel="stylesheet" href="/styles.css">
    </head>
    <body>
      <h1>Hello world</h1>
    </body>
  </html>
`

Create a src/styles.css with a few rules, then run npm run build and you get:

dist/
  index.html   ← your HTML, with <!DOCTYPE html> added
  styles.css   ← bundled and minified, because the page linked it
  404.html     ← a default one, until you write src/404.ht.js

The function ran once, at build time, in Node. The browser gets the string it returned and nothing else: no runtime, no hydration, no bundle of page code. If you want JavaScript in the browser, you add a <script> tag, the same as you would in a hand-written HTML file.

Template literals aren't the only option. A page can also return JSX from a .ht.jsx or .ht.tsx file, which is rendered to a static string with react-dom/server. Or you can use my companion library javascript-to-html, where every element is a function. I'll stick with template literals here because they need no explanation.

Step 2: a layout is just another function

A blog needs the same <head> and header on every page. There's no layout system to learn for this, because a layout is a function that takes some HTML and wraps it:

// src/lib/layout.js
export const layout = ({ title, children }) => `
  <html lang="en">
    <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <title>${title} · My blog</title>
      <link rel="stylesheet" href="/styles.css">
    </head>
    <body>
      <header><a href="/">My blog</a> · <a href="/blog">Posts</a></header>
      <main>${children}</main>
    </body>
  </html>
`

// src/index.ht.js
import { layout } from './lib/layout.js'

export default () => layout({
  title: 'Home',
  children: '<h1>Hello world</h1><p>Welcome to my blog.</p>',
})

layout.js doesn't end in .ht.js, so it isn't a page. It also never ends up in dist/. Sitelo only emits a JavaScript or TypeScript file when your HTML references it with a <script src>; a module you only import from page code stays on the build side. That rule matters more later, when the helpers you import hold API keys or database code. They can't leak into the browser by accident.

The same rule works in the other direction. Write <script type="module" src="/main.ts"></script> and Sitelo bundles src/main.ts with esbuild, emits main.js, and rewrites the tag to match. Browser code exists only where you asked for it.

Step 3: posts from JSON files

Now for the posts. I'll keep them in the repo as JSON, one file per post, outside src/ because they're content rather than code:

// data/posts/hello-world.json
{
  "title": "Hello, world",
  "date": "2026-10-01",
  "body": "<p>My first post.</p>"
}

The post page lives at src/blog/[slug].ht.js. The square brackets make it a dynamic route, and it exports two more functions next to the page itself:

generateStaticParams() lists the pages to build, one per post.
data() loads what one page needs. Whatever it returns arrives in the page function as data.

// src/blog/[slug].ht.js
import { readJsonCollection } from 'sitelo/data'
import { layout } from '../lib/layout.js'

const posts = () => readJsonCollection('data/posts', { sort: '-date' })

export async function generateStaticParams() {
  return (await posts()).map((post) => ({ slug: post.slug }))
}

export async function data({ params }) {
  return (await posts()).find((post) => post.slug === params.slug)
}

export default ({ data: post }) => layout({
  title: post.title,
  children: `
    <article>
      <h1>${post.title}</h1>
      <time datetime="${post.date}">${post.date}</time>
      ${post.body}
    </article>
  `,
})

readJsonCollection reads every .json file in the folder and takes each slug from its file name. It parses each file once per build, however many pages ask for it, and two posts with the same slug fail the build instead of one silently overwriting the other.

The index page is the same idea without the brackets:

// src/blog/index.ht.js
import { readJsonCollection } from 'sitelo/data'
import { layout } from '../lib/layout.js'

export const data = () => readJsonCollection('data/posts', { sort: '-date' })

export default ({ data: posts }) => layout({
  title: 'Posts',
  children: `
    <h1>Posts</h1>
    <ul>
      ${posts.map((post) => `<li><a href="/blog/${post.slug}">${post.title}</a></li>`).join('')}
    </ul>
  `,
})

A build now writes dist/blog/index.html and one dist/blog/<slug>/index.html per post. In the dev server (npm run dev) pages render on request through Vite, so editing a JSON file reloads the browser, and an error points at the exact line of your page in the terminal.

If your posts live in a CMS instead, data() can fetch them. Sitelo exports fetchWithCache, a drop-in for fetch that caches responses during the build. A 500-page site then doesn't make 500 identical requests to your API.

Step 4: fresh comments on a static page

Comments are the classic reason static blogs reach for a client-side widget or give up and go server-rendered. Sitelo's answer is a server island: the page stays static, and one marked region is rendered on the server when someone views it.

An island is a module in src/islands/ whose default export returns HTML. Islands are fragments rather than pages, so the file is plain .js, not .ht.js:

// src/islands/comments.js
import { getComments } from '../lib/comments.js'

const escape = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)

export default async function comments({ props }) {
  const list = await getComments(props.postId)
  if (!list.length) return '<p>No comments yet.</p>'
  return `<ul>${list.map((c) => `<li><b>${escape(c.author)}</b> ${escape(c.text)}</li>`).join('')}</ul>`
}

getComments is whatever your comment store is: a database query, a call to a hosted service. Comments are user input, hence the escape.

Place the island in the post page with island(). The third argument is the fallback HTML that ships in the static build, and when: 'visible' waits until the reader scrolls near the comments before making the request:

// src/blog/[slug].ht.js (the page function)
import { island } from 'sitelo/islands'

export default ({ params, data: post }) => layout({
  title: post.title,
  children: `
    <article>…</article>
    ${island('comments', { postId: params.slug }, '<p>Loading comments…</p>', { when: 'visible' })}
    <script type="module" src="/islands.js"></script>
  `,
})

The script tag loads a two-line client that finds the placeholders and fetches them:

// src/islands.js
import { mountIslands } from 'sitelo/islands/client'

mountIslands()

In npm run dev and sitelo preview this already works: Sitelo serves islands at /_sitelo/islands/<name>. In production your static host serves the pages, and you mount a small handler wherever you can run server code. createIslandsHandler from sitelo/islands/server takes a Web Request and returns a Response, so it fits a serverless or edge function. The repo has Netlify and Vercel versions.

A few details I cared about getting right:

Props are untrusted. They're embedded in the page and sent back on the request, so anyone can edit them. Set SITELO_ISLANDS_SECRET and the build signs every placeholder with HMAC-SHA256, and the handler rejects edited props with a 403.
Islands are server-only. The rule from Step 2 applies: nothing references comments.js from HTML, so it never reaches dist/, and neither does your database code.
Failure is graceful. If the island endpoint is down or slow (10 seconds by default), the fallback HTML stays where it was. The page still works.

Step 5: let the build check your work

The blog works. The last step is a config file, and it's where Sitelo earns its keep on a real site:

// sitelo.config.js
export default {
  site: 'https://myblog.example',
  rss: {
    site: 'https://myblog.example',
    title: 'My blog',
    description: 'Latest posts',
    routePrefix: '/blog',
  },
  images: true,
  linkCheck: 'error',
  lighthouse: {
    thresholds: { accessibility: 100, 'best-practices': 95, seo: 100 },
  },
}

Here's what each line buys you:

site generates dist/sitemap.xml from every route, including the ones generateStaticParams produced.
rss writes dist/rss.xml with an item for every page under /blog.
images turns each <img> into a resized, WebP srcset with width and height set, so a 3000px hero photo no longer ships to phones. It needs sharp installed, and it works in the dev server too, so what you see is what you ship.
linkCheck: 'error' resolves every internal <a href> against the files the build actually wrote, the way a static host would. A typo like /blgo fails the build with the page it's on.
lighthouse gives sitelo lighthouse thresholds to enforce. Any score under its threshold exits non-zero, so it can gate CI. Like sharp, Lighthouse is an optional install.

I left performance out of the thresholds on purpose. It depends on the machine running the audit, and a page that scores 100 on a laptop can score around 60 on a shared CI runner. Accessibility, best practices and SEO are properties of the HTML itself, so they score the same anywhere.

One check needs no config. If a page links a script or stylesheet that doesn't exist in src/ or public/, the build fails and lists the paths it tried. That's why Step 1 asked you to create styles.css first.

Every build ends with a report of what you're shipping: file counts and sizes per type, the largest files, and how long each phase took. On a static site, "how much JavaScript am I sending?" should be a number you see every time, not something you go looking for.

Building it with a coding agent

I designed Sitelo with coding agents in mind, and the small surface area matters even more for them than for people. Ask an agent to add a page to an unfamiliar framework and it reaches for whatever it has seen most: React components, Next.js conventions, Astro frontmatter. With Sitelo there's less to get wrong, because there's less of everything. A page is a function, a route is a file, and browser code is a <script> tag.

To close the remaining gap, Sitelo ships two Agent Skills: one for the framework (pages, routing, data, islands, deployment) and one for its component library. Install them into your project and Claude Code, Cursor, Codex and other agents load them when a task needs them:

npx skills add Paul-Browne/sitelo

The skills also ship inside the npm package, matching the version you installed. Sitelo's test suite checks every API the skills mention against the package's real exports, so a renamed or removed API fails the tests before it reaches a release. For agents that prefer to read a URL, the docs publish sitelo.dev/llms.txt, plus a single-file llms-full.txt with every guide in Markdown.

The build checks from Step 5 help here too. An agent that invents a stylesheet path or links to a page that doesn't exist gets a failed build naming the problem, not a site that quietly ships broken.

What we built, and when not to use it

In five steps we went from an empty folder to a blog with:

a home page, a post index and one page per JSON file
comments rendered on the server at view time, on otherwise static pages
a sitemap, an RSS feed and responsive images
a build that fails on broken links and missing assets, plus a Lighthouse gate for accessibility and SEO

The browser receives HTML, one stylesheet and a 1.7 kB island loader. That's all, because those are the only things we asked for.

Sitelo isn't the right tool for everything. JSX pages render to static HTML only, so onClick handlers and hooks do nothing in the browser. If you're building an application, with client-side state and routing, use an application framework. Astro, Next.js and Eleventy are all excellent at what they do. Sitelo is for docs, blogs, marketing sites and content sites, where "view source" should show what you wrote.

If that sounds like your next project:

Docs: sitelo.dev/docs
Code (MIT licensed): github.com/Paul-Browne/sitelo
Package: npmjs.com/package/sitelo

The repo includes a complete blog example that goes further than this post, with Markdown posts. And if you find something that makes Sitelo more complicated than it needs to be, please open an issue. Keeping it boring is the whole point.

Framer vs Webflow for Beginners: Which No-Code Builder is Best?

Tue, 06 Oct 2026 05:40:50 +0000

Choosing a website builder is no longer simply a question of finding a platform that lets you publish a page without writing code. Modern no-code builders now combine visual design, content management, hosting, SEO controls, analytics, forms, localization, collaboration, and increasingly, AI-powered tools.

Two platforms that attract a large share of attention in this category are Framer and Webflow. Both allow users to build websites visually, but they approach the process differently. Framer is strongly oriented toward visual design and rapid publishing, while Webflow provides a more extensive system for structured website development, content management, collaboration, and larger projects.

For a beginner deciding between the two, the important question is not which platform has more features. The better question is which platform makes the type of website you want to build easier to create and manage.

Framer and Webflow Take Different Approaches
Framer began with a strong connection to interface and interaction design, and its current website builder continues to emphasize visual creation. Users can build responsive pages on a visual canvas, create CMS-driven pages, manage SEO settings, add forms, use analytics, and publish through Framer's hosting infrastructure.

Webflow also uses a visual development environment, but its system is designed around greater control over website structure, content, interactions, hosting, collaboration, and business requirements. Its CMS is positioned for content-rich websites, while its broader platform includes hosting, localization, SEO, analytics, optimization, and other tools.

That distinction matters for beginners.

If the main goal is to create a polished portfolio, landing page, personal website, agency site, or other design-led project quickly, Framer can be an attractive starting point.

If the goal is to learn a more extensive visual website development system that can accommodate sophisticated CMS structures, larger content operations, localization, and team workflows, Webflow deserves serious consideration.

Which Platform Is Easier for Beginners?
Framer has a strong advantage when simplicity and visual design are the immediate priorities.

Its workflow keeps much of the website creation process inside a visual canvas. Pages can be designed responsively, CMS pages can be generated from collections, and users can manage website content without moving into a completely separate publishing system. Framer's current documentation also describes support for web pages, CMS pages, and design pages.

This makes Framer particularly attractive to someone who thinks visually and wants to see the result while building.

Webflow is also a visual platform, but beginners may encounter more concepts before becoming comfortable. Website structure, classes, responsive behavior, CMS collections, interactions, hosting settings, SEO controls, and other platform functions can require more time to understand.

That is not necessarily a weakness. Greater control can be valuable once a user moves beyond basic websites. The tradeoff is that Webflow can require a larger learning investment.

For someone building their first website, Framer is generally the easier place to begin.

For someone willing to spend more time learning the platform in exchange for deeper control, Webflow can provide a stronger long-term development environment.

Design and Creative Control
This is one of the clearest areas where the platforms differ in practical use.

Framer is built around a design-first workflow. Its visual canvas makes it possible to create responsive pages, navigation, effects, and different breakpoints directly within the design environment.

That approach works especially well for designers, freelancers, creators, startups, portfolio owners, and anyone who wants the website itself to have a strong visual identity.

Webflow also provides extensive visual design control. However, its interface is closely connected to concepts associated with professional web development, including structured styling and reusable systems.

For a beginner, Framer can therefore feel more direct.

For a user who wants to understand how a complex website is constructed and controlled at a deeper level, Webflow may offer more room to grow.

CMS and Content Management
The choice becomes more complicated when content management is a major requirement.

Framer has a CMS that supports collections and dynamic pages. Its official documentation describes CMS pages generated from collection content, with templates that can be used for blog posts, news articles, product pages, case studies, and similar content.

Framer also provides visual content editing and automatic SEO options for CMS pages. Its CMS documentation highlights dynamic titles and descriptions, schema, Open Graph tags, drafts, publishing, and localization capabilities.

Webflow has a more established reputation for structured content management. Its CMS is designed for content-rich websites and allows teams to manage structured content while controlling how that content is presented visually.

For a simple blog or small content site, either platform can work.

For a website expected to contain a substantial amount of structured content, multiple content types, and more complicated publishing requirements, Webflow's broader CMS environment may be more suitable.

SEO: Framer vs Webflow
Both platforms provide built-in SEO controls, meaning users do not have to rely on a separate WordPress-style SEO plugin simply to manage fundamental search settings.

Framer states that its websites are optimized for SEO by default. Its SEO tools include sitemap and robots.txt generation, custom page titles and descriptions, indexing controls, redirects, and structured data options.

Framer also provides built-in analytics and allows integration with Google Analytics.

Webflow provides comparable fundamental SEO controls, including page titles, meta descriptions, URLs, Open Graph settings, and CMS-based SEO fields.

Webflow goes further when localization becomes important. Its Localize system supports localized URLs, metadata, sitemaps, hreflang implementation, and visitor routing.

For a beginner creating a single-language website, neither platform has an obvious fundamental SEO disadvantage.

For larger multilingual websites, Webflow offers a more extensive localization system.

Forms and Analytics
A modern business website needs more than attractive pages. It also needs a way to collect leads and measure visitor activity.

Framer includes native forms and built-in analytics. Its documentation covers contact forms for leads, bookings, signups, and inquiries, as well as spam protection and analytics.

Framer also allows users to assign tracking IDs to links and forms and view those events through Analytics Overview. The platform supports funnels and A/B testing as part of its analytics and testing capabilities.

Webflow provides forms and a broader set of marketing and optimization tools within its platform. Its current platform includes Analyze and Optimize products, while its paid Site plans include different levels of functionality depending on the selected plan.

For a small website, Framer's built-in tools may be enough.

For a company that expects website analytics, optimization, localization, collaboration, and other marketing functions to become increasingly important, Webflow's broader platform can be more compelling.

Pricing Matters for Beginners
Pricing can change, so it is important to compare current plans rather than rely on old articles.

As of October 2026, Framer lists a free plan, Basic at $10 per month, and Pro at $30 per month, with annual billing displayed on its pricing page. The Basic plan includes a custom domain, two CMS collections, 50 GB of bandwidth, and built-in SEO. The Pro plan increases the CMS collections limit to 10 and includes features such as redirects, staging, and branching with previews.

Webflow currently offers a free Starter plan. Its Basic Site plan is listed at $15 per month when billed yearly, while its Premium plan is listed at $25 per month when billed yearly. The Premium plan includes Webflow CMS, while the Basic plan is intended for simpler websites without CMS requirements.

Webflow also separates Site plans from Workspace plans, which means users need to understand the distinction between hosting a website and managing projects, staging environments, collaboration, and related Workspace functions.

For a beginner comparing only the entry-level paid plans, Framer currently has the lower listed starting price.

However, price alone should not determine the decision. A cheaper plan that lacks a feature you later require can become more expensive if it forces a move to another tier or platform.

Localization and International Websites
International websites introduce another important difference.

Framer supports localization and provides tools for translating and adapting sites. Its current platform documentation also describes localization as part of its broader website-building system.

Webflow has invested heavily in localization. Webflow Localize supports multiple locales, localized content and styles, localized page settings, SEO metadata, URLs, and sitemap functionality.

Webflow's localization system can therefore become particularly relevant to companies operating across different countries or language markets.

A beginner building a personal portfolio probably does not need to prioritize this feature.

A business planning a multilingual website should examine it carefully before choosing a platform.

Collaboration and Growing Teams
The platform choice can change when a solo website becomes a team project.

Framer introduced a new billing system in 2026 that includes different editor types, including Content Editors for people who manage CMS content without requiring full editing access.

Webflow has a broader Workspace system with collaboration features, staging environments, seats, permissions, publishing workflows, and team-oriented plans. Its current Team plan is designed for growing organizations and includes features such as Localize, publishing workflows, page branching, single-page publishing, and additional governance capabilities.

For a solo creator, these differences may not matter much.

For agencies, marketing departments, and organizations with multiple people involved in website production, Webflow's collaboration architecture deserves close attention.

Which One Is Better for a Portfolio?
For a personal portfolio, designer portfolio, freelancer website, or creative landing page, Framer is a strong choice.

The visual workflow allows beginners to concentrate heavily on the appearance and presentation of the website. Its hosting, CMS, SEO, analytics, and publishing functions are integrated into the same platform.

Webflow can also produce excellent portfolios, but it may introduce more concepts than a beginner needs for a relatively small project.

If the objective is to launch a visually impressive portfolio without spending weeks learning a complex platform, Framer is the more straightforward recommendation.

Which One Is Better for a Business Website?
The answer depends on the business.

A small company that needs a professional homepage, services page, contact page, and a few supporting pages can use either platform successfully.

Webflow becomes more attractive when the website requires a structured CMS, multiple content types, localization, advanced collaboration, extensive marketing operations, or a larger team.

Framer remains a strong choice when visual design, rapid publishing, and ease of use are the highest priorities.

Which One Is Better for a Blog?
Both platforms can support blogs through their CMS systems.

Framer's CMS can generate dynamic pages from collections, making it possible to create blog posts and other recurring content from reusable templates.

Webflow's CMS is also designed for structured content and content-rich websites.

For a small independent blog, either platform can work.

For a publication that expects complicated content structures, larger editorial operations, multiple content types, or more advanced team workflows, Webflow is likely the stronger candidate.

Framer vs Webflow: The Beginner's Verdict
There is no universal winner because the platforms prioritize different aspects of website building.

Framer is the better choice for beginners who want:

A highly visual website-building workflow
Fast project creation
Design-focused websites
Portfolio websites
Landing pages
Small business websites
Straightforward CMS projects
Built-in SEO and analytics tools
A lower starting price for paid plans
Webflow is the better choice for beginners who want:

A deeper website development environment
More extensive CMS capabilities
Content-heavy websites
Larger business websites
Advanced collaboration
Multilingual and international websites
More extensive marketing and optimization capabilities
A platform that can accommodate increasingly complex projects
The important point is that Webflow is not automatically better because it has more features, and Framer is not automatically better because it is easier to approach.

For a first website, Framer is probably the better starting point for most beginners who prioritize simplicity and visual design.

For someone who intends to build more complex websites and is prepared to spend more time learning the platform, Webflow is the stronger long-term candidate.

The best choice is therefore determined by the website being built, not by which platform has the longer feature list.

Before committing to either service, beginners should also check the current pricing and feature limits. Both companies continue to update their products and plans, and Webflow made significant pricing and plan changes during 2026.

If the goal is to get a polished website online quickly, start with Framer.

If the goal is to develop deeper skills for building structured, content-rich, collaborative websites, start with Webflow.

For most first-time users, that distinction is more useful than simply asking which platform is "best."

Stop Slow Laravel: Your Next Architectural Leap Is Here!

Wed, 01 Jul 2026 06:34:24 +0000

Stop Slow Laravel: Your Next Architectural Leap Is Here!

Introduction

It’s 2026, and the landscape of web development has evolved dramatically. If your Laravel applications are still relying on traditional PHP-FPM for request handling, you might be leaving significant performance on the table. The conversation around application speed has moved beyond mere query optimization; it’s an architectural paradigm shift. Enter Laravel Octane, a powerful package that integrates your Laravel application with high-performance application servers like RoadRunner or Swoole. This isn’t just about making PHP “faster”; it’s about fundamentally transforming how your application processes requests, ushering in an era of unprecedented throughput, reduced latency, and blazing-fast API responses. Octane transitions your application from a stateless, “boot-on-every-request” model to a persistent, long-running process, eliminating the costly framework bootstrap for each incoming call.

Code Layout and Architectural Walkthrough

Embracing Laravel Octane demands a shift in mindset, particularly regarding application state. Let’s walk through the essential steps and considerations to integrate Octane into your project.

1. Installation and Setup: Getting started with Octane is straightforward. You first install the package via Composer:

composer require laravel/octane

Next, you’ll install Octane into your application, choosing your preferred server driver (RoadRunner or Swoole). RoadRunner is often simpler to get started with due to fewer external dependencies for many environments.

php artisan octane:install

This command publishes the config/octane.php configuration file, which allows you to fine-tune settings like the number of worker processes, maximum requests per worker before restarting, and more.

2. The Persistent Server Model: Unlike FPM, which reboots your entire application for every request, Octane leverages a persistent application server. When you run php artisan octane:start, a dedicated server process (RoadRunner or Swoole) is launched. This server loads your Laravel application once, keeping it in memory. Subsequent requests are then routed to this already-booted application instance. This fundamentally eliminates the overhead of bootstrapping the framework on every single request, leading to dramatic performance improvements.

3. Embracing the Stateful Mindset: This is the most critical aspect of adopting Octane. Because your application remains loaded in memory between requests, global state can persist, leading to unexpected behavior if not managed carefully. Key areas to monitor:

Static Properties & Global Variables: Any data stored in static properties or global variables will persist across requests. This can lead to data leaks or incorrect behavior if not reset.
Service Container Bindings: While Octane intelligently resets many core framework services, custom singleton bindings in your service container might retain state.
Opened Resources: Database connections, file handles, or network sockets that are not properly closed might accumulate or become stale.

Octane’s Mitigation Strategies: Octane provides powerful hooks to manage state:

Octane::onRequest: You can register callbacks to be executed at the beginning of each request. This is ideal for manually resetting any custom global state or re-binding services if necessary.

use Laravel\Octane\Facades\Octane;

Octane::onRequest(function ($request, $app) {
    // Clear any custom static caches
    MyCustomService::$cache = [];
    // Rebind specific service if it holds request-specific state
    $app->bind(SomeService::class, fn () => new SomeService());
});

Octane::onWorkerStopping: This hook can be used for cleanup tasks when a worker process is gracefully shutting down.
Automatic Resetting: Octane intelligently resets many core Laravel components, such as request input, session data, authentication state, and even clears resolved instances from the service container (unless explicitly configured otherwise).

For most well-architected Laravel applications that rely heavily on dependency injection and avoid excessive global state, the transition is smoother than anticipated. Focus on ensuring your services and controllers are stateless or properly reset if they must hold state.

Conclusion

Adopting Laravel Octane is no longer an edge-case optimization for the ultra-high-traffic elite; it’s becoming the baseline for modern, efficient Laravel applications. The architectural shift to a persistent application server, powered by RoadRunner or Swoole, fundamentally redefines performance. By eliminating per-request framework bootstrapping, Octane delivers 10x throughput, significantly reduced latency, and an incredibly responsive user experience. While it demands a careful consideration of application state, the performance gains and competitive advantage it provides are immense. Stop leaving raw performance on the table. Embrace Octane today and position your Laravel applications for peak efficiency and future success.

Best Python AI Frameworks in 2026

Thu, 11 Jun 2026 12:57:42 +0000

A comparison of seven major Python AI frameworks for 2026: TensorFlow, PyTorch, Keras, scikit-learn, XGBoost, LangChain, and Hugging Face. Each framework is evaluated by strengths, weaknesses, and ideal use cases. Deep learning frameworks (TensorFlow, PyTorch, Keras) suit neural network tasks; classical ML frameworks (scikit-learn, XGBoost) excel on tabular data; LLM/agent frameworks (LangChain, Hugging Face) power language model applications. A decision table helps match framework choice to data type, abstraction level, deployment target, and project objective. Many teams combine multiple frameworks in production.

We finally broke the 500ms latency barrier for AI phone calls.

Mon, 04 May 2026 08:35:00 +0000

Hey CoderLegion! One of the biggest complaints with AI calling is the lag.
We wanted to share a raw snippet of our open-source framework, Siphon, in action.
By using WebRTC under the hood instead of WebSockets, we've gotten the voice-to-voice response time to feel incredibly human.
Would love for you guys to test the repo and let us know how it feels on your local machines!

Siphon | Step-by-Step YT Tutorial
Siphon Website
GitHub code

The "Context Gap" in Voice AI: Why Chatbots Fail at Scheduling

Sun, 01 Feb 2026 13:15:33 +0000

Voice AI demos are everywhere.

You call a number, an enthusiastic robot voice greets you, and you have a pleasant five-minute chat about the weather or the meaning of life. But the moment you ask:

“Can you squeeze me in for a cleaning next Tuesday at 2 PM?”

…the magic usually breaks.

Why?

Because talking is easy. Context is hard.

Most voice agents are great conversationalists, but they operate in a vacuum. They have no real understanding of time, availability, or the systems businesses actually run on.

To build a truly useful AI receptionist, you don’t just need a good LLM—you need real integrations.

That’s why we’re introducing Native Google Calendar Integration in SIPHON.

The Context Gap in Voice Agents

Traditionally, building a scheduling voice agent looks something like this:

Transcription – Convert speech to text
Extraction – Parse phrases like “next Tuesday at 2 PM”
API Glue – Authenticate with Google, fetch events, check conflicts
Response Logic – Manually construct confirmations and retries

This approach is fragile, slow to build, and painful to maintain.

SIPHON solves this by treating integrations as first-class citizens—just like your LLM, STT, or TTS provider.

Native Google Calendar Integration

With SIPHON, enabling Google Calendar support is a single line of configuration:

agent = Agent(
    # ... standard config ...
    google_calendar=True
)

That’s it.

No OAuth boilerplate.
No custom API clients.
No fragile glue code.

What This Enables

Once enabled, your SIPHON agent can:

Check real-time availability before offering time slots
Create, update, and cancel events directly on Google Calendar
Avoid double-booking and intelligently handle conflicts
Reschedule appointments in a natural conversation

All through voice.

A Real Example: 24/7 Dental Clinic Receptionist

To showcase this integration, we built a production-ready Dental Clinic Receptionist.

This is not a toy demo—it behaves like a real front-desk employee:

Inbound Call – A patient calls to book an appointment
Verification – The agent verifies whether the caller is a new or existing patient
Smart Scheduling – It checks the dentist’s actual Google Calendar
Booking – The agent books the slot and confirms it verbally
Follow-ups – Patients can call back to modify or cancel appointments

Explore the full example on GitHub

Why This Matters

For Voice AI to move from novelty to utility, it must do real work.

Scheduling is one of the highest-value automation targets for:

Clinics and hospitals
Salons and service businesses
Consultants and small teams

By abstracting away OAuth flows, API management, and tool orchestration, SIPHON lets developers build powerful scheduling agents in minutes instead of weeks.

Get Started

Ready to give your voice agent a calendar?

SIPHON is an open-source framework for building production-grade calling AI.
⭐ Star us on GitHub

SIPHON: The Telephony-First Framework for Calling AI

Wed, 28 Jan 2026 17:36:40 +0000

Building an AI that can chat via text is now a solved problem. Building an AI that can handle a real phone call in production is still a nightmare of fragmented infrastructure.

Developers typically face a "plumbing" crisis: they must manually stitch together SIP trunks, manage real-time media buffers, handle signal interruptions, and wire up multiple AI providers—all while trying to keep latency low enough for a human conversation.

SIPHON was built to end the plumbing. It is an open-source Python framework that provides a unified, telephony-first abstraction for building and operating Calling AI agents.

The Problem: The Telephony Gap

Traditional IVR systems and contact center platforms were never designed for the era of Large Language Models (LLMs). When developers try to build modern calling agents, they encounter three primary friction points:

Complexity: Each project requires re-implementing SIP trunk provisioning, room orchestration, and VAD (Voice Activity Detection) tuning.
Vendor Lock-in: Most "Voice AI" platforms tie you to a single stack, making it impossible to swap LLM or TTS providers as technology evolves.
Operation Hurdles: Features like call recording, metadata persistence, and transcription handling are often treated as afterthoughts rather than first-class features.

The Solution: A Unified Calling Abstraction

SIPHON sits between the telephony world and the AI world, providing a coherent framework for developers to build production-ready agents in ~30 lines of code.

How it Works: The SIPHON Architecture

Unlike generic voice frameworks, SIPHON is built on top of LiveKit, leveraging its real-time media and SIP layer to ensure high reliability.

The diagram illustrates how SIPHON orchestrates the entire call lifecycle:

PSTN/SIP Provider ↔ LiveKit SIP Domain (Real-time media)
LiveKit Rooms ↔ SIPHON Agent Worker (Orchestration)
SIPHON Worker ↔ AI Providers (OpenAI, Deepgram, Cartesia, etc.)

The framework is divided into two core modules:

siphon.telephony: Handles inbound Dispatch rules and outbound Call initiation, allowing you to bind phone numbers to agents programmatically.
siphon.agent: The runner that manages the LiveKit Agent worker, entrypoint orchestration, and the dynamic construction of AI components.

Key Pillars of SIPHON

1. Production-Ready at Scale

SIPHON is not a "toy" framework. It is designed for horizontal scalability; you can run your agent on one server or a thousand, and the architecture automatically balances the load.

2. Sub-500ms Latency

By utilizing WebRTC for real-time media interactions, SIPHON ensures voice interactions feel natural. It manages audio packet loss and interruptions to maintain a human-like flow.

3. Total Vendor Flexibility

Through its plugin architecture, SIPHON is agnostic to your AI stack. You can swap between OpenAI, Gemini, Deepgram, or ElevenLabs with minimal code changes.

4. Integrated Data Persistence

Recording, transcription, and metadata persistence are enabled via simple environment flags. Whether you need to save to S3, Postgres, or Redis, SIPHON handles the storage logic for you.

Getting Started

SIPHON is now open-source under the Apache 2.0 license.

Developers can install the framework and spin up a functioning agent worker in minutes:

pip install siphon-ai

Whether you are building an AI receptionist, an outbound notification system, or a contact-center triage bot, SIPHON provides the infrastructure to get you to production faster.

Stop building the plumbing. Start building the agent.

Read the Documentation | ⭐ Star us on GitHub

A BLACKDWARF Initiative.

Hello, World. Meet SIPHON.

Sun, 25 Jan 2026 11:27:39 +0000

Building an AI that chats is easy. Building an AI that calls is painfully hard.

If you have ever tried to build a production-ready voice agent, you know the struggle: fighting with SIP signaling, debugging audio buffers, and wrestling with 2-second latency.

We got tired of the plumbing. So we built SIPHON.

What is it?

SIPHON is an open-source Python framework for building Calling AI agents.

It is a "telephony-first" abstraction over LiveKit that handles the chaos of real-world phone networks for you. No more stitching together WebSockets or media servers. Just pure Python.

Why use it?

Production Ready:
Built for real phone calls, not just demos.
Few Lines of Code:
Spin up an agent that handles inbound/outbound calls in minutes.
Vendor Agnostic:
Swap LLMs (OpenAI, Gemini) and Voice providers (Deepgram, Cartesia) with a single config line.
Sub-500ms Latency:
Powered by WebRTC for conversations that feel human.
Zero-Config Horizontal Scaling:
Run your agent on multiple servers and it automatically load balances calls across them—no complex setup required.

Get Started

Install it:

pip install siphon-ai

Build your agent:

from siphon.agent import Agent
from siphon.plugins import openai, cartesia, deepgram

agent = Agent(
    agent_name="Receptionist",
    llm=openai.LLM(),
    tts=cartesia.TTS(),
    stt=deepgram.STT(),
)

if __name__ == "__main__":
    agent.dev()

The plumbing is done. Go build the agent.

⭐ Star us on GitHub | Read the Docs

Modern Frontend Frameworks Are Failing at Testing

Tue, 30 Dec 2025 12:12:28 +0000

A few weeks after releasing TWD, a tool designed to integrate testing directly into the development workflow. I started creating testing recipes for different frontend frameworks. While doing that, a few patterns became very clear.

What works

Frontend-focused applications (SPAs) are relatively easy to test using tools like TWD and traditional runners such as Vitest.
You can validate real user interactions, keep tests close to the UI, and iterate quickly.

What doesn’t

SSR frameworks make testing unnecessarily confusing.

Frameworks like Next.js, Astro, TanStack, Qwik, and Solid provide little to no guidance on how to test applications in a reliable and maintainable way. Most of them simply delegate testing to external tools like Playwright or Cypress (example next.js docs), treating testing as an afterthought rather than part of the framework itself.

The problem with SSR frameworks

SSR frameworks blur the line between backend and frontend. In theory, this sounds powerful. In practice, it creates serious testing problems.

Yes, you need to test both frontend and backend behavior, but SSR frameworks don’t offer a clear or opinionated way to do that. If you look at their documentation, testing is either:

Completely missing
Mentioned briefly
Outsourced to E2E tools like Playwright or Cypress

This effectively means: “Here’s how to build fast. Testing is your problem.”

From a company perspective—especially one building a long-lived product—this is a big red flag. You want:

Tests that are easy to write
Tests that reliably fail when something is actually broken
Tests that help reproduce bugs
Tests that evolve with the product

Most SSR frameworks don’t provide that. They optimize for speed of development, but you start accumulating testing debt from day one.

“But you can unit test, right?”

Technically, yes. But in practice, unit testing frontend code often becomes testing for the sake of testing.

What usually happens:

You mock half of the system
You test implementation details
You don’t test real user interactions

Eventually, you fall back to Playwright. And now:

Tests live outside your app
They’re slower
They’re harder to debug
They don’t feel like part of your development workflow

This is extremely common in Next.js applications. To this day, I haven’t seen a truly robust testing setup for Next.js that:

Fails only when something meaningful is broken
Avoids implementation details
Is easy to write and maintain

By “robust,” I mean tests that actually protect the product—not just increase coverage numbers.

React Router loaders and actions: an exception

In the React ecosystem, I found one notable exception: React Router, specifically createRoutesStub.

This API is interesting because it allows you to:

Mock routes with loaders and actions
Create different scenarios per page
Test frontend behavior realistically
test loaders and actions separately as pure functions

This separation of concerns is something many frameworks try to replicate—but React Router gets it right.

The API design makes testing:

Straightforward
Explicit
Predictable

Even better, migrating from SPA data mode to framework (SSR) mode is incremental and low-risk.

After researching multiple alternatives, and considering that testing is one of the most critical aspects of a product, React Router is the only SSR-capable solution I’d personally choose today.

Using TWD with React Router

When building TWD, we noticed how powerful createRoutesStub was—and decided to use it in a different way.

Instead of testing routes in isolation, we:

Added a dedicated testing route
Executed TWD tests inside the real application
Rendered pages using route stubs
Controlled loaders, actions, and scenarios per test

Here’s the setup.

Route configuration

import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("todos", "routes/todolist.tsx"),
  route("testing", "routes/testing-page.tsx"),
] satisfies RouteConfig;

Testing page

// app/routes/testing-page.tsx
let twdInitialized = false;

export async function clientLoader() {
  if (import.meta.env.DEV) {
    const testModules = import.meta.glob("../**/*.twd.test.{ts,tsx}");
    if (!twdInitialized) {
      const { initTWD } = await import('twd-js/bundled');
      initTWD(testModules, {
        serviceWorker: false,
      });
      twdInitialized = true;
    }
    return {};
  } else {
    return {};
  }
}

export default function TestPage() {
  return (
    <div data-testid="testing-page" >
      <h1 style={{ opacity: 0.5, fontFamily: 'system-ui, sans-serif' }}>TWD Test Page</h1>
      <p style={{ opacity: 0.5, fontFamily: 'system-ui, sans-serif' }}>
        This page is used as a mounting point for TWD tests.
      </p>
    </div>
  );
}

Example test

import { createRoot } from "react-dom/client";
import { twd, screenDomGlobal } from "twd-js";

let root: ReturnType<typeof createRoot> | undefined;

export async function setupReactRoot() {
  if (root) {
    root.unmount();
    root = undefined;
  }

  // Navigate to the empty test page
  await twd.visit('/testing');
  
  // Get the container from the test page
  const container = await screenDomGlobal.findByTestId('testing-page');
  root = createRoot(container);
  return root;
}

describe("Hello World Test", () => {
  // root instance to re render the stub
  let root: ReturnType<typeof createRoot> | undefined;

  beforeEach(async () => {
    // preparing the root instance
    root = await setupReactRoot();
  });

  it("should render home page test", async () => {
    // mocking the component
    const Stub = createRoutesStub([
      {
        path: "/",
        Component: () => {
          const loaderData = useLoaderData();
          const params = useParams();
          const matches = useMatches() as any;
          return <Home loaderData={loaderData} params={params} matches={matches} />;
        },
        loader() {
          return { title: "Home Page test" };
        },
      },
    ]);

    // Render the Stub
    root!.render(<Stub />);
    await twd.wait(300);
    // Check for the element within our test container
    // We scope the search to the container to be safe, or just search globally since the harness is empty otherwise
    const h1 = await screenDom.findByRole('heading', { level: 1 });
    twd.should(h1, 'have.text', 'Home Page test');
  });
});

Once the test runs, the route is rendered inside the real application, fully interactive, with all assertions passing.

Conclusion

At the end of the day, you have a choice:

Keep using tools that optimize for speed but accumulate testing debt
Or adopt an approach where testing is part of everyday development

For SSR applications, React Router + TWD is the first setup I’ve seen that truly supports:

Real UI testing
Maintainability and easier to debug
Long-lived products
Fast feedback

If you work on large applications with complex requirements, this approach scales far better than traditional SSR testing strategies.

An example on how to integrate twd + react router.

Nexios (ASGI Python framework)

Mon, 14 Jul 2025 12:14:49 +0000

Nexios – A Modern Python Web Framework Built for Speed

The Story Behind Nexios

Nexios was born out of frustration — frustration with bulky frameworks, unnecessary boilerplate, and the over-complication of simple tasks. I wanted a framework that had:

the simplicity of Express.js
the power of FastAPI
the flexibility of raw ASGI
and none of the magic Django-style meta-classes.

So I built Nexios — a lightweight, async-first Python web framework designed to help developers ship fast, clean, and production-ready APIs with minimal setup.

⚙️ How Nexios Works

Nexios is built on ASGI and designed with speed and clarity in mind. You define routes using Python functions — no decorators, no hidden base classes, no magic. Just clean, readable code.

from nexios import NexiosApp

app = NexiosApp()

@app.route("/hello")
async def hello(request, response):
    return {"message": "Hello, Nexios!"}

Under the hood, Nexios handles routing, request parsing, async middleware, response formatting, and more — all in a modular and blazing-fast ASGI engine.

Key Features

✅ Async-first: Built on ASGI for native async performance.
✅ Minimal boilerplate: Get up and running in 5 lines of code.
✅ Custom Auth Backends: JWT, API keys, token rotation, blacklisting — all pluggable.
✅ ORM-Agnostic: Works with Tortoise, Prisma, SQLAlchemy, or no ORM at all.
✅ Zero Magic: No hidden behavior or metaclass gymnastics.
✅ Fast Startup: Instant dev server, instant reload.
✅ Auto Docs: Generate OpenAPI docs without extra setup.
✅ Extensible Core: Built to be hacked and extended.

How to Get Involved

Nexios is open-source and community-friendly. You can:

⭐ Star the repo on GitHub
Report bugs or request features
Contribute modules or plugins
Join discussions in the community

GitHub: https://github.com/nexios-labs/Nexios

Docs: https://nexios-docs.netlify.app

Ready to Try It?

Install it now:

pip install nexios

Create a new project:

nexios new  <project_name>

Then start building APIs your way.

Built by developers, for developers. Nexios is what Python web development should feel like.

Inversion of Control (IoC) Principle

Sun, 13 Jul 2025 21:33:50 +0000

Nowadays, it is very common for applications to use some pre-written code to perform specific tasks. Typically used to structure or provide functionality, this code can be reused and repurposed, avoiding the need to write it from scratch, saving time and effort. These useful codes are usually called Libraries and Frameworks, although they have fundamental differences, they are often confused. Do you know what the biggest difference is between a Library and a Framework? In this article, I’m going to talk about that difference, called Inversion of Control Principle.
Library vs Framework

First things first, let’s talk about the differences. A library is a set of functions or class that provides specific functionality. You can call it to do some work in your code flow and then it returns control to you. You call it and control how and when it gets called. Below is a C code that calls the <math.h> library to calculate the square root. Since we have flow control, we call the method, the already implemented method does the calculation for us, and finally, we show the result.

#include <stdio.h> 
#include <math.h>
  
int main() {
  double number = 16;
  double square_root = sqrt(number);
  printf("%.2lf", square_root);
  return 0;
}

In a different way, a framework works, seen as a skeleton, with some custom behavior that we need to insert and it will call. We just implement a functionality and it calls, but we don’t know how and exactly when, for this reason we lose control, we are inverting control — the framework calls the implementation, instead of the application calling it. Below, we have an example of a framework called Flask, used to create a web server in a simple and extremely powerful way, abstracting aspects such as configurations, sockets and HTTP requests. We don’t worry about this, because the framework does it for us, providing a set of functionalities, widgets and ready-made structures to facilitate development.

from flask import Flask

app = Flask(__name__)

@app.route('/')
def home():
    return "<h1>Hello, Flask!</h1><p>Welcome to the home page.</p>"

@app.route('/about')
def about():
    return "<h1>About</h1><p>This is a simple Flask app.</p>"

if __name__ == '__main__':
    app.run(debug=True)

As you read, inversion of control is a fundamental characteristic of framework, now let’s talk more about this principle.
Inversion of Control Principle (IoC)

As I said before, inversion of control consists of changing the flow of control from the usual flow used in procedural programming and putting external code to manage it. This external code, usually a framework, calls user-provided methods to do something and these methods return control to the framework, or whatever. When you use this framework, it usually plays the role of the main one that defines the skeleton of the step sequence. This concept reminds me of the Template Method design pattern, which is a way to implement the inversion of control principle. In it we defines the template of algorithm in a superclass and subclasses override methods without changing its structure. Did you understand? We implemented it but we don’t know how the template will execute the algorithm.

abstract class Game {
    public final void play() {
        initialize();
        startPlay();
        endPlay();
    }

    protected abstract void initialize();
    protected abstract void startPlay();
    protected abstract void endPlay();
}

class Soccer extends Game {
    @Override
    protected void initialize() {
        System.out.println("Setting up Soccer field...");
    }

    @Override
    protected void startPlay() {
        System.out.println("Kickoff! Match started.");
    }

    @Override
    protected void endPlay() {
        System.out.println("Full time. Match ended.");
    }
}

public class Main {
    public static void main(String[] args) {
        Game soccer = new Soccer();

        System.out.println("\n=== Playing Soccer ===");
        soccer.play();
    }
}

Above, the Game class creates the behavior model. Subclasses, such as Soccer, only implement the content but do not decide the order of execution, and then call the play method, which controls the flow of the application and calls the other methods.
Framework examples

In Flutter, a UI framework, we abstract a lot of things, as it provides a structure, only needing to fill in the customizable parts.

import 'package:flutter/material.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text("User Profile")),
        body: Center(child: Text("Hello, there!")),
      ),
    );
  }
}

In PetalTest, a testing framework I’m developing in Dart inspired by JUnit, we can implement the setUp and tearDown methods, however, we do not call this, the framework will call the implemetation that has been provided by the application. Again, the inversion of control used here is that instead of the application calling a framework method, we delegate this responsability to the framework. If you’re curious about JUnit, check out this article, and I’ll be writing about PetalTest soon.

///PetalTest Framework Example: We don't call this, we just implement it
@ClassTestable()
class ClassTest {

  @BeforeEach()
  void setUp() {
    print("Before Each Test");
  }

  @AfterEach()
  void tearDown() {
    print("After Each Test");
  }
}

In conclusion, this principle gives us the power to separate components, making them more flexible, and also guarantees low coupling — Even more so using dependency injection, another way to implement IoC.

Did you get a better understanding of Inversion of Control? Do you have any questions or find any errors? Let me know, comment below. See you later!

The Pygame Framework I Didn’t Plan: Building Tic-Tac-Toe with Asyncio and Events

Sat, 05 Jul 2025 13:46:49 +0000

Over the last weekend, I spent some time mucking around with Pygame. Despite facing some challenges along the way, I ended up with a working prototype. There was neither design nor specification drafted for the project. Nonetheless, mid-development, a reusable design emerged, and we discussed that in last week’s article. Following that discovery, we will explore the implementation this week and answer the question ‚ “Can we make a framework out of it?”.

Cute illustration from Copilot

The Unexpected Framework: From Pygame Hacks to a Reusable Design

Understanding Awaitables: Coroutines, Tasks, and Futures in Python

As a brief recap to the last article, we know how Pygame is designed to be primitive, and lacks inherent structure. Building a Pygame application would therefore require a developer to begin by writing the main application loop. On the other hand, this also presents an opportunity to design a bespoke structure for graphical application development. By refactoring our work from last week, we will witness how a framework emerges, while adhering the original design goal to stay immutable and reliable.

Adapting the synchronous main application loop to AsyncIO took quite some effort. Despite the complexity involved, it was worth it because it broke the tight coupling of display update and event dispatching loop. Previously, events were only fetched once per display update cycle. If the application was written in a pure event driven manner, delegating work into multiple events would introduce latency.

Now that both event dispatching and display update run independently, ensuring synchronization of application states between the two components is also crucial. Immutability was therefore introduced such that application data can only be changed through publishing changes to relevant queues.

With all the work laid out, this opens up an interesting potential, allowing the orchestration code for event dispatching and display updates to be split from the game logic. Application setup work, such as event handler registrations and the initialization of application-specific data, is the primary area that differs from one application to another.

Sounds like a plan, let’s split it out, and complete the tic-tac-toe game we started.

Photo by Daniel McCullough on Unsplash

Building the Core: Immutable State and Asynchronous Orchestration

It shouldn’t be difficult, right? Given the design goal mentioned earlier, the splitting work was indeed not too difficult. On the other hand, keeping track of the declared dataclasses is another story. Regardless, we will uncover an architectural pattern that forms the framework core through some refactoring work. Some minor revisions will be made to the state management, as well as the main application loop. All this work yields a reusable framework for simple graphical applications.

Previously we were creating multiple queues for different fields in our Application dataclass. Having multiple queues serving similar purpose to update values is fine, though I personally find it wasteful. Why not just consolidate them?

And I did exactly that.

Photo by USGS on Unsplash

Firstly, we start by introducing an Enum to represent the field we intend to update

class ApplicationDataField(Enum):
    STATE = auto()
    ELEMENTS = auto()
    EVENTS = auto()

Secondly, we update the DeltaOperation to always require the field we intend to update

@dataclass
class DeltaOperation(ABC):
    field: ApplicationDataField
    item: Any

Lastly, we need to update the application_refresh function, which is the only place where the Application object is updated throughout the framework.

async def application_refresh(application: Application) -> Application:
    result = application

    with suppress(asyncio.queues.QueueEmpty):
        while delta := application.delta_data.get_nowait():
            field = application_get_field(application, delta.field)

            match delta:
                case DeltaAdd():
                    result = replace(
                        result,
                        **{field: getattr(result, field) + (delta.item,)},
                    )

                case DeltaUpdate():
                    result = replace(
                        result,
                        **{
                            field: tuple(
                                delta.new if item == delta.item else item
                                for item in getattr(result, field)
                            )
                        },
                    )

                case DeltaDelete():
                    result = replace(
                        result,
                        **{
                            field: tuple(
                                item
                                for item in getattr(result, field)
                                if not item == delta.item
                            )
                        },
                    )

    return result

Actual implementation is a little bit longer, but I truncated for brevity. Logically, the current version is rather similar to the previous version, though it only consumes from one single queue (application.delta_data) to update the states in an Application object.

After the minor refactoring to the state management, we shift our attention to the main application loop.

async def main_loop(
    application_setup: Awaitable[Application],
) -> None:
    pygame.init()

    application = await application_setup

    pygame.event.post(pygame.event.Event(SystemEvent.INIT.value))

    tasks = []

    tasks.append(
        asyncio.create_task(
            display_update(
                application.delta_screen,
                application.clock,
            )
        )
    )
    tasks.append(
        asyncio.create_task(events_process(application))
    )

    await application.exit_event.wait()

    pygame.quit()

It is almost similar to the original run function in our original code, with just 2 small changes. Remember I mentioned about wanting a window.onload like system events? Here we are emitting an INIT event before we start the display update and event dispatching loops. Additionally, setup code is passed in as an Awaitable object, that is only scheduled to run after pygame.init().

Understanding Awaitables: Coroutines, Tasks, and Futures in Python

That’s practically it, though extracting them out to another module, is a pain due to how these functions reference numerous dataclasses and other helpers. Alongside these changes, I also added some helpers to deal with in-game state management. Spiritually, the design of these helper functions loosely follows Redux, though the implementation is a lot simpler in my implementation. We shall see them in action when we go through the game implementation next.

Framework in Action: Bringing Tic-Tac-Toe to Life

Framework is now done, what’s next?

What’s a better way to test the framework, than building a game for real? Now that we delegate the orchestration work to another module, we can now focus purely on the game logic. Throughout the discussion, we can observe how the framework design enables building of a simple game with just dispatching events and implementing the handlers. Game state management as mentioned earlier will be discussed as well.

Firstly, let’s set-up the game:

async def setup() -> Application:
    application = Application(screen=pygame.display.set_mode((300, 300)))
    application = await add_event_listeners(
        application,
        (
            (SystemEvent.INIT.value, handle_init),
            (CustomEvent.RESET.value, handle_reset),
            (CustomEvent.MAP_UPDATE.value, handle_update),
            (CustomEvent.JUDGE.value, handle_judge),
        ),
    )

    return application

A new helper add_event_listeners was written for adding multiple event listeners, though they work similarly as the add_event_listener we discussed last week. In case you are wondering at this point, yes, this is all we needed to implement our tic-tac-toe game. Since we split out the orchestration code to another module, our run function now becomes:

from core import main_loop

async def run() -> None:
    await main_loop(setup())

Remember main_loop() takes an Awaitable as argument? This is the reason why setup() was written as a coroutine function, and passed into main_loop function without the await keyword.

Before we start the display update and event dispatching cycles, let’s initialize the game by drawing relevant elements to the application screen object:

async def handle_init(
    _event: pygame.event.Event, target: Application, logger: BoundLogger, **detail: Any
):
    for row, col in product(range(3), range(3)):
        element = await box_draw(target, row, col, 100)
        element = await add_event_listener(
            element,
            pygame.MOUSEBUTTONDOWN,
            handle_box_click,
        )
        await target.delta_data.put(DeltaAdd(ApplicationDataField.ELEMENTS, element))
        await screen_update(target, element) # type: ignore

    pygame.event.post(pygame.event.Event(CustomEvent.RESET.value))

During the initialization phase, the handler draws the 3 x 3 tiles to the screen via box_draw, and then registers a mouse click event to each of them. Each tile is then sent to 2 queues, one to populate the application.elements tuple (via target.delta_data.put), and another to update the display (via screen_update). Once done, the handler invokes the RESET event to start a new game.

async def handle_reset(
    _event: pygame.event.Event, target: Application, logger: BoundLogger, **detail: Any
):
    await state_merge(target, "board", winner=None, state=GameState.RING, board=None)

    for element in target.elements.values():
        delta = await box_redraw(target, (255, 255, 255), element, Symbol.EMPTY) # type: ignore
        await target.delta_data.put(
            DeltaUpdate(ApplicationDataField.ELEMENTS, element, delta)
        )
        await screen_update(target, delta)

As the game is resetting, it first reinitializes the game state via state_merge.The helper sends a DeltaOperation to update application.state to

{
    "board": {
        "winner": None,
        "state": GameState.END,
        "board": None
    }
}

Elements in the game board also get redrawn (via box_redraw) to ensure they do not contain a ring or cross symbol. As we did earlier, all of them are then sent to the queues for application and display update.

Our game is now accepting input. And once a click is registered, the registered event handler is called.

async def handle_box_click(
    _event: pygame.event.Event,
    target: Box,
    application: Application,
    logger: BoundLogger,
    **detail: Any,
) -> None:
    element = None

    match state_get(application, "board").get("state"):
        case GameState.END:
            await logger.ainfo("END")
            pygame.event.post(pygame.event.Event(CustomEvent.RESET.value))

        case GameState.TIE:
            await logger.ainfo("TIE")
            pygame.event.post(pygame.event.Event(CustomEvent.RESET.value))

        case GameState.RING if target.value == Symbol.EMPTY:
            element = await box_update(
                application,
                target,
                Symbol.RING,
            )
            await state_merge(application, "board", state=GameState.CROSS)

        case GameState.CROSS if target.value == Symbol.EMPTY:
            element = await box_update(
                application,
                target,
                Symbol.CROSS,
            )
            await state_merge(application, "board", state=GameState.RING)

        case _:
            await logger.aerror("Invalid click")

    if element:
        pygame.event.post(pygame.event.Event(CustomEvent.MAP_UPDATE.value))

Click events are handled differently, depending on the state of the board. If there is no valid moves available, in the events of an ended or tie game, then we log a message, and emit a RESET event. Otherwise, we update the clicked element to the symbol corresponding to the current state of the board, followed by a board state change for the next symbol. Lastly, we trigger a MAP_UPDATE event to update the current mapping of the board for judging.

@dataclass
class BoardMap:
    mapping: dict[tuple[int, int], Symbol]

async def handle_update(
    _event: pygame.event.Event, target: Application, logger: BoundLogger, **detail: Any
):
    await state_merge(
        target,
        "board",
        map=BoardMap(
            {
                (item.column, item.row): item.value
                for item in target.elements.values()
                if isinstance(item, Box)
            }
        ),
    )

    pygame.event.post(pygame.event.Event(CustomEvent.JUDGE.value))

BoardMap is just a dataclass keeping the current state of the board, what symbol is placed at each tile. As soon as it is updated, a JUDGE event is triggered to evaluate the game.

WIN_LINES = [
    # Rows
    {(0, 0), (0, 1), (0, 2)},
    {(1, 0), (1, 1), (1, 2)},
    {(2, 0), (2, 1), (2, 2)},
    # Columns
    {(0, 0), (1, 0), (2, 0)},
    {(0, 1), (1, 1), (2, 1)},
    {(0, 2), (1, 2), (2, 2)},
    # Diagonals
    {(0, 0), (1, 1), (2, 2)},
    {(0, 2), (1, 1), (2, 0)},
]

async def handle_judge(
    _event: pygame.event.Event, target: Application, logger: BoundLogger, **detail: Any
):
    if not (bmap := state_get(target, "board").get("map")):
        return

    tiles, winner = (), None

    for symbol in (Symbol.RING, Symbol.CROSS):
        places = {coor for coor, item in bmap.mapping.items() if symbol == item}

        for line in WIN_LINES:
            if line.issubset(places):
                winner = symbol
                tiles = line
                break

        if winner:
            break

    if winner:
        await logger.ainfo("Winner is found", winner=winner)
        await state_merge(target, "board", winner=winner, state=GameState.END)

        for element in target.elements.values():
            if (element.column, element.row) in tiles: # type: ignore
                delta = await box_redraw(target, (255, 255, 0), element, winner) # type: ignore
                await target.delta_data.put(
                    DeltaUpdate(ApplicationDataField.ELEMENTS, element, delta)
                )
                await screen_update(
                    target,
                    delta, # type: ignore
                )
    elif (
        len([symbol for _, symbol in bmap.mapping.items() if symbol == Symbol.EMPTY])
        == 0
    ):
        await logger.ainfo("End with a tie")
        await state_merge(target, "board", state=GameState.TIE)

Not the most robust code I would proudly print on a t-shirt and parade with it. Essentially, it judges the game to find the winning line and symbol. Redrawing the winning tiles will take place whenever applicable. Besides that, the relevant state of the board is also queued for update (either an END or TIE) whenever needed.

By utilizing events and state_merge strategically, the simple game of tic-tac-toe is implemented. All the event dispatching work and display update are completely handled by the framework itself. All we needed to do, when changes occur, is to submit the change to the relevant queue. While there are certainly potential improvements to be made, as a weekend project I deem it good enough.

Beyond Tic-Tac-Toe: Lessons Learned and What’s Next

Can we build more things with it?

Short answer to the question is yes, but I don’t see much point in doing so for most people. Instead, we should reflect on what we learned so far. What is the purpose of the project? What have we achieved so far? What do we do with this piece of code?

Extracting the orchestration code into a framework is a totally unexpected outcome. Yet, I am happy with the turns of events leading to what we have now. With some polish, the resulting framework should be able to be applied for other simple graphical applications. Personally, I am quite curious on seeing how the framework scales with more elements on screen.

Photo by Dan Freeman on Unsplash

As an experimental project, it certainly is quite rough on the edges. Much thought and polish are still needed in the framework API design for consistency. There are also some experimental code snippets that are not covered in the article as they are irrelevant to the game featured this week. Some of the most interesting helpers I can’t wait to try out are the functions inspired by setTimeout and element.dispatchEvent().

Perhaps a re-implementation of the code rain animation a-la the Matrix?

Code Rain’s Revelation: Embracing Existence Before Perfection

Now, back to the original question asked earlier, at the beginning of this section. The framework is proven capable of building a simple game, as shown in this article. Despite that, do go for a proper game engine like Godot for serious projects. Treat the work presented here as a personal passion project, though I am open for feedback and collaboration. Seriously, this exploration makes me appreciate how game engines do all the heavy-lifting work.

Finally, thanks for reading this far. If you are interested in checking out the project, it is still hosted on GitHub at the same repository. Though I cannot commit to a fixed publication schedule due to my new job, I shall try writing again soon.

A quick note on how this article came together. While Gemini helped with the drafting and refining of the language, all the core ideas, the technical insights, and every line of code you’ve seen are entirely mine. This project truly reflects my personal journey and passion for game development. If you enjoyed this deep dive and want to follow more of my explorations into coding and game development, consider subscribing or following me on Medium. Your support means a lot!

DevLog 20250611: Audio API Design for Divooka Glaze!

Wed, 11 Jun 2025 18:14:04 +0000

Glaze! is an interactive media framework in Divooka that features a Processing-like interface.

Overview

Today, I'm laying the groundwork for audio APIs for our Glaze! framework.

Divooka Glaze! draws inspiration from SFML and Processing, so we need to understand how those two handle audio first.

How SFML Handles It (SFML.Net)

To play audio in SFML.Net, we use the SFML.Audio module, which provides two main classes:

Sound + SoundBuffer for short, fully-loaded sounds (like sound effects).
Music for long, streamed audio (like background music).

Playing Short Sounds

Short audio files (WAV, OGG, FLAC, etc.) can be fully loaded into memory:

// Load the entire file into a buffer (only do this once per sound).
SoundBuffer buffer = new SoundBuffer("hit.wav");

// Create a Sound instance and assign the buffer.
Sound hitSound = new Sound(buffer);

// Optional settings
hitSound.Volume = 75f;    // 0–100
hitSound.Pitch  = 1.2f;   // playback speed
hitSound.Loop   = false;  // play once

// Play it
hitSound.Play();

// Make sure the program doesn't exit immediately,
// otherwise the sound will be cut off:
while (hitSound.Status == SoundStatus.Playing)
    System.Threading.Thread.Sleep(10);

Key points:

Reuse the same SoundBuffer if you need to play the same sound multiple times.
Keep the Sound (and its SoundBuffer) in scope until playback finishes.

Streaming Music

For large files (e.g., full-length tracks), use the Music class, which streams from disk:

It doesn't load the entire file into RAM.
Suitable for long tracks, though with slightly higher CPU usage due to streaming.

// Create a Music instance; it will stream the file on the fly.
Music backgroundMusic = new Music("background.ogg");

// Optional settings
backgroundMusic.Volume = 50f;
backgroundMusic.Loop   = true;

// Start playback
backgroundMusic.Play();

// In a game loop we'd typically:
// while (window.IsOpen()) { /* update, draw, etc. */ }

Common Pitfalls

Missing Native DLLs: If you get DllNotFoundException, ensure all CSFML native libraries are present.
Scope & Lifetime: If Sound or Music goes out of scope (is garbage collected), playback stops.
Program Exit: If the application ends before the audio finishes, you won't hear the full sound - keep the main thread running or integrate playback into the render loop.

How Processing Handles It

Processing offers sound support through the built-in Sound library and the legacy Minim library.

Below are the two most common approaches.

The Built-in Sound Library

Installing/Importing

In the Processing IDE, go to Sketch → Import Library… → Add Library…
Search for “Sound”, then click Install (if not already installed).

Placing Audio Files

Create a folder named data in the sketch's directory.
Copy audio files (e.g., music.mp3 or beat.wav) into that data folder.

In the sketch, import and declare:

import processing.sound.*;
SoundFile song;

void setup() {
  size(400, 200);
  // Load a file named "music.mp3" from /data
  song = new SoundFile(this, "music.mp3");
  song.play();        // start playing once
}

void draw() {
  background(0);
  // (Optionally visualize or control playback here)
}

Looping, Volume, Rate

void setup() {
  size(400, 200);
  song = new SoundFile(this, "music.mp3");
  
  song.loop();               // loop indefinitely
  song.amp(0.5);             // set volume (0.0–1.0)
  song.rate(1.2);            // change playback speed (1.0 = normal)
}

Minim

Minim handles things similarly, albeit through AudioPlayer:

import ddf.minim.*;
Minim minim;
AudioPlayer player;

void setup() {
  size(400, 200);
  
  minim = new Minim(this);
  // loadFile(filename, bufferSize)
  player = minim.loadFile("music.mp3", 2048); // Place MP3/WAV files inside the sketch's `data` folder.
  player.play();
  
  // Looping & Controlling
  player.loop();        // loop playback
  player.setGain(-10);  // lower volume: gain in dB
  player.setTempo(1.5); // speed multiplier
}

void draw() {
  background(50);
  // ...
}

Where to Store Files: Always place audio files in the sketch's data/ folder so Processing can find them.
File Formats:
- Sound library: supports WAV, AIFF, MP3 (depending on platform).
- Minim: supports MP3, OGG, WAV.
Latency / Real-Time: For low-latency playback or live audio input/processing, Minim (or advanced libraries like Beads or TarsosDSP) may be preferable.
Visualizations: Both libraries support real-time audio analysis (waveforms, FFT), which is great for interactive visuals.

Observations

Those two statements are crucial:

// Load a soundfile from the /data folder of the sketch and play it back
file = new SoundFile(this, "sample.mp3");
file.play();

We can observe a few things regarding API design:

It's procedural and imperative - we create resources first, then set properties, then play/stop via the resource reference. Importantly, it's necessary to keep a reference for later control.
Resources might require explicit (or scope-based) release.

On the other hand, I'm more interested in a "functional" style API, like this:

The Approach

We could implicitly load and manage resources, releasing them at the end of the application lifetime (on window close), if no explicit reference is needed. However, distinguishing between SoundBuffer and Sound (both are IDisposable) can be tricky when deciding which to persist. At the very least, this is what we should expose via PlaySound() and PlayMusic().

private void ReleaseResources()
{
    // Sounds
    foreach (Sound item in _soundInstances)
        item.Dispose();
    foreach ((string key, SoundBuffer item) in _soundBuffers)
        item.Dispose();
    foreach (Music item in _music)
        item.Dispose();
}

In fact in the current design we cannot share the underlying instance - since Glaze! is implementation-agnostic - unless we introduce strongly typed types for SoundBuffer, Sound, and Music, so all implementations can recognize them. Otherwise, we can't return any instance objects.

// IInteractiveServiceProvider, which is ignorant of SFML.Net's existence
#region Audio Engine
void PlaySound(string filePath);
void PlayMusic(string filePath, bool loop = true);
#endregion

A slightly inelegant shortcut is to expose them as untyped "object handles":

/// <summary>
/// One-shot sound.
/// </summary>
object PlaySound(string filePath);
/// <summary>
/// Loopable BGM etc.
/// </summary>
object PlayMusic(string filePath, bool loop = true);
/// <param name="volume">0–100f</param>
void SetVolume(object soundOrMusic, float volume);
/// <param name="pitch">0–1f</param>
void SetPitch(object soundOrMusic, float pitch);
void SetLoop(object music, bool loop);

While it might seem "unsafe" on the paper, it works well in Divooka's graphical interface:

(This is partly thanks to Divooka's support for return value naming via XML doc comments, e.g., <returns name="Music">A music instance.</returns> for PlayMusic().)

Conclusion

So far so good! There's a lot we can enhance in the audio engine - more parameters, DSP support, etc. For example, Processing has very neat functions for low-pass/high-pass filters.

But for now, we can play sounds - and that's a solid start!

References

Processing Sound library documentation: here
Divooka Glaze! framework documentation on Methodox Wiki

How To Build A Raycast Extension ✨

Sat, 31 May 2025 21:22:15 +0000

In this article, you are going to learn how to build a Raycast extension. We are going to split this tutorial into two. In the first tutorial you will learn:

What Raycast is?
Raycast APIs.

In the second tutorial, you will learn:

How to build a Raycast extension.
How to publish a Raycast extension.
How to update a Raycast extension.

Raycast

Raycast is a productivity tool built for developers by developers. It helps developers save time by adding all the tools that they need in one place to avoid continuous context switching between browser tabs.

Raycast's UI and UX are incredible, everything you need is in one interface and each tool one keyboard command away. One of the reasons that I as an engineer enjoy using Raycast apart from it's great UI and UX, is there openness and inclusion of the community. Instead of the Raycast team building the entire ecosystem of extensions on their own, they have a documentation guide on how developers can build their own Raycast extension and publish it to the Raycast store. The Raycast store has over 2.13K extensions that have been built by both the Raycast team and the community.

In today's world AI is part of our lives and it makes our everyday tasks much simpler. Raycast has not been left behind in matters related to AI. As a matter of fact, AI integrates seamlessly into Raycast as if they were meant for one another. You can be able to schedule meetings, cancel meetings, add events and all the great stuff that would require 5 minutes of your life in 30 seconds by simply typing a command and voila! Everything has been set.

Raycast's pricing model is insanely cheap, they have a free and two paid tiers. The free tier includes: core features, access to thousands of extensions, custom extensions, developer tool, Raycast AI ( Free 50 messages by trying any Pro model ) etc. The other two paid tiers are $8/month and $16/month respectively. You can check out their pricing model and what they offer here: Raycast pricing.

Currently, Raycast is only available on MacOs but they do have a waitlist if you are on windows. You can join the Windows waitlist here: Raycast Windows waitlist.

Raycast APIs

Raycast has powerful APIs that enable developers to tap into it's core engine. These APIs include but not limited to UI components, CLI etc. Let's look at each of them.

UI components

Raycast provides developers with building blocks to build their extensions. These UI components have a similar look to React's Radix UI. The Raycast API works with React, take a look at this code: import { useState } from "react"; import { List } from "@raycast/api";

In the code above, we import useState from React to handle our state and List component from the @raycast/api for building our UI. The @raycast/api provides us with UIs and utilities for building our extension, these UIs and utilities include but not limited to:

Detail component.
Form component.
Grid component.
Action component.
Toast component.
showToast function.

In the next tutorial, we’ll explore and work with each one in detail.

CLI

The Raycast CLI allows you to build, develop, and lint your extension. The CLI is part of the @raycast/api package and is automatically installed in the extension directory during setup. The CLI has various commands for specific use cases:

Help command: To get a list of the available CLI commands.
Build command: Creates an optimized production build of our
extension for distribution.
Development command: Starts our extension in development mode.
Lint command: Runs ESLint for all files in the src directory.
Migrate command: Migrates our extension to the latest version of the
@raycast/api.
Publish command: Verifies, builds, and publishes an extension to the
Raycast store.

In the next tutorial, we are going to learn how to build and publish a Raycast extension.

Till then, happy hacking ✨

Quarkus Neo4j: How to build a Quarkus app with Neo4j

Fri, 30 May 2025 20:23:12 +0000

I've recently been working on expanding my horizons in different Java frameworks, and Quarkus was on my list to try.

Quarkus is a Kubernetes-native Java framework designed to reduce an application's footprint, ideal for addressing challenges in deploying, running, and maintaining applications in cloud-based environments.

It has become a major player in list of frameworks, so naturally, I wanted to try it out! I started by following the first few steps in this blog post, as it outlines how to get a project up and running and the dependency needed for Neo4j. I felt the Quarkus Neo4j documentation was a bit overly complicated and verbose for a starter app.

All of the code for this blog post is available in the quarkus-coffee-shop Github repository.

Note: I also have a sister project using Spring Data Neo4j, for comparison. :)

Creating a project

Similar to the Spring Initializr that offers a web interface for defining a project and its dependencies, Quarkus has code.quarkus.io. Quarkus also offers a CLI, which would be especially helpful for creating multiple projects quickly.

On code.quarkus.io, I filled out the project name, and then added three dependencies for the Neo4j client, RESTEasy Classic, and RESTEasy Classic JSON-B. Once that is complete, click the Generate your application blue button to download the .zip file.

Next, unzip the folder and open it in your preferred IDE. The project template includes a GreetingResource class with a default /hello endpoint, so we can run the application and call the endpoint to see a message.

./mvnw quarkus:dev

http ":8080/hello"

Hello RESTEasy

Setup

However, to build out our application, there are a couple of adjustments needed to the pom.xml. To utilize object graph mapping capabilities, we need to include the neo4j-ogm-quarkus library, which currently (v3.14.0) is only compatible with Quarkus 3.22.1.

Note: There is an open Github pull request for 3.23, which may be released soon.

So, we need to downgrade Quarkus's platform version in order to use OGM (for now). Open the pom.xml, then navigate to the <properties> section and change the quarkus.platform.version property to version 3.22.1, as shown below.

<properties>
    <quarkus.platform.version>3.22.1</quarkus.platform.version>
</properties>

Next, add the following library to the <dependencies> section.

<dependency>
    <groupId>org.neo4j</groupId>
    <artifactId>neo4j-ogm-quarkus</artifactId>
    <version>3.14.0</version>
</dependency>

Next, we need a Neo4j database and to connect to the instance from our application.

Creating and connecting to an instance of Neo4j

If you don't have one already, spin up a free cloud instance of Neo4j Aura.

Once the instance is running, load the data by clicking on the Query tool along the left console menu, then copy the contents of the coffee shop import script and paste into the input box at the top of the window. Click the play button on the right of the input box and wait for all steps to complete.

Back in the Quarkus application, open the src/main/resources/application.properties file to add configuration for connecting to Neo4j.

# Neo4j config
quarkus.neo4j.uri=<NEO4J_URI>
quarkus.neo4j.authentication.username=<NEO4J_USERNAME>
quarkus.neo4j.authentication.password=<NEO4J_PASSWORD>

# OGM config
org.neo4j.ogm.use-native-types=true

The first three properties should match the URI, username, and password for the Neo4j instance. The final property is so that OGM will map temporal data types (dates and times) correctly.

The next step is to create the domain classes for Order, Receipt, Staff, and Customer entities.

Domain classes

The domain model for this application contains 4 main entities and the relationships between them.

We will map the Order entity first. Create a new file named Order.java and define the class as follows.

import java.time.LocalDate;
import java.time.LocalTime;

import org.neo4j.ogm.annotation.Id;
import org.neo4j.ogm.annotation.NodeEntity;
import org.neo4j.ogm.annotation.Relationship;

@NodeEntity
public class Order {
    @Id
    private String transactionId;
    private String orderId;
    private LocalDate orderDate;
    private LocalTime orderTime;
    private String inStore;

    //make OGM happy
    public Order() {
    }

    public Order(String transactionId) {
        this.transactionId = transactionId;
    }

    //getters and setters
}

The @NodeEntity annotation is for OGM to map this class to an Order node in Neo4j, and the @Id annotation pinpoints the id field for the class. After the class variables for orderId, etc, we have to create an empty constructor, as well as a required parameter constructor for OGM. Then, the getters and setters follow.

Next, let's define the Staff.java and Customer.java classes.

Staff.java:

@NodeEntity
public class Staff {
    @Id
    String staffId;
    String firstName;
    String lastName;
    LocalDate startDate;

    public Staff() {
    }

    public Staff(String staffId, String firstName, String lastName, LocalDate startDate) {
        this.staffId = staffId;
        this.firstName = firstName;
        this.lastName = lastName;
        this.startDate = startDate;
    }

    //getters and setters
}

Customer.java:

@NodeEntity
public class Customer {
    @Id
    private String customerId;
    private String customerName;
    private String loyaltyId;

    public Customer() {
    }

    public Customer(String customerId, String customerName, String loyaltyId) {
        this.customerId = customerId;
        this.customerName = customerName;
        this.loyaltyId = loyaltyId;
    }

    //getters and setters
}

These classes are similar to Order, so the code shouldn't contain any surprises.

Relationships

The next step is to define relationships. While we can directly define the relationship by adding a new variable to point to the other entity, this domain also contains relationship properties between Order and Customer that hold information on how many items the customer ordered and the total amount for the order.

To map these properties, we need another class that holds the receipt information.

import org.neo4j.ogm.annotation.EndNode;
import org.neo4j.ogm.annotation.GeneratedValue;
import org.neo4j.ogm.annotation.Id;
import org.neo4j.ogm.annotation.RelationshipEntity;
import org.neo4j.ogm.annotation.StartNode;

@RelationshipEntity("BOUGHT")
public class Receipt {
    @Id @GeneratedValue
    private Long id;

    private Integer itemsInOrder;
    private Double orderTotal;

    @StartNode
    private Customer customer;

    @EndNode
    private Order order;

    //getters and setters
}

The @RelationshipEntity maps this class to the BOUGHT relationship in Neo4j. @Id and @GeneratedValue define the id and note that it's an internally-generated id. Two class variables hold the number of items and order total. Then, the @StartNode and @EndNode point to the starting and ending entities for the relationship.

Finally, we can connect these pieces together by mapping the relationships from the Order.java class.

@NodeEntity
public class Order {
    //previous class variables

    @Relationship(value = "BOUGHT", direction = Relationship.Direction.INCOMING)
    private Receipt receiptAndCustomer;
    @Relationship(value = "SOLD", direction = Relationship.Direction.INCOMING)
    private Staff staff;

    //constructors

    //getters and setters
}

There are two definitions - one for each relationship. The @Relationship annotation defines the relationship type (BOUGHT or SOLD) and the direction (both incoming to the Order node). Those are mapped to class variables that return the entity type (Receipt and Staff).

These definitions map connections from the Order class to related entities. Now we need to define a repository and resource to retrieve entities from the database and create endpoints for us to access it.

Repository class

Create an OrderRepository.java and populate it with the following code:

import java.util.Map;
import org.neo4j.ogm.session.SessionFactory;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class OrderRepository {
    private final SessionFactory sessionFactory;

    OrderRepository(SessionFactory sessionFactory) {
        this.sessionFactory = sessionFactory;
    }
    
    Iterable<Order> findTenOrders() {
        return sessionFactory.openSession().query(Order.class, 
            "MATCH (order:Order)<-[rel:BOUGHT]-(c:Customer), " +
                "(order)<-[rel2:SOLD]-(s:Staff) " + 
                "RETURN order, collect(rel), collect(c), collect(rel2), collect(s) LIMIT 10;", 
            Map.of());
    }
}

The @ApplicationScoped annotation will share this repository bean across the application. Inside the class, we inject the OGM SessionFactory into the class to handle connections to Neo4j.

Next, we define a method to find 10 orders. The query retrieves customers who bought orders, and staff who sold those orders. By returning the order nodes and collecting related entities, unique patterns (orders) are returned. OGM will map returned nodes and relationships accordingly.

Finally, we need an endpoint to access this information.

Resource (i.e. Controller) class

Quarkus uses the term Resource rather than Controller, so the OrderResource.java will handle the user interface by creating a REST api.

import jakarta.enterprise.context.RequestScoped;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@RequestScoped
@Path("/orders")
public class OrderResource {
    private final OrderRepository orderRepository;

    @Inject
    public OrderResource(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Iterable<Order> getOrders() {
        return orderRepository.findTenOrders();
    }
}

First, the @RequestScoped narrows this bean to each request, and the @Path defines the root url of /orders. Within the class, there is a variable for the repository and it's injected into the class constructor, so that we can call the query method we wrote earlier.

Next, we define the getOrders() method as a HTTP GET method that will return multiple orders (Iterable<Order>) in JSON output @Produces(MediaType.APPLICATION_JSON). The method will call the repository's findTenOrders() method.

Now we can test the application!

Run and test the application

Run the application in dev mode with the following command:

./mvnw quarkus:dev

We can test the default /hello endpoint (GreetingResource), as well as the /orders endpoint (OrderResource), which retrieves 10 order entities (and their related entities) from Neo4j:

http ":8080/hello"

http ":8080/orders"

Wrapping up!

In this blog post, we walked through the following:

How to create a Quarkus application using the Quarkus project online tool.
How to connect to Neo4j.
How to map domain entities to Neo4j with OGM.
How to run queries in Neo4j and access the data via a REST endpoint.

This project is a jumping point into so many other facets, and I'll be sure to bring you along for the ride.

Happy coding!

Resources

Github repository: Accompanying code for this blog post
Documentation: What is Quarkus?
Data set: Coffee shop graph data
Documentation: Quarkus Neo4j
Github repository: Neo4j Quarkus OGM library

Healenium: Anti-flakiness potion

Wed, 30 Apr 2025 01:40:18 +0000

Healenium: Anti-flakiness potion

Test automation flakiness is a long-standing headache in UI testing. Selectors break, tests fail, and debugging becomes a frustrating ritual. Enter Healenium — a self-healing solution that enhances Selenium and Appium by automatically fixing broken locators at runtime.

In this article, you'll learn how Healenium integrates with your Java-based Selenium or Appium test framework, and how it transforms brittle tests into robust, maintainable assets.

What Is Healenium?

Healenium is an open-source library designed to augment web and mobile automation frameworks by enabling automatic healing of element locators. When a locator fails (due to minor UI changes, for instance), Healenium uses machine learning and history-based matching to find the most likely alternative, allowing the test to continue without failure.

Reference: healenium.io/docs

Core Features

Automatic Locator Healing: Fixes broken XPath or CSS selectors on-the-fly.
ML-based Matching: Uses previous DOM snapshots to find similar elements.
Minimal Code Change: Simple integration into existing test frameworks.
Compatibility: Works with Selenium WebDriver and Appium.
Self-Healing Report Dashboard: Visualizes healed selectors and statistics.
Multilingual Support via Proxy: Enables healing across various languages using Healenium-Proxy.

☕ Healenium + Selenium-Java: Integration Guide

1. Add Maven Dependencies

<dependency>
    <groupId>com.epam.healenium</groupId>
    <artifactId>selenium</artifactId>
    <version>3.5.5</version>//Update accordingly
</dependency>

2. Wrap Your Driver

WebDriver delegate = new ChromeDriver();
SelfHealingDriver driver = SelfHealingDriver.create(delegate);

Now driver.findElement(...) is backed by Healenium's self-healing engine.

3. Set Up Healenium Backend (Optional but Recommended)

Healenium stores and compares locator history. To do this, run the backend via Docker:

docker-compose -f docker-compose-local.yml up

Includes:

Healing Service
Postgres DB
UI Dashboard at http://localhost:7878

Configure Healing Behavior (Optional)

Create a custom configuration file named healenium.properties under the test/resources directory:

recovery-tries = 1
score-cap = 0.5
heal-enabled = true
hlm.server.url = http://localhost:7878
hlm.imitator.url = http://localhost:8000

Config Parameter Explanations:

recovery-tries – Number of proposed healed locators to try.
score-cap – Healing only proceeds if the match score is >= this threshold (e.g., 0.5 means 50%).
heal-enabled – Enables/disables healing (can be overridden using -Dheal-enabled=false).
hlm.server.url – Address of the Healenium backend.
hlm.imitator.url – Address of the imitate service.

Disable Healing for Specific Methods

Use the @DisableHealing annotation to skip healing for specific methods:

@DisableHealing
public boolean isButtonPresent() {
    try {
        return driver.findElement(By.cssSelector(".test-button")).isDisplayed();
    } catch (NoSuchElementException e) {
        return false;
    }
}

Healenium Report

Healenium generates a detailed HTML report after each Selenium session, accessible via browser.

Local URL: http://localhost:7878/healenium/report/

Report Sections Include:

Path to healed locator
Failed locator value
Healed locator value
Screenshot of healed locator on page
Healing success confirmation (correct/not correct)
Score of the healing result

⚠️ Note: The Maven/Gradle report plugins are deprecated and no longer supported.

Healenium + Appium

Healenium supports Appium too, using the same SelfHealingDriver. Simply delegate your mobile driver (like AndroidDriver or IOSDriver) to SelfHealingDriver.create(...). For example:

AppiumDriver delegate = new AndroidDriver<>(url, capabilities);
SelfHealingDriver driver = SelfHealingDriver.create(delegate);

Ensure that Appium and Healenium versions are compatible. Use native locators (like XPath, accessibility ID) for best results.

Real-World Usage Tips

Store all your element locators centrally to monitor which ones heal frequently.
Use Healenium’s dashboard to identify flaky elements and clean up your selectors.
Combine with Allure Reports to attach healed screenshots and diagnostics.

Beyond Java: Other Language Support

Healenium-Proxy enables healing across all Selenium-supported languages, such as Python, JavaScript, C#, and more.

To use Healenium in other languages, simply create a RemoteWebDriver and connect it to the Healenium-Proxy instance. This allows clients in any language to benefit from Healenium's healing capabilities without needing native library support.

from selenium import webdriver

options = webdriver.ChromeOptions()
driver = webdriver.Remote(
    command_executor='http://localhost:7878/wd/hub',
    options=options
)

This approach allows teams to integrate healing logic regardless of the language or test framework they use.

Enable Console Debug with SimpleLogger

To see detailed Healenium logs during test execution, configure simplelogger.properties as follows:

org.slf4j.simpleLogger.log.healenium=debug

Place this file in your test/resources directory. This enables console-level debug logging for Healenium's internal operations, helping with troubleshooting and development.

Last Thoughts

Healenium empowers your automation framework with self-healing capabilities, helping reduce flaky failures, improve resilience, and speed up debugging. Whether you're working with Selenium for web or Appium for mobile, Healenium is a lightweight but powerful addition.

Official Docs | GitHub

EF Core Interceptors: Supercharge Your Data Access with the Decorator Pattern

Thu, 20 Mar 2025 08:25:11 +0000

Learn how to hook into EF Core operations using interceptors, leverage the Decorator Pattern for clean cross-cutting concerns, and see real-world examples like SQL logging and auditing.

Table of Contents

A Brief History of EF Core Interceptors
What Are EF Core Interceptors?
EF Core Interceptors and the Decorator Pattern
Top Use Cases for EF Core Interceptors
Example 1: Logging SQL Queries
Example 2: Auditing SaveChanges
Final Thoughts

A Brief History of EF Core Interceptors

EF Core interceptors were first introduced in EF Core 3.0 (released in September 2019). This version marked a significant step forward in EF Core's extensibility, allowing developers to intercept low-level database operations like commands, connections, and transactions.

Since then, Microsoft has expanded interceptor capabilities in newer versions:

EF Core 5.0: Introduced SaveChanges interceptors for tracking changes at the context level.

EF Core 6.0+: Continued performance improvements and better support for asynchronous interception.

What Are EF Core Interceptors?

In Entity Framework Core (EF Core), interceptors allow developers to hook into the execution pipeline of EF Core's operations. Think of them as middleware for your database interactions. You can intercept events such as:

SQL command execution
Connection opening/closing
Transactions
SaveChanges lifecycle

This lets you inject custom logic like logging, auditing, validation, or performance metrics without modifying your application’s core logic.

EF Core Interceptors and the Decorator Pattern

EF Core interceptors are a real-world application of the Decorator Pattern, a classic design pattern where functionality is wrapped around existing behavior to extend or alter it.

The core EF operation is the base object.
Your interceptor is the decorator.
You add behavior before or after EF Core’s operation — without altering EF’s core.

This approach promotes clean code, separation of concerns, and makes your custom behavior reusable and testable.

Top Use Cases for EF Core Interceptors

– SQL Query Logging

– Track database queries for performance or debugging.

– Auditing – Automatically log user actions and timestamps.

– Soft Deletes – Intercept delete commands and convert them to updates.

– Command Modification – Change or enrich raw SQL before execution.

– Multi-Tenant Filtering – Inject filters dynamically for multi-tenant scenarios.

Example 1: Logging SQL Queries

Let’s log every SQL command executed by EF Core.

Step 1: Create a SQL Logging Interceptor

using Microsoft.EntityFrameworkCore.Diagnostics;
using System.Diagnostics;

public class SqlLoggingInterceptor : DbCommandInterceptor
{
    public override InterceptionResult<DbDataReader> ReaderExecuting(
        DbCommand command, 
        CommandEventData eventData, 
        InterceptionResult<DbDataReader> result)
    {
        Debug.WriteLine($"SQL Executed: {command.CommandText}");
        return base.ReaderExecuting(command, eventData, result);
    }
}

Output:

SQL Executed: SELECT * FROM [Users] WHERE [IsActive] = 1

Step 2: Register the Interceptor

public class AppDbContext : DbContext
{
    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder
            .UseSqlServer("YourConnectionString")
            .AddInterceptors(new SqlLoggingInterceptor());
    }
}

Example 2: Auditing SaveChanges

Let’s implement automatic auditing of entity modifications.

Step 1: Define an Auditable Entity Base Class

public abstract class AuditableEntity
{
    public DateTime ModifiedAt { get; set; }
    public string ModifiedBy { get; set; }
}

Step 2: Implement a SaveChangesInterceptor

public class AuditInterceptor : SaveChangesInterceptor
{
    private readonly string _currentUser;

    public AuditInterceptor(string currentUser)
    {
        _currentUser = currentUser;
    }

    public override int SavingChanges(DbContextEventData eventData, int result)
    {
        var context = eventData.Context;
        if (context == null) return base.SavingChanges(eventData, result);

        var entries = context.ChangeTracker
            .Entries<AuditableEntity>()
            .Where(e => e.State == EntityState.Modified);

        foreach (var entry in entries)
        {
            entry.Entity.ModifiedAt = DateTime.UtcNow;
            entry.Entity.ModifiedBy = _currentUser;
        }

        return base.SavingChanges(eventData, result);
    }
}

Final Thoughts

EF Core interceptors are an underutilized gem in the .NET ecosystem. They let you cleanly implement cross-cutting concerns without muddying your core application code. And because they follow the Decorator Pattern, you get flexibility, maintainability, and testability.

Whether you need to log queries, audit changes, enforce soft deletes, or handle custom behavior, interceptors offer a powerful and elegant solution.

References
EF Core Documentation – Interceptors
https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/interceptors

EF Core 3.0 Release Notes (Interceptors introduced)
https://learn.microsoft.com/en-us/ef/core/what-is-new/ef-core-3.0/whatsnew

EF Core SaveChanges Interceptor Docs
https://learn.microsoft.com/en-us/ef/core/logging-events-diagnostics/interceptors#savechanges-interception

Decorator Pattern - Refactoring Guru (for pattern explanation)
https://refactoring.guru/design-patterns/decorator

EF Core GitHub Repository (for latest updates and issues)
https://github.com/dotnet/efcore