DEV Community: Mxolisi Masuku

Can Claude Skills Save Us From The Smartphone?

Mxolisi Masuku — Fri, 01 May 2026 07:18:21 +0000

I have grown to hate the smartphone.

It's a glorious piece of tech. But it's a trap built around usefulness.

At 2 AM, I wake up and reach for my phone. I know it's not healthy but I do it out of necessity. I work with people in different timezones. Overnight, decisions get made, messages arrive, deadlines shift. If I don’t check, I risk missing something that matters.

So I check: Email. WhatsApp. Slack. iMessage. LinkedIn.

Somewhere between those apps, the boundary breaks. I find myself no longer checking for important things but consuming whatever shows up next. By the time I stop, I’ve lost time and some tokens of my attention.

This is the real problem with the smartphone:

==The important messages arrive through the same channel as the distractions.==

Your client’s message, your mother’s greeting, and a notification from a social media app all compete in the same space, with the same priority. Unfortunately, the apps that win are the ones engineered to interrupt, not the ones that matter.

You check your phone because the environment you are operating on is designed that way. You are not addicted to your phone. Checking is the only reliable way to not miss something important. Everything else follows from that.

For the first time I broke that cycle. I woke up at 2 AM and didn't touch my phone.

A few days earlier, I built a Claude skill called tomorrow.

Before bed, it pulls my Google Calendar, scans emails from the last 36 hours for anything that requires action the next day, and checks Slack and iMessage for messages that signal requests, deadlines, or decisions. Everything runs through a set of rules I defined.

The output is a clean and prioritized rundown of the next day. It is designed to be easy to read and scan through.

I run it before sleeping. When I wake up, I already know what my day is going to look like. I ran another skill today just to be sure after all my morning preps.

There was no reason to open all those other apps on the phone. I made coffee and started working.

I solved part of the "alert fatigue" problem in my first week with Claude Skills. 1 command doing the work of 6 apps.

From what I can see, we can save ourselves from mindless smartphone consumption once we start applying AI skills as filters and guardians for our attention. This idea isn't new. It's been discussed in research and is currently being applied by other builders across multiple fields. This is my account of how it played out for me.

What skills actually change

A Claude skill is just a folder with instructions and code. You ask Claude to do something, it loads the relevant skill, runs it, and gives you an answer. Nothing magical about the technology.

What matters is the direction of the interaction. With a phone, information comes to you and you sort it. With a skill, you go to the information and it comes back already sorted. The phone is push. The skill is pull.

My tomorrow skill replaces the morning email, calendar, Slack, and iMessage check. I built today, a midday rundown so I don’t open Slack just to see what I’ve missed. deadline handles scheduling without opening Google Calendar or the reminders app. Next is a notification filter that surfaces only actionable items from LinkedIn and email and drops the rest. After that, scheduled email drafting and more complex tasks.

Each skill replaces one reason to pick up the phone.

However, I still need the phone for music, messaging and for the camera. But the involuntary uses, the checks, the just-in-cases will start to fall away. Picking up the phone will eventually become a deliberate act. Something I do for pleasure because the important things have already been handled.

The real shift here isn't necessarily killing the smartphone but cutting the relationship where it owns your attention by default and you fight to get it back.

Why this is different from "just use less screen time or use different notifications."

I've tried screen-time apps. Greyscale mode. App blockers etc.

They all fail because they treat the symptom which is checking your phone frequently. You check apps on your phone because it's the only way to not miss things. The impulse to open and check the phone will go away the moment we remove the uncertainty around the alerts and notifications they bring. Good systems make the right behaviour cheap and the wrong behaviour expensive.

...But you still need your phone don't you? ...and other gotchas

Yes.

Skills run on a phone too.

I can trigger tomorrow and deadline skills from the Claude app on my Android. I'm not escaping the phone. I'm changing what I do on it. There is the phone-as-tool and the phone-as-an-attention-sinkhole . These are two different things that share the same hardware.

Skills are limited because they only work if you build them with the right context for your needs. Most people won't. The barrier is somewhere between users who know what a markdown file is and users who can write basic instructions. There is no coding involved for entry level skills, but a barrier does exist. Until that barrier drops, skills will be a tool for people already inclined to build their way out of problems.

Secondly, the model could change. APIs break. Permissions change. Anthropic could deprecate skills. The economics on AI could shift (tokens are already getting expensive). I'm not betting on this specific implementation.

Another flaw is the issue latency vs urgency tradeoffs. If you decide to get rid of real time notifications for a sweeping 3 hour skill or agent run, there is a possibility of seeing a notification 2 hours too late.

I'm betting on the pattern of intentional pull-based AI tools that replace specific reasons to grab a phone. If Claude skills aren't the thing that wins, something shaped like them will.

The Future That IBM Saw in 2020:

We are not yet at the point of deleting apps from our smartphones for good. But if one skill can replace the need to open 6 apps then half the battle is one. History has taught us that convenient tech always wins! Maybe the app can be replaced once trust issues around AI are addressed.

In 2020, researchers at IBM published a paper proposing exactly this kind of system: an intelligent notification framework that sits between you and your apps.

It learns which alerts to issue, which to suppress, and which to batch together for later. Their framework classified alerts by severity, modelled user behaviour, preferences and availability. They called it a "snooze-less" system. The goal was to eliminate the need to snooze or ignore notifications entirely. If the system does its job, every notification you see is one that deserves your attention at that moment.

The paper was ahead of its time. In 2020 the infrastructure to build this didn't exist for individuals. You needed enterprise backends, custom ML pipelines, dedicated integration work. In 2026, a Claude skill connected to Gmail and Calendar via MCP does roughly the same thing from a markdown file on your laptop. The gap between research prototype and personal tool collapsed in six years. There is further research being done on why companies should now build notifications for both users and AI Agents.

The IBM paper also hints at a future that goes further than filtering.

If an AI agent can reliably read, classify, and act on your notifications, you don’t need the app at all. You need the protocol: the underlying rules and interfaces that define how messages are sent, received, and interpreted.

Email already works this way. Slack exposes this through its API. WhatsApp is a bit tricky, and the security model there makes direct access harder, but that’s a separate problem. The point is: the app was always just a frontend for a communication channel. If your AI agent can interface with that channel directly, the app becomes optional. Not today. But the architecture is already pointing there.

That's the future I find most compelling is where AI replaces the entire app layer to talk directly to the systems underneath. We will stop interacting with interfaces designed to capture our attention and start interacting with an agent designed to protect it.

What I'm actually claiming

The notification-driven model of computing is a historical accident, not a permanent condition. It won because attention was the cheapest thing to monetise on a small screen with constant connectivity. It will lose to anything that lets us get signal without noise.

Maybe Claude skills are an early primitive version of that anything. They're not pretty. They require setup. The ecosystem is young. There is a lot of push-and-pull. But they're the first tool I've used that actually changes the math of why I pick up my phone.

With the right tools this is how App Independence can be attained:

Step one: Build a scheduled digest skill that pulls Gmail and Slack, iMessage every few hours and filters for what actually needs me.

Step two: Turn off notifications from those apps on my phone.

Step three: Live with that for two weeks and see what falls through.

