Dynamodb 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 2: Making It Real

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

This is part two of our three-part development journey series. Part 1 covered the foundation — standing up infrastructure and getting the first render on screen. This post covers the transition from “something renders” to “something plays.”

The period from February 14th to 17th was where the game came alive — and where most of the visual bugs lived.

The City Grid Problem (Feb 14-15)

The initial city grid was 50x50 tiles. On paper, that sounded reasonable. In the isometric renderer, it was too large — buildings were tiny, navigation was tedious, and the render performance suffered. But the bigger problem was visual.

Buildings at the grid edges clipped into empty space. The isometric diamond layout meant the rectangular browser viewport showed the diamond’s corners — ugly gaps of nothingness. And the cloud overlay we’d been struggling with was still dominating the view.

The fix came in stages across multiple PRs:

Resize to 20x20 — a dramatically smaller grid that kept buildings visible and navigation manageable
Add grass border tiles — filled the area beyond the grid diamond so the viewport always shows terrain
Clamp the camera — prevented scrolling beyond the rendered area
Storm cloud rework — the exterior overlay got completely reworked

The Storm Cloud Saga

The cloud overlay deserves its own section because it consumed 6 PRs over two days. The idea was simple: the area outside your built city should have ominous storm clouds, creating a “fog of war” effect that makes the playable area feel like a clearing in the darkness.

The first implementation rendered clouds over the entire map and then punched a hole for the city. It looked like this:

The iteration went:

Add storm cloud overlay — initial implementation, way too thick
Thicken storm clouds and increase lightning — made it worse, but established the aesthetic direction
Rebalance for 20x20 grid — scaling adjustment after the grid resize
Fix city bleed — storm effects were bleeding into the city area
Replace clipPath with saveLayer+dstOut — the rendering approach itself was wrong. clipPath in Flutter’s canvas wasn’t compositing correctly with the tile renderer. Switching to saveLayer with Porter-Duff dstOut compositing mode fixed the bleed
Fix hard edge at map corners — the final cleanup

The progression from “cloud soup” to “atmospheric border” was a real lesson in iterative rendering. Each PR fixed one thing and revealed the next problem.

Building Placement and the Real Backend

With the grid sorted, we wired up actual building placement. This required changes across four repos in sequence:

BackendCommon: Add building data models and road segment data
BackendApi: Add building placement and upgrade endpoints with DynamoDB storage
OperationalTools: Add city-buildings ops command for debugging
FrontEndClient: Wire up placement and upgrade API calls

The cross-repo dependency chain meant this feature took a full day even though the individual changes were straightforward. The NuGet pipeline adds latency — merge BackendCommon, wait for CI to publish, then update the other repos.

Hardcoded IDs were another pattern that needed systematic removal. The city view initially used city-001 everywhere. The troop screens hardcoded city-001. World endpoints hardcoded world-001. Each hardcoded value was a separate PR to replace with the real ID from the player’s session.

The UI Overhaul (Feb 16)

February 16th was almost entirely a frontend day — 25 PRs merged in the FrontEndClient alone. This was the day the game started looking like a game.

Management screens: Resources, Buildings, and Research got dedicated tabs in a new Management screen. The bottom navigation grew from City/Map/Troops/Guild/More to City/Map/Manage/Guild/More.

The carousel battles: The build panel originally used a dropdown to select buildings. We replaced it with an image carousel showing building previews. This seemingly simple change spawned 5 PRs:

Replace dropdown with carousel
Fix navigation buttons and image sizing
Fix clipping on mobile viewports
Fix the build button being hidden behind the panel
Final height and layout adjustments

Gesture handling: Adding pinch-to-zoom to the isometric maps created a cascade of input conflicts. The tile tap handler consumed touch events that the zoom handler needed. The zoom gesture interfered with panning. Pan conflicted with tap detection. This produced 5 bug-fix PRs in sequence — each fixing one gesture interaction and breaking another, until the gesture recognizer configuration was right.

The mobile experience: The game runs in Safari on iOS as a progressive web app.

Mobile brought its own issues — the PWA standalone mode needed fixes to hide browser chrome, and touch gesture handling behaved differently than mouse events.

Token Management

One practical problem: JWT access tokens expire after 6 hours. When a player’s session runs long enough, API calls start returning 401s. We added automatic token refresh — when a 401 comes back, the Dio HTTP interceptor transparently refreshes the access token using the stored refresh token and retries the original request. The user never sees the expiration.

Observability

On the backend side, we added Embedded Metric Format (EMF) logging to the BackendApi. Every API request now emits structured metrics to CloudWatch — request count, latency, and status code breakdown (2xx, 4xx, 5xx). Getting EMF right took 4 PRs:

Add EMF request metrics middleware
Fix to emit single structured object (not multiple)
Fix Dimensions array format per CloudWatch spec
Align metric names with property names

The CloudWatch EMF specification is finicky about formatting. Small deviations cause metrics to silently not appear in CloudWatch — no error, just missing data. Each fix was discovered by checking CloudWatch and finding empty graphs.

Stats: Days 6-9 (Feb 14-17)

Metric	Value
PRs merged	94
Frontend PRs	62
Backend PRs	22
City grid iterations	3 (50x50 → 20x20 → final layout)
Storm cloud PRs	6
Gesture handling bug fixes	5
Carousel UI iterations	5
EMF metrics iterations	4
Hardcoded ID replacements	5
New API endpoints (real, not stubs)	18

Code Growth (Feb 14-17)

Language	Lines Added	Total
Dart	~12,500	~26,500
C#	~9,200	~15,700
TypeScript	~100	~625
Markdown	~8,000	~38,000
JSON	~2,000	~20,000

Feature Velocity

Day	PRs Merged	Key Features
Feb 14	16	Server-backed maps, city resize, iOS PWA, post-login flow
Feb 15	28	Storm clouds, road rendering, building placement, world simulation phase 1, mock removal
Feb 16	32	Management screens, carousel, pinch-to-zoom, token refresh, EMF metrics, troop training UI
Feb 17	18	Research trees, building definitions, worker staffing, tile bonuses, blog launch