app

app is a web-first, mobile-ready Expo + TypeScript foundation for an open-source turn-based fantasy strategy game. The repository is set up so we can prototype quickly in the browser today without giving up a clean path to Expo-powered mobile builds later.

Architecture

• app/ is the Expo project and owns routing, screens, UI, app state, config, and platform helpers.
• core/ is pure TypeScript game logic. It can be imported by app/, but it must never import React, Expo, Zustand, router files, or other UI code.
• docs/ holds ADRs, game design notes, and agent guidance.
• .github/ contains the issue template, pull request template, and CI workflow.

Expo Structure

• Thin Expo Router files live in app/app.
• Real screen implementations live in app/screens.
• Zustand stores live in app/features.
• Localization state and translation tables live in app/features/localization.
• Reusable UI lives in app/components.
• Small app helpers live in app/utils.
• White-label brand and publishing values live in app/config.

White-Label Setup

Copy app/.env.example to app/.env and fill in any values you want to customize. The Expo config reads:

• app name
• slug
• scheme
• shared app identifier used for both iOS and Android
• primary and accent colors
• publisher/support/legal links

No real secrets are committed. In GitHub Actions, the same EXPO_PUBLIC_* values should be added as repository secrets so CI can typecheck, test, and export the web build. Use EXPO_PUBLIC_APP_ID once and the app config applies it to both ios.bundleIdentifier and android.package.

Local Commands

Run everything from the repository root:

npm install
npm run typecheck
npm test
npm run app:web
npm run app:ios
npm run app:android

Testing

• vitest runs fast unit tests for pure core/ modules.
• jest-expo runs component tests for reusable app UI and screens.

Architecture Rules

• app may import core
• core must never import app
• app/app files stay routing-only
• game logic stays in core
• stores stay in app/features
• brand values come from config/env, not hardcoded screen strings

Multi-Agent Workflow

Use GitHub Issues with the Agent Task template to define scope, limits, and acceptance criteria. Each implementation should land in a focused pull request that references the issue, records the owning agent, and confirms the architecture checklist in .github/pull_request_template.md.