Step four: If nothing falls through, stop opening the apps entirely.

Step five: Maybe a month out: delete them.

Thanks for reading

All Claude skills referenced in this article are published and maintained here:

Firestore Architecture For Scaling Read-Intensive Multi-Tenant Software

Mxolisi Masuku — Sat, 25 Apr 2026 21:22:57 +0000

When you research how to build a multi-tenant SaaS on Firestore, most articles stop at one idea: put a tenantId field on every document. That's true, but it's the easy half. The more tricky question is how do you arrange your collections so that reads, writes, and costs stay within budget as the business scales.

Background

I was afraid of creating a system that was more trouble and expensive than it was worth.

I built a multi-tenant SaaS Trogern for managing informal taxi businesses in Zimbabwe. I was the first tenant. The industry here is so volatile and unpredictable that instant record retrieval and logging is key for business operations. In the process I got obsessed with designing a database that wouldn't generate reads and writes which I couldn't manage.

For most people, this is not a problem you need to solve today. Firestore is dirt cheap. The free tier gives you 50,000 reads and 20,000 writes per day.

The two axes of scale on Firestore

Multi-tenant load doesn't scale along one line, it scales along two. Deep and Wide.

Deep scale. One tenant with a lot of data. This can be something like one taxi company, 100 vehicles, 100 drivers, 20,000 income logs per quarter. The stress falls on one partition.

Wide scale. Many tenants with small amounts of data. 1,000 companies, each with 10 vehicles, all opening their dashboards at 9am Monday morning. The stress falls on global indexes, listeners, and cold-start reads.

Deep scaling breaks different things than wide scaling. The same data model can be great at one and awful at the other. For this reason you will find that most documentation, including Firebase official docs, do not recommend a one-size-fits all best practice for Firestore database design.

I'm using deep and wide for the rest of the article because vertical and horizontal are already taken by infrastructure vocabulary and they mean roughly the opposite of what you'd guess here.

What flat collections look like

Firestore supports subcollections — collections nested inside a document. For a fleet app you could do:

companies/{companyId}/
  vehicles/{vehicleId}/
    incomeLogs/{logId}

A flat layout goes the other way. One top-level collection per business entity.

companies/{companyId}
vehicles/{vehicleId}       // field: companyId
drivers/{driverId}         // field: companyId
income/{logId}             // fields: companyId, vehicleId, driverId

Each document carries companyId as a partition field or shared key. The document id is the primary key, usually auto-generated or a natural one like a plate number. The document also carries the other foreign keys it'll be queried against — vehicleId, driverId . This is to ensure that one query can pull income for a specific driver in a specific vehicle at a specific company.

The case for flat collections

Note: Firestore charges per document read, not per path depth. A nested lookup for one vehicle's income is one query, and it's just as cheap as a flat one.

The real reasons to go flat in a multi-tenant app are these:

