Age of New Worlds — Architecture Atlas

AoNW<br>Architecture Atlas<br>repo: ernestwisniewski/aonw

Source branchmain

Snapshot2026-08-03

StackFlutter · Flame · Serverpod

CoreDart-only

Views

Legend

Client/UI<br>Domain<br>Server<br>Data/protocol<br>Quality<br>Migration

Important: the atlas separates the current architecture from accepted ADR targets. A “migration” status means the boundary already governs new code, although not every transitional exception has reached zero.

AGE OF NEW WORLDS · ARCHITECTURE ATLASRepository architecture mapThe domain core is shared by local play, AI, replay, and the authoritative server.CURRENT + ACCEPTED TARGETFLUTTER / FLAME CLIENTUI, controls, adapters, and renderingAONW_CORE — AUTHORITATIVE COREPure Dart; deterministic rules and contractsSERVERPOD / MULTIPLAYERAuthentication, ordering, persistence, and recipient viewsSURFACEFlutter UI + RiverpodScreens, controllers, providers, routing, and input.INTERACTIONGameIntentResolverSeparates UI gestures from rule-changingcommands.APPLICATIONUse cases + portsOrchestrates sessions, saves, clocks, IDs, andtransport.LOCAL ADAPTERLocalCommandResolverBuilds context, calls the engine, and projects UIeffects.PRESENTATION Flame layers" style="font-size: 16px;">RenderState -> Flame layersGrid, units, cities, fog, overlays, camera, andanimation.EDITORMapDraft (mutable)Only mutable map; frozen before gameplay.INPUTDomainCommandFramework-free request tochange domain rules.TRUSTEDSystemCommandTrusted timeout, finalization, andsystem actions.WIREProtocol DTOs + codecsVersioned command, event,snapshot, ACK, and match envelopes.IMMUTABLEDomainStateSingle authoritative rules state: turns,players, units, cities, fog, research,diplomacy, and victory.…ore/lib/game/domain/state/domain_state.dartSINGLE RULES ENGINEGameEngineDeterministic dispatcher for 10 command families: movement,combat, cities, production, workers, trade, research, diplomacy,and turns.migration in progress…ib/game/application/engine/game_engine.dartWORLDWorldMap + HexCoordImmutable, validated once, with O(1) tilelookup.ADAPTERAI planning + MCTSProduces DomainCommand and simulates throughGameEngine.PERSISTENCE ENVELOPECanonical snapshotMetadata + full DomainState + one eventoffset.current…e/domain/state/canonical_game_snapshot.dartOUTPUTGameEngineResultAccepted/rejected snapshot, events, movement evidence, andpresentation facts.being narrowedGENERATEDGenerated Serverpod clientTyped bridge between Flutter and Serverpod endpoints.ENTRYPOINTAuth + MultiplayerEndpointLogin, lobby, snapshot/event reads, and live stream.ORCHESTRATIONRealtimeMatchHubMatchmaking, lifecycle, queries, broadcast, andconnections.AUTHORITATIVE ADAPTERServerCommandReducer / EngineValidates wire and context, then calls the sharedGameEngine.PRIVACY BOUNDARYRecipient projectionFog and audience redaction; full route or explicit [].RUNTIMEPostgreSQL + RedisSnapshots, events, offsets, match metadata, and Serverpod infrastructure.DomainCommandinteraction onlyfreeze()project + rendergenerated DTOssame engineaccepted resultprojected wirepersist firstArrows show dependencies and authoritative change flow; presentation remains outside DomainState.branch main · reviewed 2026-08-03

AGE OF NEW WORLDS · ARCHITECTURE ATLASOne command, end to endFrom UI input to a deterministic result and exact animation—locally or online. ENGINE -> PROJECTION" style="font-size: 9.5px;">COMMAND -> ENGINE -> PROJECTIONINPUT1 · UI gesture / actionTap, click, shortcut, gamepad, orautomation.PRESENTATION ONLY2 · GameIntentSelection, focus, targeting mode, andlocal workflow.BOUNDARY3 · Intent resolutionUpdates InteractionState and may emit aDomainCommand.AUTHORITATIVE INPUT4 · DomainCommandComplete immutable intent to changedomain state.PORT5 · Execution adapterLocalCommandResolver or versioned Serverpod transport.LOCAL PATHOffline, hot-seat, and in-process AINETWORK PATHServerpod remains authoritative for ordering and persistenceADAPTERLocalCommandResolverBuilds GameEngineContext with map,ruleset, actor, and tick.PURE RULESGameEngine.applyUses the same validation and reducerchain as the server.RESULTAccepted / rejectedSnapshot, domain events, movementevidence, and UI facts.PROJECTIONGameClientStateDomainState + client-localInteractionState; no duplicate rule state.STRICT CODECWireCommand + message idv, tick, turn, lastSeenOffset, andclientMessageId.TRANSPORTBidirectional streamsendCommand → ACK; reconnect fromthe latest offset.ORDERINGServer adapterAuth → validate →ServerCommandReducer → sharedGameEngine.DURABLEPersist + project + deliverPersist snapshot, event, and offsetbefore ACK and projected broadcast.localonlinesame GameEnginesnapshot / eventNever sent over the wireGameIntent, camera, open panels, focus, renderer cache, and local UI effects.Deterministic contractEqual snapshot, command, and context produce equal output; rejection preservesinput state.Exact movement presentationThe client animates authoritative movementExecutions and never reconstructs a...