EigenInteractive platform

EigenInteractive is a platform for building authoritative, turn-based games: game authors write deterministic TypeScript rules, the server owns sequencing and persistence, and generated Dart APIs plus the Flutter runtime deliver typed game sessions to Android and the web.

This is the canonical implementation repository. The packages and documentation are published, but the platform remains pre-1.0 and has no production game or backward-compatibility commitment yet.

Repository layout

Path	Responsibility
server/	Rules SDK, authoritative kernel, Cloudflare Worker server, testkit, scaffolder, and generated Dart HTTP API
dart/	Pure Dart client runtime and development-only contract generator
flutter/	Embeddable, provider-neutral Flutter integration and example game
shell/	Complete first-party Flutter application shell and product flows
firebase/	Optional Firebase Auth, telemetry, crash reporting, push, and configuration adapter
web/	Game-implementor documentation, generated API reference, and documentation Worker
docs/architecture/	Accepted architecture decisions and current status
tool/	Whole-repository validation tools

The three component histories were imported without squashing. Their original repositories are archived as readable history; all active work belongs here. The exact imported commits are recorded in 0000-monorepo-import; package versions live in the pubspecs and package.json files that declare them.

Getting started

Use the Node version in server/.nvmrc, pnpm 11.20.0, the Flutter version in flutter/.fvmrc, and JDK 21. Install each component's dependencies from its own dependency root:

(cd server && pnpm install --frozen-lockfile)
(cd web && pnpm install --frozen-lockfile)
(cd dart/eigen_client && dart pub get)
(cd dart/eigen_codegen && dart pub get)
(cd flutter && flutter pub get)
(cd shell && flutter pub get)
(cd firebase && flutter pub get)
(cd flutter/example && flutter pub get)

Run the full cross-platform gate before handing off a change:

./tool/check.sh all

For faster iteration, pass manifest, server, flutter, web, or scaffold instead of all. The full gate also checks generated contracts and package contents, tests the Flutter package on the Dart VM and Chrome, builds the imported example and documentation for web, and validates a freshly scaffolded game with release Android and web builds.

Architecture and documentation

The accepted design lives in docs/architecture/. A protocol or game-contract change is one platform change: server behavior, generated Dart types, Flutter runtime behavior, examples, and documentation must land together and pass the same commit gate.

The current game-implementor documentation is published from this repository at eigeninteractive.com. The accepted architecture records are normative for new platform work. Maintainer-only upstream constraints are tracked in docs/blockers.md.

CI and releases

Pull requests to main run the platform workflow in checks.yml. Its contracts, server, Flutter, documentation, and scaffold checks run in parallel, then report one stable check result. The repository ruleset requires that result before a pull request can be squash-merged. The resulting main commit is checked again as the hard release boundary. See rulesets for the exact policy. Documentation-only pull requests take a conservative fast lane through contracts and the documentation build. Changesets' generated version PR uses the same lightweight checks because both the source and final merged main commits receive the complete gate. npm packages use Changesets; one post-gate coordinator creates namespaced Dart tags, and each Dart package retains its own pub.dev publishing workflow. Publishing uses registry trusted publishing with GitHub OIDC and environment-bound npm / pub.dev identities, so no registry token is stored in the repository and publishing starts automatically after the release checks pass.

The exact registry settings, routine release flow, first-cutover sequence, and failure recovery are documented in docs/operations/releases.md.

Contributing and license

Read CONTRIBUTING.md and the nearest AGENTS.md before changing a component. Report vulnerabilities privately as described in SECURITY.md. EigenInteractive platform source is available under the MIT License.