DEV Community: Hakim

Stop Fighting Python for Webhooks: Why Node.js is Optimal for Cloud Function Signatures

Hakim — Thu, 18 Jun 2026 03:11:49 +0000

The Cryptographic Trust Problem (Why Webhooks Are Unforgiving)

Webhooks are the nervous system of modern production apps. Whether you are processing a payment on Stripe, tracking a subscription on Lemon Squeezy, or fulfilling an order via Shopify, webhooks are how external platforms tell your backend: "Hey, something important just happened".

Because these webhook endpoints have to be publicly accessible, they are prime targets for malicious actors.

To prevent this, platforms use cryptographic signature verification.

The Golden Rule of Verification

When a provider sends a webhook, they take the HTTP request body and hash it with a shared secret key using HMAC-SHA256. They pass this resulting signature in the request headers (like Stripe-Signature).
When the request hits your server, your code has to do the exact same math:

Grab the shared secret.
Grab the exact raw bytes of the incoming request body.
Hash them together and compare your result with the signature in the header.

This process is completely binary and zero-tolerance. If your backend framework alters even a single byte—adding a trailing newline, stripping a whitespace, or reordering a JSON key during parsing—the math changes entirely. The signatures won't match, and the verification will fail.

This brings us to our fundamental architectural bottleneck: to verify a webhook, you must intercept the request before your framework touches it.

Why Python/Werkzeug Struggles

If you build a Cloud Function in Python using the Firebase Functions SDK, you are working on top of Flask, which relies on Werkzeug to handle the underlying web server mechanics.

Werkzeug is fantastic for standard web apps, but it has a specific architectural design that makes webhook verification a nightmare: it treats the incoming request body as a one-time, sequential input stream.

The Single-Consumption Stream
Under the WSGI (Web Server Gateway Interface) standard that powers Python web frameworks, the network payload arrives as an active stream.

Here is exactly how the trap snaps shut:

The Eager Parse: The moment a webhook hits your Python Firebase Function with a Content-Type: application/json header, the underlying framework tries to be helpful. It immediately reads the incoming byte stream to parse the JSON and populate the request.json object.
The Empty Stream: Because the stream was read to build that JSON object, the stream pointer is now at the very end. If you later call request.get_data() or try to read request.stream, you get nothing but an empty byte string (b'').
The Mutation Disaster: "Fine," you might think, "I'll just take the parsed request.json dict and turn it back into bytes using json.dumps()." Do not do this. When a framework parses JSON into a Python dictionary, it strips out original whitespaces, removes payload formatting, and can completely reorder the object keys. Re-encoding that dictionary into bytes will yield a completely different string than what the provider sent, instantly breaking your HMAC signature verification.

The Workaround: To circumvent this in Python, you have to write defensive, hacky middleware or override Werkzeug’s request class caching before the request lifecycle begins, caching the raw stream into memory manually. It is boilerplate-heavy, fragile, and completely unnecessary.

The Node.js Superpower

While Python’s Werkzeug makes you fight the request lifecycle to protect your raw bytes, the Node.js runtime for Firebase Cloud Functions handles this exact architectural challenge elegantly.

Node.js treats network requests as asynchronous readable streams. But more importantly, the underlying Google Cloud Functions framework for Node.js includes a built-in, quality-of-life feature specifically engineered to save developers from the webhook signature trap.

The Decoupled Architecture

When an HTTP request hits a Node.js Firebase Function, the runtime intercepts the incoming byte stream before any middleware or parsing logic can touch it.

The Native Cache: The framework reads the raw stream immediately and saves those exact, unmutated bytes as a native JavaScript Buffer.
The Injection: It then injects this buffer directly onto the request object as req.rawBody.
The Eager Parse (Safe Version): Afterwards, the framework goes ahead and parses the JSON payload into a clean, traversable JavaScript object, assigning it to req.body.

Because these two properties exist simultaneously, Node.js completely decouples payload data usage from cryptographic verification.

Node.js Wins

You don't have to choose between convenience and security. You can use req.body.data.object.id to read your payment details in your application logic, while safely passing req.rawBody into your provider's SDK (like stripe.webhooks.constructEvent()) for verification. The raw buffer remains pristine, byte-perfect, and entirely unaffected by the JSON parsing process.

The Code Showdown (Side-by-Side Comparison)

Let's put both approaches side by side using a standard Stripe webhook integration. This is where the abstract architectural difference turns into an absolute night-and-day difference in production code.

Node.js

In Node.js, the Firebase Functions SDK gives you access to req.rawBody right out of the box. Notice how cleanly we handle both application data processing (req.body) and security verification (req.rawBody).

const { onRequest } = require("firebase-functions/v2/https");
const stripe = require("stripe")(process.env.STRIPE_SECRET_KEY);

