Github-Actions on Worlds of the Next Realm - Dev Blog

The Development Journey, Part 1: Nine Days from Zero

Tue, 17 Feb 2026 00:00:00 +0000

This is the first of a three-part series covering the development journey of Worlds of the Next Realm so far. In this post, we cover the foundation: standing up infrastructure, building the first services, and getting something on screen.

The timeline is aggressive. The first commit landed on February 8th, 2026. Nine days later, we had 11 repositories, a live beta environment, a working authentication system, a Flutter web client with isometric tile maps, and a backend serving real game data from DynamoDB.

Day 1-2: The Foundation Sprint (Feb 8-10)

Everything started with the Flutter client and the AWS infrastructure.

The FrontEndClient repo received 12 PRs in the first two days. We scaffolded the entire application structure — domain models, theming, navigation, mock backend layer, and all the core UI screens: troops, leaders, research, guild, inventory, expeditions, barter, events, settings, chat, shop, and AI companion. Most of these screens were populated with mock data, but the architecture was real — Riverpod state management, GoRouter navigation, Dio HTTP client with interceptors.

The most significant piece was the isometric 2.5D tile map renderer built on the Flame game engine. This would become the city view and world map — the visual heart of the game.

Simultaneously, the Infra repo went up with CDK stacks for the VPC, DynamoDB tables, Application Load Balancer, and CloudFront distribution. We deployed the BackendApi on Lambda behind API Gateway, and the NotificationService and WorldSimulation on Fargate.

All three backend services had working CDK deployments by the end of day 2. The CI/CD pipelines were live — every push to main deployed to beta automatically.

Day 3-4: The Data Layer (Feb 11-12)

This is where BackendCommon became the backbone of the project.

We built a generalized DynamoDB data store abstraction — a single-table design where every game entity (players, cities, buildings, resources, troops, worlds) lives in one table with partition key patterns and GSIs for alternate access patterns. The data store handles serialization, optimistic concurrency via version IDs, and batch operations.

The DynamoDB schema went through several iterations during these two days:

Started with a partition key + sort key design
Removed the sort key
Added GSI1
Added GSI2
Restored the sort key and added GSI1
Recreated the table as PK-only with GSI1

That’s 6 PRs in the Infra repo just iterating on the table schema. Each change required coordinating across BackendCommon (data models), Infra (CDK table definition), and the services that read the data. This is one of the costs of a multi-repo architecture — schema changes ripple across repositories.

The OperationalTools CLI also came to life during this phase: create-user, load-game-data, generate-map, and bootstrap-world commands. These tools are essential for populating the game world with data — definition files for buildings, troops, resources, and research loaded from JSON into DynamoDB.

Day 5: Authentication and API Wiring (Feb 13)

February 13th was one of the busiest days of the project. Across all repos, we merged PRs covering:

Authentication service: Full username/password auth with RS256 JWT tokens, Argon2id password hashing, family-based refresh token rotation, and JWKS endpoint for public key distribution. The master encryption key went through its own evolution — first as a CDK context value, then moved to AWS Secrets Manager for proper secret management.
JWT middleware in BackendApi: All API endpoints now verified authentication tokens. We added request/response models for all 22 planned endpoints and created stub handlers for each one.
Frontend auth integration: The Flutter client was hooked up to the real authentication service. The mock login button was removed. Real JWT tokens flowed from login through to API calls.
Structured logging: Every service got consistent JSON logging — critical for debugging in a distributed system where you need to correlate requests across Lambda, Fargate, and CloudWatch.
Security hardening: CloudFront origin verify headers and WAF rules on the ALB to prevent direct access bypassing the CDN.

This was also the day of the “README wave” — every repo got a README, documentation links, and design doc references. Housekeeping, but important for a multi-repo project where anyone (human or AI) needs to find their way around.

The First Render

Getting the isometric city to render with real data in the browser was the first real milestone. The early versions had… issues.

The bottom navigation bar icons were missing because of how Flutter web packages and deploys JSON-declared assets. It took a dedicated fix to properly deploy subdirectory JSON assets to S3.

The cloud overlay — intended to obscure the city exterior — was rendering far too aggressively. The terrain and buildings underneath were completely invisible. This would take several more days and multiple PRs to get right.

What We Learned

Multi-repo coordination is expensive. A schema change in DynamoDB touches Infra (CDK), BackendCommon (models), BackendApi (endpoints), OperationalTools (data loading), and sometimes the FrontEndClient (API contracts). The NuGet package pipeline adds latency — you merge a BackendCommon PR, wait for CI to publish the package, then update dependent repos. We ended up with explicit rules: create the BackendCommon PR first, wait for CI, then create dependent PRs.

Mock-first works. Building the entire Flutter client with mock backends first meant we could iterate on UI and navigation without waiting for the real APIs. When the APIs were ready, we swapped in real repositories one at a time.

CDK schema iteration is painful. Six PRs to get the DynamoDB table right. Each one required a CDK deploy, which means CloudFormation stack updates, which means waiting for DynamoDB table operations to complete. Some of these were destructive — dropping and recreating the table. In a production environment, this would require careful migration planning.

