DEV Community: Yusuf kızılkan

Everything your Flutter app needs after login (and why most starters stop there)

Yusuf kızılkan — Thu, 06 Aug 2026 00:40:01 +0000

Every Flutter starter kit solves the login screen. Almost none of them solve what comes after it.

I spent the last few weeks building the "after" part for a real SaaS app, and it turned out to be six distinct problems — each one with a gotcha I didn't see coming. Here's what I learned, with the details that cost me the most time.

Token refresh is a queueing problem, not a retry problem

The naive version: catch a 401, call /auth/refresh, retry the request. This works right up until your app fires three requests at once on a cold start. All three get a 401, all three call refresh, and now you have a race — two of them refresh with a token that's already been rotated server-side, and your user gets logged out for no reason.

The fix is to treat refresh as a single-flight operation. When a 401 arrives, check whether a refresh is already in progress. If it is, queue the request and wait for the result instead of starting a second refresh:

dart
Future _refreshOnce() {
// If a refresh is already running, everyone waits on the same future.
return _refreshFuture ??= _doRefresh().whenComplete(() {
_refreshFuture = null;
});
}

Small change, and it removes a whole class of "randomly logged out" bug reports.

Your subscription state lives in two places, and they drift

If you use RevenueCat (or any IAP layer), the client knows whether the user is entitled. Your backend doesn't — until you tell it. And you need the backend to know, because the client can lie and because your server-side features need to gate on something.

The answer is the webhook. RevenueCat posts events to your API, you map the entitlement to a column, done:

python
@router.post("/webhooks/revenuecat")
async def revenuecat_webhook(request: Request, db: Session = Depends(get_db)):
verify_signature(request) # don't skip this
event = (await request.json())["event"]
user = db.query(User).filter(User.id == event["app_user_id"]).first()
user.subscription_status = (
"premium" if event["type"] in ACTIVE_EVENTS else "free"
)
db.commit()

Two things people get wrong here: not verifying the signature (your endpoint is public, anyone can POST to it), and treating the webhook as the only source of truth. Webhooks get delayed and dropped. Read entitlements on the client too, and let the backend column be the authoritative one for server-side checks.

Push notifications need a device token table, not a user column

It's tempting to store fcm_token on the user row. Then your user installs the app on a tablet, and the phone stops getting notifications.

One user, many devices. Separate table, and handle token rotation — FCM rotates tokens on reinstall, restore, and sometimes for no visible reason:

python
class DeviceToken(Base):
tablename = "device_tokens"
id = Column(Integer, primary_key=True)
user_id = Column(Integer, ForeignKey("users.id"))
token = Column(String, unique=True, index=True)

Account deletion is an app store requirement with a trap in it

Both stores now require in-app account deletion. What's less obvious: deleting the account does not cancel the subscription. The user deletes their account, keeps getting charged, and blames you.

So the flow has to be: check whether the user has an active subscription, and if they do, tell them plainly that they need to cancel through the store as well. Then soft-delete rather than hard-delete — you want the row for billing reconciliation, but you want the personal data gone:

python
user.deleted_at = datetime.utcnow()
user.is_active = False
user.email = f"deleted-{user.id}@example.invalid"
user.full_name = None
user.avatar_url = None

Your starter should run before any API keys exist

This one is a design decision rather than a bug, and it changed how the whole project felt to work on.

If your app crashes without google-services.json, then nobody — including future you — can clone it and see it run. So every external integration got a mock path: no Firebase credentials means push logs a warning and returns a mock response instead of throwing. No RevenueCat key means the paywall renders with fake products.

python
if not credentials_path and not credentials_json:
logger.warning("Firebase credentials not set — push running in mock mode")
return {"mode": "mock", "recipients": 0}

The result: docker compose up, flutter run, and you have a working app in two minutes. You wire the real services when you actually need them.

You will want an admin panel sooner than you think

The first time a user emails "I can't log in", you'll be writing SQL by hand. If you're on FastAPI, sqladmin gives you a usable panel in an afternoon — user list, search, ban/activate — and you can secure it with the JWT auth you already built instead of inventing a second login system.

Worth adding from day one: a filter for soft-deleted users (otherwise they clutter every list) and a stats page. Not because the numbers are sophisticated, but because "how many people signed up yesterday" is the question you'll ask most often.

The Windows gotcha that ate an evening

Unrelated to any of the above, but it cost me hours and almost nothing is written about it: if your Windows user folder is localized — mine is Masaüstü — Gradle and Flutter's shader compiler fail on the non-ASCII character. The error message points nowhere near the actual cause.

Workaround: subst a drive letter to your project path, or move the project somewhere ASCII-only. Also, recent flutter_secure_storage versions need minSdk 23, which produces its own confusing build failure.

If you'd rather not build all of this

I packaged everything above into a starter kit — Flutter app plus FastAPI/PostgreSQL backend, with the auth, subscriptions, push, profile management, i18n and admin panel already wired together and tested end to end.

Free auth module (MIT, just the login layer): github.com/yusufkizilkan/flutter-fastapi-auth-starter
Full kit: kizilkan2.gumroad.com/l/flutter-saas-kit

But honestly, the six problems above are worth understanding whether or not you use someone else's code for them. Most of my time went into the parts nobody writes tutorials about.

What did I miss? If you've shipped a Flutter SaaS, I'd like to hear which of these bit you hardest.

I built a free full-stack auth starter so you can skip "auth week" (Flutter + FastAPI)

Yusuf kızılkan — Tue, 28 Jul 2026 23:22:55 +0000

Every side project I've started died a little during the same seven days: auth week.

You know the drill. Login screen, register screen, forgot password. JWT access tokens, refresh tokens, where do I even store these securely? Then the Google Sign-In configuration maze — SHA-1 fingerprints, two different client IDs, the OAuth consent screen. A week of boring, error-prone work before you write a single line of your actual product.

So I built the whole thing once, properly, and released it free.

What's inside

Flutter side:

Login, Register, Forgot Password and Auth Gate screens (light/dark themes, follows system)
Email/password + Google Sign-In, fully wired
JWT access + refresh tokens in flutter_secure_storage
Automatic refresh on 401 — expired tokens refresh silently, and the user only gets logged out if the refresh itself fails
Riverpod + go_router, clean feature-based architecture

Backend side (the part most starters skip):

FastAPI + PostgreSQL with /auth/register, /login, /refresh, /forgot-password, /me, /google
bcrypt password hashing, short-lived access tokens, rotating refresh tokens
Starts with one command: docker compose up
Interactive API docs at /docs out of the box (thanks, FastAPI)

Why full-stack?

Most free auth templates give you beautiful screens and leave the backend as "an exercise for the reader." Which means auth week isn't actually over — you just moved it.

This starter runs end to end: clone → docker compose up → flutter run → sign in. Real Postgres, real tokens, real error handling (wrong password shows a clean error banner, not a crash).

Two gotchas I hit (so you don't have to)

1. Non-ASCII Windows paths break the Flutter build. My desktop folder is Masaüstü (Turkish Windows). Gradle and Flutter's shader compiler choke on the ü. If your Windows is in Turkish, German, Spanish... and your project lives under a localized path, you'll hit this too. The fix (subst a drive letter + android.overridePathCheck=true) is documented in the repo's FAQ.