exports.stripeWebhook = onRequest(async (req, res) => {
    const sig = req.headers["stripe-signature"];
    let event;

    try {
        // Node.js hands us the exact, unmutated buffer on a silver platter
        event = stripe.webhooks.constructEvent(req.rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET);
    } catch (err) {
        console.error(`❌ Webhook Signature Verification Failed: ${err.message}`);
        return res.status(400).send(`Webhook Error: ${err.message}`);
    }

    // Safe to use parsed JSON data down here seamlessly!
    if (event.type === "checkout.session.completed") {
        const session = event.data.object;
        // Fulfill the purchase...
    }

    res.status(200).json({ received: true });
});

Python

In Python Firebase Functions (v2), the underlying Flask/Werkzeug app eagerly parses the incoming stream if it sees Content-Type: application/json. Trying to access req.get_data() can throw errors or return empty bytes depending on the framework version's lifecycle parsing phase.

To safely bypass Werkzeug's eager consumption or formatting mutations, you often have to rely on raw fallback properties like req.environ or construct manual stream intercepts before the route logic runs:

from firebase_functions import https_fn
import stripe
import os

@https_fn.on_request()
def stripe_webhook(req: https_fn.Request) -> https_fn.Response:
    sig_header = req.headers.get("Stripe-Signature")

    # TRAP: If you call req.get_json() first, or if the runtime pre-parsed it,
    # req.get_data() can return empty or lose its original format byte-for-byte.
    try:
        # In modern Firebase-Python setups, you must access the low-level 
        # WSGI environment to reliably grab unparsed fallback data streams.
        wsgi_input = req.environ.get("wsgi.input")
        raw_body = req.get_data(cache=True) # Heavy reliance on manual framework caching flags

        event = stripe.Webhook.construct_event(
            raw_body, sig_header, os.environ.get("STRIPE_WEBHOOK_SECRET")
        )
    except Exception as e:
        print(f"❌ Webhook Signature Verification Failed: {str(e)}")
        return https_fn.Response(f"Webhook Error: {str(e)}", status=400)

    # Proceed with processing
    if event["type"] == "checkout.session.completed":
        session = event["data"]["object"]
        # Fulfill the purchase...

    return https_fn.Response("OK", status=200)

The Verdict

Node.js explicitly caches the stream into a separate variable (rawBody), freeing up the main object to parse freely.
Python forces you to explicitly configure caching flags or dip into low-level WSGI parameters (req.environ) to ensure the byte stream hasn't been modified or exhausted by the framework lifecycle.

Choosing Your Battles

At the end of the day, software architecture isn't about finding a single "perfect" language; it's about choosing the right tool for the specific job at hand.
When you are building a backend ecosystem on a platform like Firebase, you don't have to lock yourself into a single runtime. Cloud Functions are modular by design, meaning your AI services, heavy mathematical processing, and network I/O gateways can live side by side in completely different environments.

Final Thoughts

Let Node.js Handle the Gates: Node’s asynchronous architecture, event-driven design, and native request-caching mechanisms (req.rawBody) make it the undisputed king for handling edge network I/O. Use Node.js for raw HTTP endpoints, third-party webhook verification (Stripe, Shopify, Lemon Squeezy), authentication gatekeeping, and lightweight CRUD routing.
Save Python for the Heavy Lifting: Python’s true strength lies in its unmatched ecosystem for data processing, machine learning, semantic search vectoring, and complex algorithmic logic. Use Python Cloud Functions when you need to run heavy backend calculations, parse multi-dimensional arrays, interface with vector databases, or manipulate large datasets.

Room-Inspired Local Persistence in Swift: A Production GRDB Architecture

Hakim — Tue, 16 Jun 2026 09:22:42 +0000

Introduction

If you've built Android apps with Room, you already think in a layered persistence model: entities define your schema, DAOs handle queries, repositories abstract the data layer, and ViewModels stay completely ignorant of the database. It's clean, testable, and scalable.

When you cross to iOS and reach for local persistence, you hit a wall. Core Data is powerful but infamous for its boilerplate and threading pitfalls. SwiftData is promising but young. GRDB (a Swift SQLite toolkit) is arguably the best option available today: fast, type-safe, well-maintained, and built around Swift concurrency. However, it ships with no official architecture pattern. The documentation shows you the API but doesn't tell you how to structure a real app.

This tutorial fills that gap. We'll build a production-ready GRDB architecture from scratch, layer by layer, using the same mental model Room developers already know: entity → DAO → repository → ViewModel. By the end, your ViewModel will read and write data with a single async call, with no GRDB imports, no threading concerns, and no setup boilerplate at the call site.

Here's what we'll build:

A MyDataBase singleton that owns the connection and exposes all DAOs
A MyEntity that handles its own schema, migration, and non-primitive type encoding
A MyDao with clean reader/writer separation
A MyRepositoryImpl as the single data entry point
A ViewModel that calls the repository as if persistence doesn't exist

Setting Up the Database MyDatabase