Cross-tenant admin queries. When you have a multi-tenant system, you become a platform manager and you will need to read across tenants. In a nested layout that requires a collection group query.. They are a Firestore query that operates across every subcollection of the same name. Collection groups work, but they demand more composite indexes and security-rule semantics. I wanted to avoid them.
Simpler security rules. All you have to do when checking a company out is "match on the companyId field" which covers every collection. A nested layout makes you write path-matching rules that are more complex and easier to get wrong.
Listener scoping. Now we look at onSnapshot, Firestore's real-time listener. It is a live socket that bills one read per doc that flows through it. On a flat collection that's one query: collection("income").where("companyId", "==", X).where("driverId", "==", Y).onSnapshot(...). One socket, one cleanup, identical shape no matter what you're watching.
On subcollections the path is the scope. Watching one driver across 100 vehicles means either a collection group query (new index, new rule path, you've given back the benefit you went nested for) or 100 parallel listeners merged client-side. A real dashboard opens four or five of these and flat collections keep every one uniform. Nested collections however, give you a different path depth per concern, plus deduplication logic and 100× the cleanup callbacks. That's where the bill blows up. A single leaked listener in flat collections is one socket pulling extra reads, but a leaked listener over many subcollections could be dozens of sockets which all silent until the bill comes.
Aggregation queries. count, sum, and avg are priced per 1,000 index entries (1 read per 1,000). They run cleanly on a flat collection. They work on subcollections too, but you run them per parent. This is fine for one tenant, painful for a platform-wide report.
Data migration and correction. You can fix a bug like a wrong driverName on a week of income logs or a missing field across half the catalog with one query where("companyId", "==", X).where("cashDate", ">=", date) in a flat system. In a nested layout that same fix is a recursive walk down every company → vehicle → income path. This happens way more often than the architecture diagrams imply.

The one-query demonstration

With a flat layout, pulling income for a driver in a vehicle for a company is one call:

db.collection("income")
  .where("companyId", "==", "trogern-01")
  .where("vehicleId", "==", "ADB-121-GP")
  .where("driverId", "==", "DRV-8421")
  .orderBy("cashDate", "desc")
  .limit(50)
  .get();

Fine. That's cheap for one request. Now 1,000 tenants do it at the same time. Now each of those 1,000 tenants has a dashboard that runs three queries like this on page load and opens a real-time listener on notifications. Now half of them have 100 vehicles each, not 10.

That's when things get interesting.

Two ways to read: per-log vs rollup

Once a flat layout is in place, the next decision is how much work each dashboard load does. There are two patterns. The simulator below toggles between them, so it's worth defining them now.

Per-log. The obvious one. Every dashboard load runs a query against income and reads back every raw log in the window. 90-day quarterly view, 200 logs/day → 18,000 reads per load, per user. Simple, always correct, no extra moving parts.

Daily rollup. Every write to income also writes (or increments) a document in dailyRollups/{companyId}_{date} with the summed amount and a count. The dashboard reads 90 of those instead of thousands of raw logs. A Cloud Function fans the writes.

Aside: Cloud Functions aren't free either. Every income log triggers one invocation, and 2nd-gen functions bill at $0.40 per million invocations past the 2M free tier, plus compute time (GB-seconds and GHz-seconds) and any egress. For an app which does 200 logs/day across a big tenant, or 20/day across 1,000 small ones. That's roughly 6M invocations/month at the top end, around $1.60 in invocation fees plus a few dollars of compute. The rollup still wins by orders of magnitude on the read side, but the trade isn't quite "two docs written for free." Watch the function bill if your write volume is high — it's the next thing that bites once you've fixed reads.

dailyRollups/
  trogern-01_2026-04-25
    { companyId, date, totalIncome, totalExpense, logCount, ... }

You pay a little more on the write path (two docs per income log instead of one) and you save 20× to 200× on reads. For a read-heavy dashboard app, that trade is one-sided.

The downside: any historical correction requires recomputing the rollup. That's a Cloud Function with a retry queue, not a one-liner. It's the kind of debt you have to decide to take.

The simulator

I built this initially with my defaults, but every input is editable. Move the tenant slider, flip the architecture, watch the cost.

Interactive
Open the Firestore Cost Simulator →
Plug in your tenant profile and compare per-log vs rollup architecture costs.

The math is: each dashboard load fans out into a handful of reads. There is one big query for the income window, plus the surrounding lists, notifications and security-rule lookups. Multiplied by users, by loads per day, by 30 days, by tenants. Priced at $0.06 per 100K reads.

A dashboard load fans out roughly like this (numbers lifted from my actual controller code):

What	Reads per load (per-log)
Income, 90-day period stats	`logsPerDay × 90`
Drivers list	`vehicles`
Vehicles list	`vehicles`
Active target	1
Notifications initial fetch	50
Security-rule `get(/users/{uid})` per protected query	~6

For a small tenant (10 vehicles, 20 logs/day) the per-log total is 1,877 reads per load. For a big tenant (100 vehicles, 200 logs/day) it's 18,257. The income window dominates — everything else is rounding error.

Here's the underlying function the widget runs, in about 25 lines:

type Tenant = { users: number; vehicles: number; logsPerDay: number; loadsPerUserPerDay: number };
type Arch = "per-log" | "rollup";

const READ_PRICE_PER_100K = 0.06; // USD, North America

function readsPerLoad(t: Tenant, arch: Arch): number {
  // Rollup stores one doc per company per day, so 90 docs for a quarterly dashboard.
  const income = arch === "per-log" ? t.logsPerDay * 90 : 90;
  const lists  = t.vehicles * 2;            // drivers list + vehicles list
  const misc   = 1 + 50 + 6;                // target + notifications + rule reads
  return income + lists + misc;
}

function monthlyUSD(tenants: number, t: Tenant, arch: Arch): number {
  const loadsPerDay = t.users * t.loadsPerUserPerDay;
  const monthlyReads = readsPerLoad(t, arch) * loadsPerDay * 30 * tenants;
  return (monthlyReads / 100_000) * READ_PRICE_PER_100K;
}

The numbers

Wide scale (all small tenants):

Tenants	Per-log $/month	With daily rollups
1	$1.01	$0.09
100	$101	$9
1,000	$1,013	$90
10,000	$10,135	$902

Deep scale: One big tenant (100 vehicles, one company): per-log = $24.65/month, rollup = $0.47/month.

Two things fall out.

The per-log model's bill crosses $1,000/month somewhere around 1,000 small tenants. That's fine if you're charging $30/month per seat. That's catastrophic if you're running freemium.
The per-log model costs more for one big tenant than for a hundred small ones. Deep scale punishes you harder than wide scale, because the income-log window grows linearly with the fleet while everything else stays flat.

Reality Checks

Under ~200 small tenants, or your first big tenant: stay per-log. The complexity of rollups isn't worth the $20–$100/month you'd save. Spend that time on the product.
Planning for 1,000+ tenants, or a first tenant with 50+ vehicles: build the rollup pattern on day one. Migrating from per-log to rollup once you have live data is painful. It is much cheaper to set up the Cloud Function up front and write both documents from the first income log.
Somewhere in the middle: watch your bill. Firestore bills daily, the spike shows up fast once it starts.

Build Reliable Local Notifications in Flutter (Step-by-Step)

Mxolisi Masuku — Thu, 16 Apr 2026 08:43:51 +0000

Companion post to How I Built the Long Game Notification System. This is the walkthrough. If you want the thinking behind the decisions, read that first. If you just want the recipe, you're in the right place.

What You're Building

A notification system where:

Notifications fire at the exact time you set, every day
They work when the phone is locked, the app is killed, or the device is in Doze mode
Notification content is personalized with fresh data on every app open
The entire system runs locally — no push server, no Cloud Functions, zero delivery cost
Pomodoro-style one-shot alarms fire on time even when the app is suspended
Notifications survive Samsung, Xiaomi, and Huawei battery killers without FCM

What You're NOT Using

workmanager — the OS throttles background tasks. Your 15-minute poll becomes hours.
Dart Timer.periodic for delivery — dies the moment the phone locks.
Firebase Cloud Messaging — overkill for local, user-specific scheduling.
Background Fetch (iOS) — Apple gives you 0–2 executions per day if you're lucky.

Step 1: Dependencies

# pubspec.yaml
dependencies:
  flutter_local_notifications: ^18.0.1
  timezone: ^0.10.0
  flutter_timezone: ^3.0.1
  permission_handler: ^11.3.1

That's it. Four packages.

The notification plugin handles scheduling.
The timezone packages ensure your 8:00 AM means 8:00 AM in Johannesburg, not UTC.
The permission handler lets you request notification access on Android 13+ and battery optimization exemption on Samsung/OEM devices.

Step 2: Android Permissions

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.SCHEDULE_EXACT_ALARM" />
<uses-permission android:name="android.permission.USE_EXACT_ALARM" />
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

What each one does:

Permission	Why
`POST_NOTIFICATIONS`	Required on Android 13+ to show any notification at all
`RECEIVE_BOOT_COMPLETED`	Alarms survive device reboots
`SCHEDULE_EXACT_ALARM`	Fires at the exact second, even in Doze mode (API ≤ 33)
`USE_EXACT_ALARM`	Guaranteed exact alarms on API 33+ — no user prompt needed, unlike `SCHEDULE_EXACT_ALARM` on API 34+
`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`	Lets you show the system "Allow unrestricted battery?" dialog — critical for Samsung, Xiaomi, Huawei
`WAKE_LOCK`	Keeps the CPU alive long enough to process the alarm and fire the notification

Watch out: On Android 14+ (API 34), SCHEDULE_EXACT_ALARM isn't granted by default. USE_EXACT_ALARM is a stronger alternative that's always granted for apps that declare it — but it may trigger Google Play review. Having both ensures maximum compatibility. Your code still needs the inexact fallback we'll cover in Step 7.

Step 3: Initialize on App Start

Before you can schedule anything, you need to initialize the timezone database and the notification plugin. This runs once in main(), before runApp().

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // ... your other init code (Firebase, etc.)

  await NotificationService.init();
  runApp(const MyApp());
}

// notification_service.dart
import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import 'package:timezone/timezone.dart' as tz;
import 'package:timezone/data/latest_all.dart' as tzdata;
import 'package:flutter_timezone/flutter_timezone.dart';
import 'package:permission_handler/permission_handler.dart';

class NotificationService {
  static final FlutterLocalNotificationsPlugin _plugin =
      FlutterLocalNotificationsPlugin();

  static Future<void> init() async {
    // 1. Initialize the timezone database and detect the device's zone.
    //    Without this, all scheduled times are wrong.
    tzdata.initializeTimeZones();
    try {
      final tzName = await FlutterTimezone.getLocalTimezone();
      tz.setLocalLocation(tz.getLocation(tzName));
    } catch (_) {
      // Fallback: stays UTC if detection fails
    }

    // 2. Initialize the plugin.
    //    We don't request permissions here — that happens later,
    //    at a moment that makes sense in your UX flow.
    const androidSettings = AndroidInitializationSettings(
      '@mipmap/ic_launcher',
    );
    const iosSettings = DarwinInitializationSettings(
      requestAlertPermission: false,
      requestBadgePermission: false,
      requestSoundPermission: false,
    );

    await _plugin.initialize(
      const InitializationSettings(
        android: androidSettings,
        iOS: iosSettings,
      ),
      onDidReceiveNotificationResponse: _onNotificationTap,
      onDidReceiveBackgroundNotificationResponse: _onBackgroundTap,
    );
  }