Stats: Days 1-5 (Feb 8-13)

Metric	Value
Repositories created	11
PRs merged	143
Commits	~310
Services deployed	5 (BackendApi, AuthService, NotificationService, WorldSimulation, FrontEndClient)
CDK stacks	5 (VPC, DataStore, Web/ALB, CloudFront, PipelineOIDC)
DynamoDB schema iterations	6
Backend endpoints stubbed	22
Flutter screens built	17
NuGet packages published	3 (BackendCommon, BackendCommon.Cdk, BackendCommon.Testing)
CI/CD pipelines	8 (one per deployable repo)

Code Written (as of Feb 13)

Language	Lines	Purpose
Dart	~14,000	Flutter client
C#	~6,500	Backend services + shared libraries
TypeScript	~520	CDK infrastructure
Markdown	~30,000	Design docs, game data, READMEs
JSON	~18,000	Game definitions, config

The Development Journey, Part 3: What We Learned

Tue, 17 Feb 2026 00:00:00 +0000

This is the final part of our three-part development journey series. Part 1 covered the foundation. Part 2 covered building the game features. This post covers what we learned — about the process, about AI-assisted development, and about what the numbers actually tell us.

The Process Evolved

When the project started on February 8th, the process was simple: write code, push to main. By February 17th, we had a structured system of rules, templates, and guardrails. Every rule exists because something went wrong.

Workspace Boundaries

The rule: Never look in or modify files above the repository root. Each workspace is independent.

Why it exists: In a multi-repo project with an AI coding assistant, context bleed is a real risk. Claude might read a file in BackendApi and then make assumptions about BackendCommon based on what it saw — assumptions that could be wrong if the repos are at different points in their development. Keeping each workspace isolated forces explicit cross-repo coordination through published packages and documented interfaces.

NuGet Versioning

The rule: Never manually change <Version> in .csproj files. Never run dotnet nuget push. CI handles all versioning and publishing.

Why it exists: The BackendCommon package is consumed by 4 other repos. The CI pipeline uses github.run_number as the patch version, giving every build a unique version. Early in the project, manual version bumps caused conflicts where two builds produced the same version number. The fix was simple — take humans and AI out of the versioning loop entirely.

The cross-repo workflow is now explicit: create the BackendCommon PR first, wait for CI to publish the new package version, then create PRs in the dependent repos. The dependent repos use 0.1.* wildcard references so they pick up new patches automatically.

PR Workflow

The rule: Every PR requires three things: the PR itself, a review comment covering reasoning and concerns, and a session stats comment with token usage and interaction quality metrics.

Why it exists: The stats comment requirement was added after several PRs were created without tracking information. Since the human-AI collaboration is itself something we’re studying, losing that data means losing insight into what’s working. The “never defer” requirement prevents the stats from being forgotten — they must be posted in the same step as creating the PR.

The “Open Source” Mistake

One of the clearest examples of AI needing oversight: in our first blog post, Claude described the project’s code as “open source.” It’s not. This is a commercial game that will be monetized. Claude defaulted to “open source” framing because that’s the most common pattern in developer blogs on GitHub.

The fix was twofold: correct the blog post, and add an explicit rule to CLAUDE.md stating this is a commercial project. Rules like this are how you calibrate AI behavior — not through hoping it gets the context right, but through explicit documentation.

Debugging Patterns

Nine days of rapid development produced a collection of debugging patterns — things that went wrong and how we fixed them.

CDK and AWS

OIDC Token Expiry: GitHub Actions OIDC tokens expire after about an hour. If a CDK deployment waits too long for ECS service stabilization (which can happen when health checks fail), the token expires mid-deploy and the stack gets stuck. The fix: use cancel-update-stack to trigger a faster rollback instead of waiting.

ALB Outbound Rules: CDK defaults ALB security groups to allowAllOutbound: false. When Fargate targets are in a different CDK app, health checks time out with Target.Timeout errors. The fix is explicit: alb.connections.allowToAnyIpv4(ec2.Port.allTraffic()). This was painful to debug because the ALB appeared healthy — it just couldn’t reach the targets.

S3 BucketDeployment Pruning: Multiple BucketDeployment constructs pointing at the same S3 bucket will delete each other’s files unless you set prune: false on all of them. The Flutter web build and the JSON asset definitions were in separate deployments, and one kept deleting the other.

CloudFormation Stack States: After a failed deploy, the stack enters UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS. You cannot deploy again until it reaches UPDATE_ROLLBACK_COMPLETE. This can take several minutes. We learned to wait rather than repeatedly retry.

Flutter Web

Asset deployment: Flutter web packages certain assets (like Material icons) via JSON manifests. If the S3 deployment doesn’t include subdirectory JSON assets, icons render as blank squares. This showed up as missing navigation icons in the first deployed build.

Gesture conflicts: The isometric tile maps use tap detection for selecting tiles and pinch-to-zoom for camera control. Flutter’s gesture arena system means only one gesture recognizer wins per pointer event. Getting tap, pan, and pinch to coexist required careful configuration of GestureDetector and InteractiveViewer — 5 PRs of trial and error.