The foundation of the entire architecture is a single file: MyDatabase.swift. This is the equivalent of Room's RoomDatabase subclass. It owns the connection, runs migrations, and exposes every DAO. Everything else in the stack depends on it.

Creating the database file

GRDB connects to SQLite through a DatabasePool—the right choice for any production app because it allows multiple concurrent reads while serializing writes. We point it at the app's Application Support directory, which is the correct location for user-generated data on iOS (it is not visible to the user and is backed up by iCloud by default).

struct MyDatabase {
  let writer: DatabaseWriter

  init(_ writer: DatabaseWriter) throws {
        self.writer = writer
        try migrator.migrate(writer)
   }

   var reader: DatabaseReader {
        writer
    }
}

Two things worth noting here. First, writer is typed as DatabaseWriter and reader as a DatabaseReader which are GRDB protocols, not concrete types. This matters for testing: you can swap DatabasePool for an in-memory DatabaseQueue without changing any downstream code. Second reader simply returns writer. DatabasePool conforms to both protocols, so this costs nothing while keeping the read/write intent explicit at every call site.

The shared singleton

extension MyDatabase {
   static let shared = createShared()

   static func createShared() -> MyDatabase {
     do {
         let fileManager = FileManager()
         let folder = try fileManager.url(
             for: .applicationSupportDirectory,
             in: .userDomainMask,
             appropriateFor: nil,
             create: true
          ).appendingPathComponent("database", isDirectory:true)

          try fileManager.createDirectory(at: folder, withIntermediateDirectories: true)
          let databaseURL = folder.appendingPathComponent("yourAppName.sqlite")
          let writer = try DatabasePool(path: databaseURL.path)
          return try MyDatabase(writer)
      }
      catch{
          fatalError(error.localizedDescription)
        }
   }
}

The fatalError on failure is intentional. If the database cannot be created at launch, the app has no recoverable state, failing loudly is the right call here, and it mirrors what Room does under the hood when misconfigured.

Registering the DAOs

Once the shared instance exists, DAOs are registered as static properties on MyDatabase itself:

extension MyDatabase {
    static let myDao = MyDao(
        reader: shared.reader,
        writer: shared.writer
    )
}

This means any layer of the app can access MyDatabase.myDao without passing the database instance around. We'll build the DAO itself in part 5. For now, think of these static properties as the switchboard that connects the database connection to every data access object in the app.

Defining an Entity MyEntity

In Room, an entity is a data class annotated with @Entity. GRDB's equivalent is a Swift struct that conforms to two protocols:FetchableRecord for reading rows from the database, and PersistableRecord for writing them back. Add Codable to get serialization for primitive fields.

struct MyEntity: Codable, FetchableRecord, PersistableRecord {
    let userId: String
    let rating: Double
    let photos: [String]
    let city: [String: String]

    static let databaseTableName = "MyEntity"

    static let persistenceConflictPolicy = PersistenceConflictPolicy(
        insert: .replace
    )
}

databaseTableName maps the struct to its SQLite table — GRDB's equivalent of Room's tableName parameter. persistenceConflictPolicy set to .replace means any insert on an existing primary key silently upserts rather than throwing. This is the right default for a cache that syncs from a remote source: you always want the latest data to win.

Type-safe column references

Rather than scattering raw string literals across queries, we declare columns once as a nested enum:

public enum Columns {
    static let userId = Column("userId")
    static let rating = Column("rating")
    static let photos = Column("photos")
    static let city = Column("city")
}

Column is a GRDB type that participates in the query builder. Referencing Columns.userId instead of "userId" everywhere means a rename is a single change.

Handling non-primitive types

This is where GRDB diverges from Room and requires explicit handling. SQLite has no native type for [String] or [Sting: String] everything must be stored as text, integer, real, or blob. Room handles this with @TypeConverter; GRDB leaves it to you.

The solution is to JSON-encode complex types on write and decode them on read:

extension MyEntity {
  static func encodeDictionary(_ dict: [String: String]) throws -> String {
        let data = try JSONEncoder().encode(dict)
        return String(data: data, encoding: .utf8) ?? "{}"
    }

  static func decodeDictionary(_ string: String) throws -> [String: String] {
        guard let data = string.data(using: .utf8) else { return [:] }
        return try JSONDecoder().decode([String: String].self, from: data)
    }

  static func encodeArray(_ array: [String]) throws -> String {
        let data = try JSONEncoder().encode(array)
        return String(data: data, encoding: .utf8) ?? "[]"
    }

  static func decodeArray(_ string: String) throws -> [String] {
        guard let data = string.data(using: .utf8) else { return [] }
        return try JSONDecoder().decode([String].self, from: data)
    }
}

These helpers are static on the entity itself, the same place Room developers would put a TypeConverter companion. They're called inside the two protocol methods that GRDB requires you to implement manually when your type has non-primitive fields.

