Architecture case study

Animal Park

Animal Park is my own mobile game, live on iOS and Android since 2023. I build and run it end to end: the Unity client, the Firebase backend, social systems and release automation. Most of the day-to-day work now runs through AI task sessions that I coordinate and approve.

Unity/C# / IL2CPP (Android + iOS) / Addressables / Firebase Cloud Functions / Node.js 22 / Firestore / Crashlytics / TeamCity / fastlane / GitHub Actions

Live on iOS and Android. Backend details are based on the project code.All projects

Overview

The backend handles player progress, inventory and map state, public profiles, clubs, club chat, tournaments, remote configuration and environment-specific deployment.

The engineering challenge is the normal one in live games: keep iteration fast without letting saves, social systems or live configuration become unsafe or inconsistent.

  • Park view with enclosures, paths and animals
  • Tile-matching puzzle board with level goals
  • Club chat with messages from other players
  • Event map with a timed challenge
Store screenshots from the Animal Park press kit.

Requirements

Player stateSave and load inventory, map, persistent map data and user profile safely.
Social systemsSupport clubs, membership flows, roles, chat and public profile lookups.
Live operationsRemote config, server-version migrations and weekly tournament jobs.
Release safetyThree isolated environments (dev/stage/prod), emulator support, Node test coverage and CI-built, store-ready client builds.

Architecture

The client can request a change. Only the server can approve it.

A player action becomes an authenticated client request. The server validates game rules before changing shared state or rejecting an invalid request.
The phone presents the experience, but it cannot award progress or alter shared state on its own. Invalid requests leave the authoritative state untouched.

Key components

ComponentResponsibilityNotable decision
utils.onAuthedCallWraps callable functions with a uniform authentication guard.Every gameplay function returns a consistent error envelope and server time.
user-progress.jsCreate, load and save player data across user, inventory and map documents.Uses Firestore batches and a save index to reject old saves.
clubs.jsClub creation, joining, role changes, pending requests and member management.Role checks distinguish leader/admin operations from normal membership flows.
chat.jsClub-scoped chat fetch and send.Verifies the authenticated user's club before reading or writing messages.
tournaments.jsWeekly tournament creation and score reporting.Score updates run in Firestore transactions; tournament creation buckets eligible clubs.
core.jsRemote configuration fetch.Returns only newer config values by version to reduce unnecessary client updates.

Unity client & release automation

The Unity/C# client is built as IL2CPP artefacts for Android and iOS, with separate development, staging and production environments. Gameplay code is organised by domain (core simulation, level generation, online services, rewards and collection, ads, analytics and IAP, UI), with editor tests alongside. Content ships through Addressables with separate dev and production build layouts, so asset iteration does not require client releases.

The build and release path is what lets one person run the game. TeamCity drives the Unity builds through a custom editor build layer (build manifests, build tags and TeamCity service-message integration live in the project as code). fastlane owns everything store-facing:

  • Dev distribution: Firebase App Distribution with generated changelogs per build.
  • iOS: Xcode build lanes and TestFlight upload via App Store Connect API keys.
  • Android: Google Play upload and track promotion from testing to production.
  • Operations: git tagging per build and Crashlytics dSYM symbol upload, so crash reports stay symbolicated.

How I build it now

I run the game as a studio of one, with AI task sessions doing most of the implementation. One coordinator session holds the plan and starts a named worker for each outcome. No more than two outcomes are in progress at once, so I can still review everything that comes back.

Authority is written down, not implied. Workers may merge checked changes into the development branch and build a development Android version, because anything there can be reverted. Production deploys, store releases, version bumps and remote config changes still need my yes, every time.

Throughput changed quickly. After I set the pattern up in October 2026, pull requests went from #6 to #41 in three days. The harder question became what “done” means.

Implementation detail

The highest-risk backend paths are the ones where a client claims identity or ordering: chat, saves and tournament scores. Those paths use server-side membership checks, server timestamps, save-index validation and transactions instead of trusting client state.

// Score reporting is accepted only when the authenticated user
// belongs to the claimed club and the club is in the active tournament.
if (!caller || caller.userData.clubId !== request.data.clubId) {
    return utils.err("permission-denied")
}

await db.runTransaction(async (transaction) => {
    const [tournamentDoc, clubDoc, memberDoc] = await Promise.all([
        transaction.get(tournamentRef),
        transaction.get(clubRef),
        transaction.get(memberRef),
    ])
    // update tournament participant score and member score together
})

Decisions that mattered

  • “Done” means checked on a real device and in crash reporting. A crash in version 1.1.19 was missed because only the test phone’s log was read. Since then, done also includes crash reporting and the store’s pre-launch report.
  • Old saves never overwrite newer ones. Each save carries an index and the server rejects anything older instead of merging it. A phone that comes back online after a week is normal on mobile, not an edge case.
  • The server decides who belongs to a club. Chat and tournament writes check the caller’s current club on the server before anything is written. Social features are trust systems, and these checks are much harder to add after players find the gap.
  • Tournaments start in buckets. Eligible clubs are fetched in batches and each batch gets its own tournament documents, so the weekly job never loads every club into memory.
  • Tuning does not wait for store review. Remote config is versioned and the client only fetches newer values, so I can change game behaviour without a client release.

Trade-offs

DecisionWhyCost
Firebase Cloud Functions and FirestoreFast to build, good fit for mobile backend iteration and authenticated callable APIs.Requires care around query shape, transactions and document-level consistency.
Callable modules by featureKeeps progress, clubs, chat, tournaments and config understandable as separate domains.Shared invariants must be kept in utilities and tests to avoid drift.
No always-warm server for new players Keeps hosting cost in line with uneven traffic. The first sign-up can start cold, so the client waits longer for it instead.

Current state

Live on iOS and Android; the latest store release is version 1.1.20.

Lessons learned

  • AI sessions made writing code cheap. They did not make checking it cheap, so my review capacity sets the limit on parallel work, not the number of sessions.
  • Writing down what workers may do alone, and what always comes back to me, is what made it safe to let them merge.
  • Small game backends need production habits early: separate environments, tests and explicit deploy paths. I added them before players depended on them.