  // Handle taps when the app is alive
  static void _onNotificationTap(NotificationResponse response) {
    // Navigate to the relevant screen, stop a timer, etc.
  }

  // Handle taps when the app was killed — must be top-level or static
  @pragma('vm:entry-point')
  static void _onBackgroundTap(NotificationResponse response) {
    // App relaunches — handle in your normal init flow
  }
}

Why timezone matters: If you schedule for "8:00 AM" without initializing timezones, the plugin may interpret that as UTC. In Johannesburg (UTC+2), that's 10:00 AM. In New York (UTC-5), that's 3:00 AM. Always initialize before any zonedSchedule call.

Step 4: Schedule a Daily Repeating Notification

This is the core of the entire system. Three lines do the heavy lifting.

static Future<void> scheduleDailyNotification({
  required int id,
  required String title,
  required String body,
  required int hour,
  required int minute,
}) async {
  await _plugin.zonedSchedule(
    id,                                           // Fixed ID per notification type
    title,
    body,
    _nextInstanceOfTime(hour, minute),            // Next occurrence of this time
    const NotificationDetails(
      android: AndroidNotificationDetails(
        'your_channel_id',
        'Your Channel Name',
        channelDescription: 'What this channel is for',
        importance: Importance.high,
        priority: Priority.high,
      ),
      iOS: DarwinNotificationDetails(),
    ),
    uiLocalNotificationDateInterpretation:
        UILocalNotificationDateInterpretation.absoluteTime,
    androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
    matchDateTimeComponents: DateTimeComponents.time,    // ← THIS IS THE KEY
  );
}

The three things that make it work:

exactAllowWhileIdle — fires even in Doze mode. The OS wakes up just enough to deliver your notification.
matchDateTimeComponents: DateTimeComponents.time — tells the OS: "repeat this every day at this hour:minute." You schedule it once. It fires every day. No background task. No polling.
_nextInstanceOfTime — computes the next future occurrence of the target time.

static tz.TZDateTime _nextInstanceOfTime(int hour, int minute) {
  final now = tz.TZDateTime.now(tz.local);
  var scheduled = tz.TZDateTime(
    tz.local,
    now.year,
    now.month,
    now.day,
    hour,
    minute,
  );
  // zonedSchedule requires a future datetime
  if (scheduled.isBefore(now)) {
    scheduled = scheduled.add(const Duration(days: 1));
  }
  return scheduled;
}

Why this helper exists: zonedSchedule requires the initial fire time to be in the future. If it's 9:00 AM and you schedule for 8:00 AM, the helper pushes it to 8:00 AM tomorrow. The matchDateTimeComponents flag handles every day after that.

Step 5: CRITICAL: The Cancel Trap

==(This bit is annoying if not taken care of)==

This is the bug that will silently break your notifications and you won't notice for days. I shipped it. It cost me a full day of missed notifications before I caught it.

The broken pattern

//  DO NOT DO THIS
static Future<void> reschedule() async {
  await _plugin.cancel(id);                     // Destroys the repeating alarm
  await _plugin.zonedSchedule(id, ...);         // Creates a new one
}

It looks correct. It's not. Here's what happens:

User opens the app at 9:00 AM
cancel(1) — destroys the existing repeating 8:00 AM alarm
_nextInstanceOfTime(8, 0) — 8:00 AM today already passed, returns tomorrow 8:00 AM
zonedSchedule(1, ...) — schedules a new alarm starting tomorrow
Tomorrow, user opens the app at 9:00 AM again → same thing
The notification is perpetually pushed to "tomorrow" and never fires

The correct pattern

// Only cancel when the user disables the notification
static Future<void> schedule(bool enabled, int hour, int minute) async {
  if (!enabled) {
    await _plugin.cancel(id);    // User turned it off — remove the alarm
    return;
  }
  // Calling zonedSchedule with the same ID REPLACES the existing alarm
  // without resetting the repeat cycle. No cancel needed.
  await _plugin.zonedSchedule(id, ...);
}

The rule: zonedSchedule with the same ID overwrites the previous alarm — it updates the title, body, and schedule time without destroying the repeat. You only need cancel when you want the notification to stop entirely.

This means you can safely call rescheduleAll() on every app open to refresh notification content (e.g., "You have 3 projects today" becomes "You have 4 projects today") without breaking delivery.

Step 6: Refresh Content on App Open

Notification bodies are frozen at schedule time. If the user adds a project at 11 PM, you want tomorrow's morning notification to include it.

// main.dart — after init, before runApp
if (FirebaseAuth.instance.currentUser != null) {
  NotificationService.rescheduleAllNotifications().catchError((_) {});
}

rescheduleAllNotifications() fetches fresh data and calls zonedSchedule for each enabled notification, overwriting the stale body. No cancel — just overwrite.

Two things to guard against:

Auth check — if your notification content depends on user-specific data (Firestore queries), and no user is signed in, the query will hang. This blocks main() and your app never starts. Gate it.
Fire-and-forget — use .catchError((_) {}). If the reschedule fails (offline, Firestore timeout), the previously scheduled alarm still fires with yesterday's content. That's better than crashing on startup.

Step 7: Handle Android 14+ Exact Alarm Restriction

Android 14 changed the rules. SCHEDULE_EXACT_ALARM is no longer auto-granted. If your app calls exactAllowWhileIdle without the permission, it throws.

The graceful fallback:

static Future<void> scheduleDailyNotification({
  required int id,
  required String title,
  required String body,
  required int hour,
  required int minute,
}) async {
  final scheduledTime = _nextInstanceOfTime(hour, minute);
  final details = /* your NotificationDetails */;

  try {
    // Try exact first — best experience
    await _plugin.zonedSchedule(
      id, title, body, scheduledTime, details,
      uiLocalNotificationDateInterpretation:
          UILocalNotificationDateInterpretation.absoluteTime,
      androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
      matchDateTimeComponents: DateTimeComponents.time,
    );
  } catch (e) {
    // Exact alarm not permitted — fall back to inexact
    // Delivery may drift by ~10 minutes, but the notification still fires
    await _plugin.zonedSchedule(
      id, title, body, scheduledTime, details,
      uiLocalNotificationDateInterpretation:
          UILocalNotificationDateInterpretation.absoluteTime,
      androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
      matchDateTimeComponents: DateTimeComponents.time,
    );
  }
}

For most notifications, a 10-minute window is fine. "Your day is 63% gone" at 2:10 PM instead of 2:00 PM doesn't break the experience.

Apply this same pattern to one-shot alarms too. Your pomodoro alarm scheduler should have the same try/catch:

static Future<void> schedulePhaseAlarm({
  required int durationMinutes,
  required NotificationDetails details,
}) async {
  final fireAt = tz.TZDateTime.now(tz.local)
      .add(Duration(minutes: durationMinutes));

  try {
    await _plugin.zonedSchedule(
      alarmId, title, message, fireAt, details,
      uiLocalNotificationDateInterpretation:
          UILocalNotificationDateInterpretation.absoluteTime,
      androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
    );
  } catch (_) {
    // Fall back to inexact — still fires, may drift ~5-10 min
    try {
      await _plugin.zonedSchedule(
        alarmId, title, message, fireAt, details,
        uiLocalNotificationDateInterpretation:
            UILocalNotificationDateInterpretation.absoluteTime,
        androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
      );
    } catch (e) {
      print('[Notifications] Failed to schedule alarm: $e');
    }
  }
}