Writing to the database encode(to:)

extension MyEntity {
  public func encode(to container: inout PersistenceContainer) throws {
  container[Columns.userId] = userId
  container[Columns.rating] = rating

  container[Columns.photos] = try MyEntity.encodeArray(photos)
  container[Columns.city] = try MyEntity.encodeDictionary(city) 
  }
}

Primitive fields are assigned directly. Non-primitive fields go through the encode helpers first. GRDB calls this method automatically on every write; you never call it yourself.

Reading from the database — init(row:)

extension MyEntity {
  public init(row: Row) throws {
    userId = row[Columns.userId]
    rating = row[Columns.rating]

        photos = try MyEntity.decodeArray(row[Columns.photos])
        city = try MyEntity.decodeDictionary(row[Columns.city])
  }
}

The mirror image of encode. GRDB calls this whenever it materializes a row into your type — fetchAll, fetchOne, anywhere. The decode helpers reverse exactly what encode wrote.

Owning the schema

The last piece is createTable, which lives as a static method on the entity itself:

static func createTable(_ db: Database) throws {
  try db.create(table: databaseTableName) { t in
    t.column(Columns.userId.name, .text).primaryKey()
    t.column(Columns.rating.name, .text).notNull()
    t.column(Columns.photos.name, .text).notNull()
    t.column(Columns.city.name, .text).notNull()
  }
}

Keeping createTable on the entity means the schema definition and the type that represents it live in the same file. When you add a column, you update the struct, the Columns enum, the encode/decode methods, and the table definition all in one place — the same discipline Room enforces through its annotation processor.

Migrations — DatabaseMigrator

In Room, migrations are defined as Migration objects passed to the database builder. GRDB's equivalent is DatabaseMigrator — a value type you configure with named migration blocks, then run against the database connection. The key property that makes it production-safe is that each migration runs exactly once, identified by its name. GRDB tracks which migrations have already been applied and skips them on subsequent launches.

We add the migrator as a computed property on MyDatabase:

extension MyDatabase {
  var migrator: DatabaseMigrator {
    var migrator = DatabaseMigrator()

    #if DEBUG
    migrator.eraseDatabaseOnSchemaChange = true
    #endif

    migrator.registerMigration("v1") { db in
     try MyEntity.createTable(db)

    }
    return migrator

  }
}

This is called in the MyDatabase initializer we wrote in part 2:

init(_ writer: DatabaseWriter) throws {
    self.writer = writer
    try migrator.migrate(writer)
}

So by the time MyDatabase.shared is ready, the schema is guaranteed to exist.

Adding future migrations

When your schema needs to change after shipping, you register a new named block alongside the existing one:

migrator.registerMigration("v1") { db in
    // original schema — never touch this
}

migrator.registerMigration("v2") { db in
    try db.alter(table: "MyEntity") { t in
        t.add(column: "age", .text)
    }
}

The names are the contract. GRDB stores them in a internal grdb_migrations table and uses them to determine what has and hasn't run. Renaming a migration that has already shipped is the same as deleting it — GRDB will try to run it again on existing installs and likely fail. Treat migration names as append-only.

The DAO Layer — MyDao

In Room, a DAO is an interface annotated with @Dao — Room generates the implementation for you at compile time. In GRDB there's no code generation, so the DAO is a plain Swift class you write yourself. The pattern is the same: one class, one entity, all database access for that entity goes through it and nowhere else.

Constructor injection of reader and writer

class MyDao {
    private let reader: DatabaseReader
    private let writer: DatabaseWriter

    init(reader: DatabaseReader, writer: DatabaseWriter) {
        self.reader = reader
        self.writer = writer
    }
}

This is the most important structural decision in the DAO. By accepting DatabaseReader and DatabaseWriter as protocols rather than a concrete DatabasePool, the DAO is completely decoupled from the database setup. In tests you pass an in-memory DatabaseQueue; in production you pass the shared DatabasePool. The DAO itself never knows the difference.

The separation also enforces intent at every method signature. If a method takes only reader, it provably cannot write. If it takes only writer, it provably cannot run a read on the wrong connection. This is the threading discipline GRDB is designed around.

Read operations

func getSingleUser(_ userId: String) async throws -> MyEntity? {
    return try await reader.read { db in
        try MyEntity.fetchOne(db, sql: "SELECT * FROM MyEntity WHERE userId = ?", arguments: [userId])
    }
}

func getAllAvailableUsers() async throws -> [MyEntity] {
    return try await reader.read { db in
        try MyEntity.fetchAll(db)
    }
}

reader.read schedules the closure on GRDB's internal reader queue — concurrent with other reads, never blocking writes. The async/await surface means the call site looks like any other async Swift function. There are no completion handlers, no DispatchQueue juggling, no @escaping closures to reason about.

fetchOne returns an optional — nil if no row matches. fetchAll returns an empty array if the table is empty. Neither throws on an empty result, only on a genuine database error. That distinction matters when you're deciding whether to show an empty state or an error state in the UI.

