System Architecture
A local-first companion: the game and the web app never talk through a server in the middle. Here is how the pieces fit together, what runs where, and how your data stays on your machine.
The only channel is 127.0.0.1:8765, your own machine. No company data or save names ever leave it.
The mod only serves GET requests. There are no write operations, so your save is never touched.
It rebuilds only when asked and caches day-scoped figures, so there is no per-frame stutter.
1. The big picture
Four layers, one direction: your game state flows out to your screen. Every optional part sits beside the pipeline, never inside it.
Big Ambitions
The gameUnity + C#. Your whole empire lives in memory: cash, stores, staff, stock and buildings.
Companion Mod
The bridgeA small C# engine reads the save, turns it into JSON and serves it over localhost.
Localhost
The transport127.0.0.1:8765. Reads only, local only. The single channel between game and app.
Live HQ
The appNext.js + React. Polls the bridge, normalizes the data and renders every dashboard.
Static game data extracted from the game files.
Your own Gemini key. The browser talks to Google, only when you use the advisor.
Uncle Fred speaks through an online, serverless text-to-speech engine (free, nothing to install).
A Discord form, only when you choose to send.
2. Building blocks
The parts that make it work, grouped by where each one runs.
Telemetry engine
One shared C# engine reads SaveGameManager by reflection, caches day-scoped financials and serializes JSON with Newtonsoft.
Loopback bridge
An embedded HttpListener on 127.0.0.1:8765 answers GET and OPTIONS only, with CORS and Private Network Access headers so a secure page can reach localhost.
Two mod targets
The Steam Workshop native mod and the MelonLoader standalone compile the same engine into two DLLs, so behaviour is identical.
Live HQ frontend
Next.js App Router, React and TypeScript. One context polls the bridge, normalizes a typed state, caches it for instant reloads and feeds every view.
Game compendium
Items, businesses, buildings, districts and suppliers pulled from the game into static JSON, plus the calculation engines that use them.
Uncle Fred AI
Bring your own Gemini key. The browser sends a compact empire summary straight to Google, only while you chat with the advisor.
Online voice
Uncle Fred speaks through a serverless XTTS text-to-speech engine in the cloud (free, nothing to install), with a local fallback for development.
Reports
Bug and suggestion reports post to Discord through a bot, with a privacy-scrubbed snapshot and optional in-game diagnostics.
3. How a refresh flows
The path every refresh takes.
The game updates its in-memory state as you play.
It asks the bridge for the latest over loopback, at your chosen cadence.
Only when needed, reading the save and reusing day-scoped caches.
Serialized to JSON and returned. Nothing is written to disk.
The app normalizes, caches and re-renders the dashboards.
4. Tech stack
Runs inside the game and serves the data over localhost.
The interface you use in the browser.
Optional online extras, off unless you use them.
5. Safety & privacy
As of companion v2.9.0GET-only server
Only GET and OPTIONS exist. There are no POST, PUT, DELETE or file-write endpoints anywhere.
Zero save modification
The mod never writes to disk. Uninstall it and your save is exactly as the game left it.
Browser friendly
CORS and Private Network Access headers let the app talk to localhost from any modern browser.
Open source
The full mod source is public on GitHub for anyone to inspect. mod/AmbitionProSync
Steam Workshop
Subscribe natively on Steam, no manual file extraction. Big Ambitions Steam Workshop (Item #3793615072)
Your save file name, any account or identity (there is no login), or your game data on our servers.
While the game is running, this shows the port is bound only to your local machine:
The mod reports its version to the app. The Steam Workshop mod (BigAmbitionsCompanionMod.dll) and the MelonLoader standalone (AmbitionProSync.dll) share one engine and one version.