Step 8: One-Shot Alarms (Pomodoro, Timers)

Daily repeating alarms cover most cases. But sometimes you need a notification that fires once at a specific future time — like when a 25-minute pomodoro focus session ends.

static Future<void> scheduleOneShot({
  required int id,
  required String title,
  required String body,
  required int minutesFromNow,
  required NotificationDetails details,
}) async {
  final fireAt = tz.TZDateTime.now(tz.local)
      .add(Duration(minutes: minutesFromNow));

  await _plugin.zonedSchedule(
    id,
    title,
    body,
    fireAt,
    details,
    uiLocalNotificationDateInterpretation:
        UILocalNotificationDateInterpretation.absoluteTime,
    androidScheduleMode: AndroidScheduleMode.exactAllowWhileIdle,
    // NO matchDateTimeComponents — this fires once, doesn't repeat
  );
}

Why you need this for pomodoro: A Dart Timer.periodic runs in your app's process. When the user locks their phone, the OS suspends the app within ~30 seconds. Your timer stops ticking. The phase ends, and — silence. The bell only rings when they unlock the phone and the app resumes.

An OS alarm doesn't care about your app's lifecycle. It fires regardless.

Making one-shot alarms alarm-grade

A standard Importance.high notification won't cut it on Samsung, Xiaomi, or Huawei devices. These OEMs aggressively kill background processes and suppress notifications they deem non-essential. You need to make your notification look like an alarm clock to the OS:

import 'dart:typed_data';

NotificationDetails _alarmGradeDetails({required bool isWorkPhase}) {
  final soundFile = isWorkPhase ? 'bell_focus' : 'bell_break';
  final channelId = isWorkPhase ? 'focus_bell' : 'break_bell';
  final channelName = isWorkPhase ? 'Focus Bell' : 'Break Bell';

  return NotificationDetails(
    android: AndroidNotificationDetails(
      channelId,
      channelName,
      channelDescription: 'Pomodoro phase transition',
      importance: Importance.max,                              // Maximum priority
      priority: Priority.max,
      sound: RawResourceAndroidNotificationSound(soundFile),
      playSound: true,
      fullScreenIntent: true,                                  // Wakes the screen
      category: AndroidNotificationCategory.alarm,             // Treated like an alarm
      visibility: NotificationVisibility.public,               // Shows on lock screen
      enableVibration: true,
      vibrationPattern: Int64List.fromList([0, 400, 200, 400]),
    ),
    iOS: DarwinNotificationDetails(
      presentAlert: true,
      presentSound: true,
      sound: '$soundFile.wav',
      interruptionLevel: InterruptionLevel.timeSensitive,      // Breaks through Focus
    ),
  );
}

What each flag does:

Flag	Effect
`importance: Importance.max`	Heads-up notification — appears at the top of the screen
`fullScreenIntent: true`	Wakes the screen and shows the notification even when locked. This is what alarm clock apps use.
`category: AndroidNotificationCategory.alarm`	Tells the OS this is time-critical. Samsung's battery manager respects this category.
`visibility: NotificationVisibility.public`	Content visible on the lock screen without unlocking
`vibrationPattern`	Custom vibration so the user physically feels it
`interruptionLevel: InterruptionLevel.timeSensitive`	iOS 15+: breaks through Focus mode

This is the difference between a notification that works on your desk and one that works in your pocket. Standard Importance.high gets silently suppressed by Samsung's battery manager. Importance.max + fullScreenIntent + category: alarm does not.

The dual-delivery pattern

When the app is in the foreground, the Dart timer catches the transition first (instant feedback). When the phone is locked, the OS alarm delivers it. To avoid the user hearing two bells:

// In your timer tick (foreground path)
void _onPomodoroPhaseEnd() {
  _plugin.cancel(alarmId);            // Cancel the OS alarm (Dart beat it)
  _plugin.show(displayId, ...);       // Show the notification immediately
  _scheduleNextPhaseAlarm();          // Schedule for the next phase
}

Use separate IDs for the scheduled alarm and the instant notification if you want, or the same ID if you want one to replace the other. Either way, the user sees exactly one notification.

Step 9: Weekly Repeating Notifications

For notifications that fire on specific weekdays — like a project reminder every Monday, Wednesday, and Friday at 6:00 PM.

static Future<void> scheduleWeekly({
  required int id,
  required String title,
  required String body,
  required int weekday,    // 1 = Monday, 7 = Sunday
  required int hour,
  required int minute,
}) async {
  await _plugin.zonedSchedule(
    id,
    title,
    body,
    _nextInstanceOfWeekdayTime(weekday, hour, minute),
    /* notificationDetails */,
    uiLocalNotificationDateInterpretation:
        UILocalNotificationDateInterpretation.absoluteTime,
    androidScheduleMode: AndroidScheduleMode.inexactAllowWhileIdle,
    matchDateTimeComponents: DateTimeComponents.dayOfWeekAndTime,  // ← Weekly
  );
}

static tz.TZDateTime _nextInstanceOfWeekdayTime(
  int weekday, int hour, int minute,
) {
  final now = tz.TZDateTime.now(tz.local);
  var scheduled = tz.TZDateTime(
    tz.local, now.year, now.month, now.day, hour, minute,
  );
  // Advance to the target weekday
  while (scheduled.weekday != weekday) {
    scheduled = scheduled.add(const Duration(days: 1));
  }
  // If it's already passed this week, push to next week
  if (scheduled.isBefore(now)) {
    scheduled = scheduled.add(const Duration(days: 7));
  }
  return scheduled;
}

Important: Each weekday needs its own notification ID. If you want reminders on Monday, Wednesday, and Friday, that's three separate zonedSchedule calls with three different IDs. When removing the reminder, cancel all of them.

// Generating unique IDs per project + weekday
final notifId = baseId + projectId.hashCode.abs() % 900 + weekday;

Step 10: Surviving Samsung Battery Optimization

This is the step most Flutter notification tutorials skip, and it's why your notifications work perfectly during development but fail silently in production.

The problem

Samsung, Xiaomi, Huawei, OnePlus, and most Chinese OEMs add an aggressive battery optimization layer on top of Android's standard Doze mode. Even if your alarm is correctly scheduled with exactAllowWhileIdle, the OEM's battery manager can:

Kill your app process after ~5 minutes of screen-off time
Block AlarmManager exact alarms from waking the app
Silently suppress notifications from "sleeping" apps

This is why WhatsApp, Duolingo, and Telegram work but your app doesn't — Google Play Services (which delivers FCM push notifications) is whitelisted at the system level. Your app is not. You need the user to manually exempt you.

The solution

Android provides a system dialog that asks the user to whitelist your app from battery optimization. You can trigger it using the permission_handler package (which you already have for notification permissions):

import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:permission_handler/permission_handler.dart';
import 'package:shared_preferences/shared_preferences.dart';