Write operations

func insertUsers(_ usersList: [MyEntity]) async throws {
    try await writer.write { db in
        for user in usersList {
            try user.save(db, onConflict: .replace)
        }
    }
}

func deleteAllUsers() async throws {
    try await writer.write { db in
        try MyEntity.deleteAll(db)
    }
}

func updateUsers(_ usersList: [MyEntity]) async throws {
    try await writer.write { db in
        try MyEntity.deleteAll(db)
        for user in usersList {
            try user.save(db, onConflict: .replace)
        }
    }
}

writer.write serializes the closure — only one write runs at a time, always. Everything inside a single write block is an atomic transaction: if any operation throws, the entire block rolls back automatically. This is why updateUsers deletes all rows and reinserts in the same block — either both operations succeed together or neither does. You never end up with a half-replaced dataset.

save(onConflict: .replace) is a per-call override that works alongside the entity-level persistenceConflictPolicy we set in part 3. They do the same thing here — but spelling it out at the call site makes the intent explicit to anyone reading the DAO later.

Registering the DAO on MyDatabase

Back in MyDatabase, we wire everything together:

extension MyDatabase {
    static let myDao = MyDao(
        reader: shared.reader,
        writer: shared.writer
    )
}

From this point forward, nothing in the app ever instantiates MyDao directly or touches a DatabaseReader or DatabaseWriter outside of this file. The DAO is the last layer that knows GRDB exists.

The pattern is identical for every other entity — UserDao, ChatDao, FilterDao, AnyDao — same constructor, same reader/writer split, same async throws surface. That's the payoff of the architecture: adding a new entity is mechanical.

The Repository Layer — MyRepositoryImpl

If the DAO is the last layer that knows GRDB exists, the repository is the first layer that doesn't. Its job is simple: receive calls from the ViewModel, delegate to the DAO, and return results. No database logic, no SQL, no GRDB imports visible to anything above it.

class MyRepositoryImpl {
    private let myDao: MyDao

    init(db: MyDatabase = .shared) {
        self.myDao = MyDatabase.myDao
    }
}

The default argument db: MyDatabase = .shared means the ViewModel can instantiate the repository with no arguments in production, while tests can pass an alternative database instance. The repository itself never holds a reference to the database — only to the DAO it needs.

Delegating reads

func getSingleUser(userId: String) async throws -> MyEntity? {
    return try await myDao.getSingleUser(userId)
}

func getAllAvailableUsers() async throws -> [MyEntity] {
    return try await myDao.getAllAvailableUsers()
}

These are pure pass-throughs and that's intentional. The repository's value isn't in transforming data at this layer — it's in being the seam where you could add caching, logging, or remote fallback later without the ViewModel ever knowing. Today it delegates; tomorrow it could check a remote source first and fall back to local. The ViewModel call site doesn't change either way.

Delegating writes

func replaceUsers(usersList: [MyEntity]) async throws {
    try await myDao.updateUsers(usersList)
}

func insertUsers(usersList: [MyEntity]) async throws {
    try await myDao.insertUsers(usersList)
}

func deleteAllUsers() async throws {
    try await myDao.deleteAllUsers()
}

Notice the method names are business-language rather than database-language. The ViewModel calls replaceUsers — it doesn't need to know that "replace" means delete-all then reinsert inside an atomic write block. That translation lives in the DAO. The repository just gives it a name the rest of the app can reason about.

Error handling strategy

Every method here is async throws. The repository does not swallow errors — it lets them propagate up to the ViewModel, which is the right place to decide what to show the user. The one exception is methods where a missing result is a valid state rather than an error:

func getAllUsers() async -> [MyEntity]? {
    do {
        return try await myDao.getAllAvailableUsers()
    } catch {
        return nil
    }
}

This is a deliberate choice — returning nil here signals "something went wrong, show nothing" without forcing the ViewModel into a catch block for a non-critical read. Use it sparingly. For anything where the error should change UI state, let it throw.

Wiring to a ViewModel

This is where the architecture pays off. The ViewModel sits at the top of the stack and knows nothing below the repository. No GRDB imports, no database references, no threading setup. Just an async call and a state update.

The ViewModel

@MainActor
class MyViewModel: ObservableObject {
    @Published var user: MyEntity?
    @Published var isLoading: Bool = false
    @Published var error: Error?

    private let userId: String
    private let myRepository: MyRepositoryImpl

    init(
        userId: String,
        myRepository: MyRepositoryImpl = MyRepositoryImpl()
    ) {
        self.userId = userId
        self.myRepository = myRepository
    }
}

@MainActor is the key annotation here. It guarantees every property update happens on the main thread automatically — no DispatchQueue.main.async wrappers, no await MainActor.run blocks scattered through the code. Swift enforces this at compile time. Combined with @Published, any state change the ViewModel makes is immediately safe to consume in a SwiftUI view.