Cache busting: The first approach used query parameters (flutter_bootstrap.js?v=timestamp) but browsers and CDNs handle query-param caching inconsistently. We switched to content-hash file renaming — the build step renames files with their hash, guaranteeing that changed content gets a new URL.

The Troop Training UI

The troop training screen is a good example of iterative design working well. It went through a complete transformation:

The original design used a dropdown to select troop type and a number input for quantity. Through iteration:

The dropdown became category filter tabs (Battle, Gathering, Mining, Farming, Factory, Labor, Magical)
The number input became a slider with preset buttons (10, 50, 100)
Troop artwork was added via carousel
Cost breakdown shows per-unit and total cost
Training time is calculated dynamically

Each step was a separate PR. None were planned as a sequence — each iteration responded to what the previous version looked like when actually used.

Data-Driven Everything

A recurring theme in the later development was replacing hardcoded values with data-driven definitions.

ResourceType: Started as a Dart enum. Replaced with a string that maps to server-defined resource definitions. This allows adding new resource types without a client update.

BuildingType: Same pattern — started as an enum, replaced with data-driven definitions loaded from the server’s building definitions endpoint.

Research tracks: Originally linear tracks (each research unlocks the next in sequence). Replaced with a tree structure where research nodes can have multiple prerequisites and unlock multiple children.

The pattern is always the same: start with the simplest thing that works (an enum), discover you need more flexibility, replace with server-defined data. This is pragmatic engineering — you don’t build the flexible system until you need the flexibility.

The Resource Icon Problem

Even at the end of 9 days, not everything is polished. The resource management screen still has missing icons for most resource types:

The game asset library has thousands of icons, but the mapping from resource definition to icon asset isn’t complete. This is the kind of polish work that takes time but isn’t blocking — the game is functional, the icons are a visual gap.

Honest Assessment

Nine days is a short time. What we have is a vertical slice — infrastructure to UI, real data flowing through real services, deployed to a real AWS environment. But it’s not a game you’d want to play yet. Major systems are still stub implementations. Combat doesn’t resolve. Guilds aren’t functional. The marketplace doesn’t exist. The AI companion is a configuration screen with no backend logic.

The AI-assisted development approach made the foundation phase dramatically faster. Scaffolding 11 repos with CI/CD, CDK stacks, data models, and Flutter screens in under a week would have been months of solo work. But the speed came with a cost — every line needed review, some assumptions were wrong (like the “open source” framing), and debugging AI-generated code requires understanding code you didn’t write.

The value is real. The risks are real. And we’re 9 days in.

Project-Wide Stats (Feb 8-17, 2026)

Development Activity

Metric	Value
Calendar days	9
Repositories	11
Total commits	477
Total PRs merged	237
Avg PRs per day	26
Most active day	Feb 16 (32 PRs)
Avg commits per day	53

PRs by Repository

Repository	PRs	Focus
FrontEndClient	80	Flutter game client
BackendApi	40	Game API endpoints
BackendCommon	31	Shared libraries
Infra	19	AWS infrastructure
Documentation	18	Design docs, game data
OperationalTools	17	CLI ops tooling
AuthenticationService	11	JWT auth service
WorldSimulation	9	Event processing engine
NotificationService	8	Real-time notifications
Blog	2	This site
Assets	2	Game artwork

Codebase Size

Language	Files	Lines	Purpose
C#	226	15,720	Backend services, shared libs
Dart	190	26,533	Flutter game client
TypeScript	11	625	CDK infrastructure
Code subtotal	427	42,878
Markdown	65+	38,000	Design docs, game data, READMEs
JSON	50+	20,000	Game definitions, config
Total	540+	100,000+

Services Deployed

Service	Runtime	Deployment
BackendApi	.NET 8 Lambda	API Gateway
AuthenticationService	.NET 8 Lambda	API Gateway
FrontEndClient	Flutter Web	S3 + CloudFront
NotificationService	.NET 8 Fargate	ALB
WorldSimulation	.NET 8 Fargate	ECS

Game Features Implemented

Feature	Status
Authentication (login, register, JWT refresh)	Complete
City view with isometric rendering	Complete
World map with tile data	Complete
Building placement and upgrades	Complete
Resource tracking and definitions	Complete
Troop training UI	Complete
Research tree system	Complete
Management screens (Resources, Buildings, Research)	Complete
EMF metrics and observability	Complete
Operational tooling (user/data/map management)	Complete
Combat resolution	Stub
Guild system	Stub
Marketplace	Stub
AI companion logic	Stub
Notification delivery	Framework only

Process Artifacts

Artifact	Count
CLAUDE.md rules documents	3 (root, OperationalTools, Blog)
CI/CD pipelines	8
NuGet packages maintained	3
Design documents	17 (HLD, 10 API LLDs, data model, simulation, notifications, Flutter, auth)
Game definition JSON files	20+
Documented debugging patterns	8