class BatteryOptimizationService {
  static const String _keyAsked = 'battery_optimization_asked';

  /// Check if the app is already exempted from battery optimizations.
  static Future<bool> isExempted() async {
    if (!Platform.isAndroid) return true;
    final status = await Permission.ignoreBatteryOptimizations.status;
    return status.isGranted;
  }

  /// Request battery optimization exemption.
  /// Shows the system "Allow unrestricted battery?" dialog.
  static Future<bool> requestExemption() async {
    if (!Platform.isAndroid) return true;
    final status = await Permission.ignoreBatteryOptimizations.request();
    return status.isGranted;
  }

  /// Check and prompt once — call on first pomodoro start.
  static Future<void> ensureExemptedForPomodoro() async {
    if (!Platform.isAndroid) return;
    if (await isExempted()) return;

    final prefs = await SharedPreferences.getInstance();
    if (prefs.getBool(_keyAsked) ?? false) return;

    final granted = await requestExemption();
    await prefs.setBool(_keyAsked, true);
    debugPrint('[Battery] Exemption ${granted ? "granted" : "denied"}');
  }
}

When to prompt

Don't ask on app first launch — the user has no context for why you need it. Ask at the moment it matters:

Future<void> startPomodoro(String projectId, {required String projectName}) async {
  // Ask BEFORE the timer starts — user understands why
  await BatteryOptimizationService.ensureExemptedForPomodoro();

  // ... start the timer, schedule the alarm
}

The system dialog is native Android UI — it looks official, not spammy. And because we gate it with _keyAsked, the user only sees it once.

What the user sees

The dialog says something like:

Let LongGame run in the background?

This app will be able to run in the background, which may increase battery usage.

[DENY] [ALLOW]

If they tap "Allow", your app is exempted from the OEM's battery killing. Your exactAllowWhileIdle alarms now fire reliably even with the screen off.

For extra reliability

If your users are on Samsung specifically, you may also want to link them to the device-specific battery settings. Samsung has an additional "Sleeping Apps" list that operates independently of Android's standard battery optimization. The don't kill my app project maintains device-specific instructions you can reference in your settings screen.

Step 11: Custom Notification Sounds

If you want distinct sounds for different notification types — like a bright bell for "focus" and a warm chime for "break" — you need three things.

File placement

android/app/src/main/res/raw/bell_focus.wav     ← Android reads from res/raw
ios/Runner/bell_focus.wav                        ← iOS reads from app bundle
assets/sounds/bell_focus.wav                     ← Optional: Flutter assets

Notification details with sound

NotificationDetails(
  android: AndroidNotificationDetails(
    'channel_focus_bell',                                    // Unique channel ID
    'Focus Bell',
    sound: RawResourceAndroidNotificationSound('bell_focus'), // No file extension
    playSound: true,
  ),
  iOS: DarwinNotificationDetails(
    presentSound: true,
    sound: 'bell_focus.wav',                                  // With file extension
  ),
);

The channel rule

Android requires a separate notification channel for each distinct sound. Once a channel is created, its sound cannot be changed programmatically — the user would need to clear app data or reinstall. Name your channels carefully the first time.

// One channel per sound
'longgame_focus_bell'   →  bell_focus.wav
'longgame_break_bell'   →  bell_break.wav
'longgame_reminders'    →  default system sound

// Don't try to reuse a channel with different sounds
// The first sound "wins" and the channel ignores subsequent changes

The Complete Reference

Which mechanism to use

Scenario	Method	Repeats?
Daily notification (8:00 AM every day)	`zonedSchedule` + `DateTimeComponents.time`	Every day
Weekly reminder (Mon at 6:00 PM)	`zonedSchedule` + `DateTimeComponents.dayOfWeekAndTime`	Every week
One-shot alarm (25 min from now)	`zonedSchedule`, no `matchDateTimeComponents`	Once
Persistent indicator (timer running)	`_plugin.show()` with `ongoing: true`	Until cancelled
Instant alert (event just happened)	`_plugin.show()`	Once

Which notification details to use

Scenario	Importance	fullScreenIntent	Category	Why
Daily nudge / reminder	`high`	`false`	—	Standard heads-up, doesn't need to wake the screen
Pomodoro phase transition	`max`	`true`	`alarm`	Must wake the screen and break through Samsung battery killing
Ongoing timer	`low`	`false`	`stopwatch`	Persistent but non-intrusive, lives in the notification shade
Session reminder	`high`	`false`	—	Standard importance, user is likely awake

What not to use

Approach	What goes wrong
`WorkManager` periodic task	OS throttles it. 15-minute minimum becomes hours in Doze.
`Dart Timer.periodic` for alerts	Stops when phone locks. App suspended = timer dead.
`cancel()` then `zonedSchedule()` on app open	Perpetually pushes alarm to "tomorrow." Never fires.
iOS Background Fetch	0–2 executions per day. Apple decides when, not you.
`Importance.high` for time-critical alarms	Samsung silently suppresses it. Use `max` + `alarm`.
Ignoring battery optimization	Works on Pixel, dies on Samsung. 70%+ of Android users are on OEM skins.

Android permissions checklist

Permission	When needed
`POST_NOTIFICATIONS`	Always (Android 13+)
`RECEIVE_BOOT_COMPLETED`	If alarms should survive reboots
`SCHEDULE_EXACT_ALARM`	Exact alarms (API ≤ 33, runtime request on API 34+)
`USE_EXACT_ALARM`	Guaranteed exact alarms (API 33+), no user prompt
`REQUEST_IGNORE_BATTERY_OPTIMIZATIONS`	Battery exemption dialog
`WAKE_LOCK`	Keep CPU alive during alarm processing

Notification IDs

Use fixed IDs per notification type. zonedSchedule with the same ID replaces the existing alarm. This is your friend — it's how you update content without breaking repeats.

static const int idMorningIntent = 1;
static const int idDriftAlert    = 2;
static const int idMirror        = 3;
static const int idStreak        = 4;
static const int idTimerRunning  = 5;
static const int idOngoingTimer  = 6;
static const int idPomodoroAlarm = 98;
static const int idPomodoro      = 99;
static const int idSessionBase   = 100;  // + project hash + weekday

The Bugs To Watch For

Bug 1: The startup hang

Your rescheduleAll() queries Firestore for personalized content. If no user is signed in, the Firestore SDK with offline persistence doesn't throw — it hangs. Your main() never reaches runApp(). The app is stuck on the splash screen.

Fix: Check FirebaseAuth.instance.currentUser != null before rescheduling. Also make the call fire-and-forget with .catchError() so a Firestore timeout doesn't block startup.

Bug 2: The cancel-reschedule cycle