The repository has a default argument in the initializer — in production SwiftUI previews and the app itself pass nothing, in tests you inject a repository backed by an in-memory database.

Reading data

extension MyViewModel {
    func fetchUser() async {
        isLoading = true
        defer { isLoading = false }
        do {
            user = try await myRepository.getSingleUser(
                userId: userId
            )
        } catch {
            self.error = error
        }
    }

    func fetchAllusers() async -> [MyEntity] {
        do {
            return try await myRepository.getAllAvailableUsers()
        } catch {
            self.error = error
            return []
        }
    }
}

Writing data

extension MyViewModel {
    func saveUsers(_ users: [MyEntity]) async {
        do {
            try await myRepository.replaceUsers(usersList: users)
        } catch {
            self.error = error
        }
    }

    func clearUsers() async {
        do {
            try await myRepository.deleteAllUsers()
            user = nil
        } catch {
            self.error = error
        }
    }
}

Consuming in a SwiftUI view

struct MyView: View {
    @StateObject var viewModel: MyViewModel

    var body: some View {
        Group {
            if viewModel.isLoading {
                ProgressView()
            } else if let user = viewModel.user {
                VStack(alignment: .leading) {
                    Text(user.userId)
                        .font(.headline)
                }
            } else {
                Text("No user found")
            }
        }
        .onAppear{
            Task{ await viewModel.fetchUser() }
        }
    }
}

Wrapping Up

Each layer has exactly one job and depends only on the layer below it. Adding a new entity means creating a new Entity, Dao, and RepositoryImpl following the same pattern — the rest of the stack stays untouched.

If you've built with Room on Android, this architecture will feel familiar. The layers and the separation of concerns translate naturally across platforms — GRDB gives you the same discipline, just in Swift.

Injecting WorkManager into ViewModels with Dagger Hilt. No Context, No Boilerplate, Always a WorkQuery Back

Hakim — Wed, 10 Jun 2026 09:13:00 +0000

WorkManager is the right tool for deferrable, guaranteed background work in Android. But the default setup pushes you toward boilerplate fast: you end up calling WorkManager.getInstance(context) inside ViewModels, passing Context where it doesn't belong, re-registering observers scattered across the codebase, and getting no consistent way to query the state of your enqueued work.

This tutorial shows how to build a clean, injectable WorkManagerHandler using Dagger Hilt, a single interface that any ViewModel can receive through constructor injection, with zero Context and a guaranteed WorkQuery callback on every call so you always know what to observe.

By the end, you'll have:

A WorkManager singleton provided through Hilt
A custom Configuration.Provider that plugs Hilt's HiltWorkerFactory into WorkManager at initialization
A WorkManagerHandler interface with a WorkManagerHandlerImpl that encapsulates enqueueing, chaining, and query registration
ViewModels that declare WorkManagerHandler as a plain constructor dependency

The pattern scales cleanly as you add workers: each new worker is one method on the handler, and the ViewModel never knows or cares how work is scheduled underneath.

Prerequisites: familiarity with Dagger Hilt basics, Jetpack WorkManager fundamentals, and Kotlin coroutines. A working Android project with Hilt already configured is assumed.

Part 1: Application Setup and Custom Configuration.Provider

By default, WorkManager initializes itself automatically using its own internal factory. The problem is that Hilt-injected workers need Hilt's factory HiltWorkerFactory to resolve their @Inject constructor dependencies. If you let WorkManager self-initialize, your workers won't have access to any of your Hilt bindings.

The fix is to disable auto-initialization and take manual control via Configuration.Provider and AndroidManifest.xml

1. Disable auto-initialization

In your AndroidManifest.xml, remove WorkManager's default initializer:

<application ...>

    <provider
        android:name="androidx.startup.InitializationProvider"
        android:authorities="${applicationId}.androidx-startup"
        android:exported="false"
        tools:node="merge">
        <meta-data
            android:name="androidx.work.WorkManagerInitializer"
            android:value="androidx.startup"
            tools:node="remove" />
    </provider>

</application>

This tells Jetpack Startup to skip the default WorkManager setup so you can wire it yourself.

2. Implement Configuration.Provider in your Application class

@HiltAndroidApp
class CustomApp : Application(), Configuration.Provider {

    @Inject
    lateinit var workerFactory: HiltWorkerFactory

    override fun onCreate() {
        super.onCreate()
        WorkManager.initialize(this, workManagerConfiguration)
    }

    override val workManagerConfiguration: Configuration
        get() = Configuration.Builder()
            .setWorkerFactory(workerFactory)
            .build()
}

A few things worth noting here:

@HiltAndroidApptriggers Hilt's code generation and makes the Application class an injection entry point, this is what makes @Inject lateinit var workerFactory work.
HiltWorkerFactory is Hilt's bridge into WorkManager. When WorkManager instantiates a worker, it will use this factory, which knows how to satisfy @Inject
We call WorkManager.initialize() manually in onCreate(), after Hilt has performed field injection, which means workerFactory is guaranteed to be non-null by the time it's used.

Why this matters for the rest of the tutorial
Without this setup, any @AssistedInject or @Inject constructor in a worker class will silently fail at runtime, WorkManager will either crash or fall back to a no-arg constructor it can't find. Getting this right first means everything built on top of it will actually work.

Part 2: Providing the WorkManager Singleton and Writing Your First CoroutineWorker

With the Application class wired up, the next step is making the WorkManager instance available across the app through Hilt, and writing a worker that can actually receive injected dependencies.

1. Provide the WorkManager singleton
In your Hilt module, add a @Provides binding for WorkManager:

@Module
@InstallIn(SingletonComponent::class)
object WorkManagerModule {

    @Provides
    @Singleton
    fun provideWorkManagerInstance(
        @ApplicationContext context: Context
    ): WorkManager = WorkManager.getInstance(context)
}

A few things to note:

@Singleton ensures the entire app shares one WorkManager instance, this is important because WorkManager itself is a singleton under the hood, and wrapping it consistently avoids subtle state mismatches.
@ApplicationContext is a Hilt built-in qualifier. It gives you the application'Context without you having to pass it manually anywhere. This is the last time Context appears directly in this tutorial.
This binding is what gets injected into WorkManagerHandlerImpl later. The ViewModel never touches WorkManager directly. 2. Write your first CoroutineWorker with Hilt injection A regular Worker subclass can't receive Hilt injections through a normal @Inject constructor because WorkManager controls instantiation. The solution is @HiltWorker combined with @AssistedInject:

@HiltWorker
class YourWorker @AssistedInject constructor(
    @Assisted context: Context,
    @Assisted workerParams: WorkerParameters,
    private val someDependency: SomeDependency  // injected by Hilt
) : CoroutineWorker(context, workerParams) {

    override suspend fun doWork(): Result = coroutineScope {
        //Do some work
        Result.success()
    }
}

Breaking this down:

@HiltWorker marks the class so Hilt's code generator knows to produce a factory for it. Without this, HiltWorkerFactory won't know the worker exists.
@AssistedInject is used because WorkManager must provide context and workerParams at runtime;Hilt can't know those at compile time. @Assisted marks those two parameters as runtime-provided; everything else (someDependency) is resolved from the Hilt graph normally.

The worker is ready. The singleton is in the graph. Next we build the interface that ViewModels will actually talk to.

Part 3: The WorkManagerHandler Interface and Its Implementation

This is the core of the pattern. Instead of ViewModels calling WorkManager directly, they talk to a WorkManagerHandler interface. The implementation handles enqueueing, chaining, and always hands a WorkQuery back so the caller knows exactly what to observe.

1. Define the interface

interface WorkManagerHandler {

    fun initializeYourWorker(
        inputData: Data,
        workQuery: (WorkQuery) -> Unit
    )
    fun observeWorkInfo(workQuery: WorkQuery): Flow<List<WorkInfo>>

}

A few design decisions worth calling out:

Every method takes a workQuery: (WorkQuery) -> Unit callback. This is the contract: you will always get a WorkQuery back, no matter which worker you trigger. The ViewModel uses it to observe work state without knowing anything about IDs or tags internally.
Data is WorkManager's key-value input container. Keeping it as the parameter type rather than raw primitives means the handler stays agnostic, it doesn't need to know what the data means, only that it gets passed into the worker.
The interface has no Context, no WorkManager, no lifecycle references. It is a pure behavioral contract.

2. Implement the interface

class WorkManagerHandlerImpl @Inject constructor(
    private val workManager: WorkManager
) : WorkManagerHandler {

    override fun initializeFiltersWorker(
        inputData: Data,
        workQuery: (WorkQuery) -> Unit
    ) {
        val request = OneTimeWorkRequestBuilder<YourWorker>()
            .setInputData(inputData)
            .build()

        workManager.enqueue(request)

        val query = WorkQuery.fromIds(mutableListOf(request.id))
        workQuery(query)
    }

    override fun observeWorkInfo(workQuery: WorkQuery): Flow<List<WorkInfo>> {
    return workManager.getWorkInfosFlow(workQuery)
}
}

Breaking this down:

@Inject constructor with WorkManager as the only parameter, Hilt resolves this from the singleton we provided in Part 2. No Context needed anywhere here.
WorkQuery.fromIds() is built immediately after enqueueing, before the callback fires. This means the ViewModel receives the query in the same call stack as the enqueue, there is no race window where work is running but unobservable.

3. Bind the implementation in your Hilt module

The interface and implementation need to be connected. Add an abstract binding to your module:

@Module
@InstallIn(SingletonComponent::class)
abstract class WorkManagerBindingsModule {