Covered in Step 5, but worth repeating because it's the most insidious bug. It works perfectly in development (you're always testing right after scheduling), and fails silently in production (the user opens the app after the notification time, so it's always pushed to tomorrow).

Fix: Never cancel before zonedSchedule for enabled notifications. Only cancel when disabling.

Bug 3: The locked-phone silence

Your Dart timer works nicely in the foreground. You test it, the notification fires after 25 minutes, you ship. Then a user runs a pomodoro session, puts the phone down, and hears nothing. The OS suspended your app. Your timer stopped.

Fix: Schedule a one-shot OS alarm for the exact phase end time. The Dart timer is for foreground UX; the OS alarm is for reliability. Let them race.

Bug 4: The Samsung battery killer

Everything works on your Pixel. Every alarm fires on time. You ship. Then 70% of your users (Samsung, Xiaomi, Huawei) report that pomodoro notifications never arrive when the screen is off.

Samsung adds "Sleeping Apps" and "Deep Sleeping Apps" lists on top of Android's standard Doze. Even exactAllowWhileIdle alarms are suppressed for apps on these lists. Your perfectly scheduled alarm never fires because Samsung killed your process and blocked the AlarmManager wakeup.

Fix (three layers, use all of them):

Request battery optimization exemption — show the system "Allow unrestricted?" dialog on first pomodoro start. This removes you from the standard Android optimization. (Step 10)
Use alarm-grade notification details — fullScreenIntent: true + category: alarm + Importance.max. The OS treats these like alarm clock notifications and is far less likely to suppress them. (Step 8)
Declare USE_EXACT_ALARM — this permission is always granted on API 33+ without user interaction, giving you a stronger guarantee than SCHEDULE_EXACT_ALARM alone. (Step 2)

None of these alone is sufficient. Together, they give you the same delivery reliability as WhatsApp on Samsung.

The Cost

Component	Cost per user
FCM push messages	$0 — not used
Cloud Functions	$0 — computed on-device
Firestore reads for content	$0 — bundled with existing app queries
Local alarm scheduling	$0 — OS-level, no backend
Battery optimization prompt	$0 — native system dialog

The entire notification system runs at zero marginal cost. The trade-off is that notification content is only as fresh as the user's last app open. For daily reflections and nudges, that's perfectly fine — you're computing tomorrow's content with today's data, and it's accurate enough to be useful.

This is the system behind Long Game, a life auditing app for people who want to be intentional with their time. The original post explaining the design decisions is here.

The People On The Other Side Of Your Upwork Proposal

Mxolisi Masuku — Mon, 30 Mar 2026 03:19:47 +0000

Upwork is increasingly getting difficult — or so they say. I've had quite a number of friends who created an account and abandoned it, and others curious about whether it's worth starting. The conversation kept repeating itself so I decided to write this.

If the Internet tells you Upwork is a scam, understand what you are actually hearing: frustration from people who didn't make it, and silence from the thousands quietly building careers on the platform. People who are making money on Upwork eat quietly. The loudest voices are freelancers turned influencers who make money coaching you, and the disgruntled ones on Reddit whose complaints come wrapped in humble brags. "I have a $400k account but Upwork treated me like this." $400k is life-changing money — but if you break the rules, Upwork is judge, jury and executioner. Your account size doesn't matter.

The Numbers Behind The Noise

Upwork is not a startup hoping to find product-market fit. It is the dominant player in the freelance platform market.

Record full-year revenue of $788 million in 2025. Over $4 billion in gross services volume — that's the total amount clients spent on the platform in a single year. More than 18 million registered freelancers across 180+ countries. Around 800,000 active clients. Upwork holds roughly 61% of the freelance platform market share, more than triple Fiverr's and double Toptal's. Fast Company named them one of the Most Innovative Companies of 2025, and Frost & Sullivan gave them the Global New Product Innovation Award in 2023.

AI-related work on the platform grew 60% year-over-year in 2024, and freelancers working on AI projects earned 44% more per hour than those who didn't. The average freelancer hourly rate sits around $39. Web and software development accounts for 34% of all work on the platform.

Why does this matter to you? $4 Billion in circulation means this is not a dying marketplace. The money is real, the clients are real, and the opportunity is real. The question is whether you can position yourself to capture your slice of it.

1. Think People First

Before you get into the Upwork algorithm debate, start here: Who are the people on the other side of your proposals?

The client landscape has shifted. Three or four years ago, the typical Upwork client had money to spend, no time to look for talent, and needed an automated way to protect their interests. You saw people offering 3-year contracts at $40 an hour.

Since 2025, the attitude has changed. Everyone is looking to save. But not everyone is looking to save the same way. Here's how I break down the client tiers on Upwork right now:

The top-tier client understands the value of AI in speeding things up. He has money but is not willing to splash it on a slow freelancer. This client wants the best person on the job who can leverage AI to move fast, and can pay explosive amounts for it. Usually after the first successful job, these people will negotiate a long-term contract with a reliable freelancer. They don't sift through 150 proposals. They go to Upwork and say "find me someone who can do this" and the algorithm feeds them the best and boosted profiles. This is where Connects, profile optimisation and your Upwork ranking all come in.

The fair-price client says "I have this job, I have this amount, let's work." Expect fair treatment here. This kind of client appreciates honesty, communication and thoroughness. These are skills you should have or be actively improving.

The exploitative client knows the freelance labour market is full of desperate people right now. So he dangles a carrot. $50 for a hard job. Then he piles on responsibility knowing the developer will do it just to get good reviews. Upwork has documentation to help you handle this, but you need to recognise the pattern before you're already trapped.

The scammer. You have to beware of these. They will take you for everything you've got. Steal, use you, hack you or worse. Follow Upwork's guidelines on surviving scammers and go to the unofficial Upwork Reddit channel — r/Upwork. It's unhinged and town-square-like, but it will help you catch up fast with how scams are evolving.

Pro tip: Read The General Guide To Upwork Scams on Reddit

Once you know the people, you know who you need to become to be chosen. You can play the algorithm all you want, but on the other end of everything you type, there is a person who is as interested in gaining value and as afraid of losing money on bad product as you are.

Think people first. Upwork is a community brought together by the platform. The rules matter as much as the people they serve.

2. Play The Long Game But Work Hard On Your Short Plays

Freelancing is hard and competitive. Upwork, being the top platform, is even more competitive. Whether you are new or a seasoned freelancer looking to reinvent yourself: your patience will be tested and your persistence will be rewarded.

The long-term goal is being on a stable, well-paying contract. Being a top freelancer that Upwork recommends to its best clients. Getting paid consistently.

The mid-term goal is building up smaller, shorter contracts. Quick jobs. Building your skill set, networking, studying the market. You don't get to the long-term goal without passing through this one unless you are extremely lucky.

The immediate goal is your short plays. This is where the real work happens and where most freelancers give up too early.

In my experience, I got lucky in a sense — I got to Top Rated Plus with just 3 jobs. But those 3 jobs amount to 2,240+ hours. My takeaway: there is more value in sustaining a long-term business relationship than in chasing volume. Your mileage may vary, but there is no substitute for good work and maintaining good relationships.

As you improve your profile, think of every iteration of profile development as a play that must be analysed and improved. Every proposal is a data point that needs to be dissected and built on.

Source: r/Upwork

Look at this from r/Upwork. 49 proposals sent in 90 days. Only 7 were even viewed. 3 interviews. 2 hires. $1,500 earned in the first few months on the platform. This is what the grind looks like. Most of your proposals will disappear into the void. The game is making sure the ones that land are good enough to convert.

Read job posts. What skills are clients asking for? What's the overall application tone on key skills? It's all about patience, playing the long game and relentlessly looking to improve.

Right now, in most of the job posts I see, clients are prioritising freelancers who have an AI-first attitude. n8n, Agentic Workflows, Supabase, Firebase, Cursor, Antigravity top almost every post. These can be pointers but they can also get you panicking and chasing the wind. When you see trends like these you can either choose to be a generalist or a specialist. I chose to specialise. Depth beats breadth when a client scans 50 proposals and needs to trust that you've solved their exact problem before.

In the job posts, listen to what clients are saying about what they need. More importantly, listen to what they're saying about the freelancer they want to work with. Become that person.

Again. Think people first.

3. Follow The Rules

The most nerve-wracking moment in your Upwork journey will be right after a client says "Hey, I saw your proposal. I'm interested. Let's talk."

At this moment, your position must shift: DO NOT THINK PEOPLE FIRST. Think Upwork first.

Do not be hoodwinked. Your main concern shouldn't be what the other person is saying. It should be: what does Upwork say about this? For every response you send, you must consider the Upwork funnel and playbook.

Failure to do so will result in a ban. Back in the day the ban was effective immediately and non-negotiable, though this may be shifting since Upwork now shows you account health status.

Things to know: Upwork is ruthless on freelancers who share personal contact details before a contract is finalised. Clients who want to take the conversation off-platform before a contract is signed are a red flag. On top of that, you should also be able to negotiate boldly without putting yourself in the corner, all while studying your client for scammer patterns.

Have your own rules as a freelancer and follow them. Know Upwork's rules and follow them. Listen to the client's rules and expectations and see if you are prepared to follow them. This is the foundation of your Upwork survival journey.

The interview and contract negotiation phase is the most dangerous period of your freelance career. When you see people talking about how a single mistake cost them everything, this is the phase they're talking about. This is why the unofficial Upwork Reddit channel is a must-visit.

Protect yourself. Protect your account.

Last Word

How do you survive Upwork as a freelancer? This entire article can be distilled into one statement: Know and study the people on Upwork, and follow the rules.

Link to the You can also check the official Upwork subreddit, though it's much smaller than r/Upwork.

My name is Mxolisi Masuku. I write blogs like this and I have a newsletter called Systems For Humans where I talk about the software world beyond the technical considerations. For me, the software world works better when you think about who is on the other end as the guiding principle of whatever you are going to build. Subscribe and follow if you like this.

Build Your Stripe Checkout Like A Lawyer, Not Just A Developer

Mxolisi Masuku — Sat, 28 Mar 2026 10:58:13 +0000

Most developers and vibe coders build their Stripe checkout to accept payments. They don't build it to survive disputes with people, their customers. In Stripe's ecosystem, a single ban or badly handled chargeback can cost your business everything. This article is about how to make sure it doesn't.

Your Refund Policy Is Your First Line of Defence

Before you write a single line of checkout code, you need a refund and chargeback policy. Not a template you copied from the internet. A policy you have actually stress-tested against real scenarios.

For example, I am working on a platform that sells music beats. These fall under digital products. My thought process was: What happens when a customer pays for a beat, downloads it, then says they don't want it anymore and claims they never used it? What if they didn't download it? How would I even prove that? What if they come back after 2 days? 2 weeks? 2 months?

These disputes will come.

Some will be genuine, some will be fraudulent. Your policy is the wall between you keeping that money and Stripe taking it back.

This policy must be visible to the user. The user must accept it before they complete the purchase. The usual feature on most sites is a checkbox with: "I accept and agree to the terms and conditions." Simple. But if it's not there, you have nothing to stand on.

When building, you want to spend more of your initial time in the Stripe Sandbox where you test all of this before real money is involved. Play both God and customer. Simulate every scenario you can think of. Who has access to the payment gateway and at what stage? How are payments reflecting on your dashboard? Don't take the Sandbox for granted because it is the only environment where mistakes cost you nothing.

Capture Every Event. Prove Everything.

When a dispute hits, Stripe doesn't take your word for it. They want evidence. The card provider wants evidence. And if you haven't been recording the right events from the start, you have nothing to give them.

Every interaction between the user and your checkout process needs to be logged. Every click, every purchase, every policy agreement. What IP address did the user have? Was it consistent with their usual IP? Was the purchase made from a valid session? Did the user explicitly agree to the refund policy? Did you deliver the product? You need to be able to prove and demonstrate all of this with timestamps and unique IDs.

This is the part where you have to be deliberate with your AI. If you are vibe coding your checkout, there is a real chance your AI won't build evidence capture unless you specifically ask for it. AI is great at making the payment flow work. AI is not great at thinking about what happens when a customer disputes that payment six weeks later. You have to stress this requirement yourself.

Pro tip: Stripe has an AI Assistant for general queries and Agent Skills and Connectors for deeper integration. Use these if you are on Claude.

Event logging should be built as a feature not an afterthought. You want to be able to export all the evidence Stripe and card providers require, as a PDF or JSON, with all the required fields populated. When the dispute comes, and it will, you pull the file and submit it. That's the difference between keeping the money and losing it.

For reference, look at Stripe's dispute evidence object documentation. It tells you exactly what fields they expect: customer email, customer IP, product description, proof of delivery, refund policy disclosure, and more. Build your logging around that schema and you won't be scrambling when the first chargeback arrives.

Send Receipts and Invoices. Build Trust Before You Need It.

You can configure Stripe to send customer emails in Settings → Business → Email → Customer Emails. This isn't a legal requirement but think about it from the human side. You just made a $240 purchase and you don't get a receipt in your email. That's how distrust starts. That's how chargebacks start.

Receipts, invoices, upcoming deductions, subscription reminders. These are not nice-to-haves. They are evidence that you communicated with your customer. They are proof that the customer knew what they were paying for and when. If a dispute lands, a clean email trail showing receipts sent and subscription reminders delivered tells a very different story from silence.

If you want to go beyond Stripe's default emails and build custom branded ones, a tool like Resend works well for this. You create React template emails, hook them to your Stripe webhooks, and fire a custom receipt whenever a checkout.session.completed event lands. Resend gives you 100 emails a day for free. If you are hitting 100 emails a day, that means you got 100 customers a day and you can afford their $20 a month subscription.

Build For Humans. Defend Against The Worst Ones.

The thread running through this article is that you should build your software for human behaviour. Defend against malicious intent and protect yourself from legal punishment at the same time.

Most startups get burned not because their product was bad but because they didn't think about what happens when a real person with real emotions and real incentives interacts with their payment system. People forget what they bought. People regret purchases. People lie. And some people game the system because they know most small developers don't have their evidence in order.

Your checkout is not just a technical flow. It is a legal document, a communication channel and a defence mechanism. Treat it that way from day one.

Additional Reading

Stripe as the authority on why chargebacks happen and how to prevent them
If you are looking how rough things can get on chargebacks check this subReddit. The question: Are Stripe Chargebacks impossible to win.
Another Stripe Blog read: Can AI agents build real Stripe integrations? We built a benchmark to find out
If you ever decide that Stripe is not for you. Here is a video on alternatives.

My name is Mxolisi Masuku. I am a software engineer and a freelancer on Upwork. If you liked this, subscribe to my newsletter, Systems for Humans, where I write about the software world beyond the technical considerations.