    @Binds
    @Singleton
    abstract fun bindWorkManagerHandler(
        impl: WorkManagerHandlerImpl
    ): WorkManagerHandler
}

Note that @Binds requires an abstract function in an abstract module, it cannot live in the same object as @Provides functions. If your existing module is an object, either convert it to an abstract class or create a separate module as shown above. Both approaches are valid.

The handler is fully wired into the Hilt graph. Any class that declares WorkManagerHandler in its constructor will get a fully functional implementation injected with no setup, no context, no boilerplate.

Part 4: Injecting into a ViewModel and Observing Work State

This is where the pattern pays off. The ViewModel declares WorkManagerHandler as a plain constructor dependency, triggers work through it, and observes the returned WorkQuery all without touching Context,WorkManager, or any lifecycle plumbing directly.

1. Inject the handler into a ViewModel

@HiltViewModel
class MyViewModel @Inject constructor(
    private val workManagerHandler: WorkManagerHandler
) : ViewModel() {

    private val _workState = MutableStateFlow<WorkInfo?>(null)
    val workState: StateFlow<WorkInfo?> = _workState.asStateFlow()

    fun fetchData(dataType: String) {
        val inputData = workDataOf(
            DATA_KEY to dataType
        )

        workManagerHandler.initializeYourWorker(inputData) { workQuery ->
            observeWork(workQuery)
        }
    }
    private fun observeWork(workQuery: WorkQuery) {
    viewModelScope.launch {
        workManagerHandler
            .observeWorkInfo(workQuery)
            .collect { workInfoList ->
                _workState.value = workInfoList.firstOrNull()
            }
    }
}
}

One note:
The WorkQuery that comes back from the handler callback is immediately handed to observeWork(). Because the query is built right after enqueue inside the handler (as we saw in Part 3), by the time observeWork() runs the work is already enqueued and observable.

2. Observe work state in your Composable

@Composable
fun MyScreen(
    viewModel: MyViewModel = hiltViewModel()
) {
    val workState by viewModel.workState.collectAsStateWithLifecycle()

    LaunchedEffect(Unit) {
        viewModel.fetchData("category_data")
    }

    when (workState?.state) {
        WorkInfo.State.ENQUEUED,
        WorkInfo.State.RUNNING -> {
            CircularProgressIndicator()
        }
        WorkInfo.State.SUCCEEDED -> {
            // render results
        }
        WorkInfo.State.FAILED,
        WorkInfo.State.CANCELLED -> {
            // show error state
        }
        else -> Unit
    }
}

Common mistakes to avoid
Calling WorkManager.getInstance() directly in a ViewModel. This bypasses the injected singleton and can produce a second instance if auto-initialization wasn't properly disabled. Always inject WorkManagerHandler and let the handler own the WorkManager reference.

Forgetting tools:node="remove" in the manifest. If the default initializer is still active, WorkManager self-initializes before HiltWorkerFactory is ready. Workers will fail to instantiate any @Inject dependencies silently.

Using @Inject instead of @AssistedInject in a worker. WorkManager provides context and workerParams at runtime, Hilt cannot know them at compile time. Without @AssistedInject and @Assisted, the worker constructor will either fail to compile or crash at runtime.

Building WorkQuery before calling enqueue(). The request ID exists as soon as the request object is built, but the work isn't registered with WorkManager until after enqueue(). Always build the query after the enqueue call to guarantee the work is observable immediately.

Swapping WorkManagerHandler and WorkManagerHandlerImpl or assuming it's the same in the @Binds declaration. This is one of the most common Hilt mistakes and the error message does not always make it obvious. The rule is: the return type is the interface, the parameter is the implementation — not the other way around.

// WRONG — will fail to compile or inject incorrectly
@Binds
@Singleton
abstract fun bindWorkManagerHandler(
    impl: WorkManagerHandler         // ❌ interface as parameter
): WorkManagerHandlerImpl            // ❌ implementation as return type

Or:

@Binds
@Singleton
abstract fun bindWorkManagerHandler(
    impl: WorkManagerHandlerImpl         // ❌ implementation as return type
): WorkManagerHandlerImpl            // ❌ implementation as return type


// CORRECT
@Binds
@Singleton
abstract fun bindWorkManagerHandler(
    impl: WorkManagerHandlerImpl     // ✅ concrete class Hilt knows how to build
): WorkManagerHandler                // ✅ the type the rest of the graph asks for

Wrapping up

The pattern covered in this tutorial gives you:

A single WorkManagerHandler interface that any ViewModel can receive with no setup cost
Workers that participate fully in the Hilt dependency graph via @HiltWorker and @AssistedInject
A guaranteed WorkQuery on every enqueue so the UI always has something to observe
The ability to add as many workers as you want.

The boundary between WorkManager and the rest of your app is now the WorkManagerHandler interface, which means it is also the boundary you can mock in tests.