# Token Empire

A browser-based incremental/idle game where you manage an AI company from a garage startup to building AGI. Navigate the real tensions of the AI industry: scaling compute, training frontier models, balancing safety vs capability, hiring talent, and competing with rival labs.

**Target:** 4-8 hour single playthrough | **Platform:** Desktop browser | **Price:** Free

## Quick Start

```bash
# Prerequisites: Node.js 18+, pnpm 10+
pnpm install
pnpm dev
```

The web app starts at `http://localhost:5173` (or the next available port). The backend server starts alongside it for cloud saves and leaderboards.

## Tech Stack

| Layer | Choice |
|-------|--------|
| Frontend | React 19 + TypeScript, Vite |
| State | Zustand (slice pattern, localStorage persistence) |
| Styling | Tailwind CSS (custom dark theme) |
| Charts | Recharts |
| Backend | Hono (Node.js) |
| Database | PostgreSQL + Drizzle ORM |
| Monorepo | Turborepo + pnpm workspaces |

## Project Structure

```
token-empire/
├── apps/
│   ├── web/              # React frontend (Vite)
│   └── server/           # Hono API backend
└── packages/
    ├── shared/           # Types, constants, formatters
    └── game-engine/      # Pure TS simulation (no DOM dependencies)
```

The game engine is fully decoupled from React. It runs identically for real-time ticks, offline catch-up, and testing.

## Game Overview

### Four Eras

1. **Startup** (~30 min) — First datacenter, first model, first customers
2. **Scale-up** (~2 hr) — Growth, multiple datacenters, specializations
3. **Big Tech** (~4 hr) — Global operations, regulation, IPO
4. **AGI** (~8 hr) — Endgame push, AI agents, custom chips

### Core Loop

Buy GPUs → Allocate compute → Train models → Deploy → Earn revenue → Expand

### Key Systems

- **Infrastructure** — Datacenters across 7 global regions with different costs, latency, and risks
- **Research** — Tech tree with generation upgrades and specialization branches
- **Models** — Train, tune, and deploy models with capability scores across reasoning, coding, creative, multimodal, and agents
- **Market** — Consumer subscriptions and B2B API with token-based pricing
- **Talent** — Four departments (Research, Engineering, Ops, Sales) with hiring and morale
- **Competitors** — AI rival labs with distinct personalities that react to your moves
- **Events** — 40+ events across industry, regulatory, PR, internal, market, and geopolitical categories
- **Safety** — Tradeoff between capability benchmarks and safety; low safety risks PR disasters
- **Funding** — VC rounds from Seed to IPO with dilution mechanics
- **Achievements** — 15 milestones tracking progression

## Scripts

```bash
pnpm dev          # Start all apps in development mode
pnpm build        # Production build
pnpm typecheck    # Type-check all packages
pnpm lint         # Lint all packages
pnpm clean        # Clean build artifacts
```

## Backend Setup

The backend requires PostgreSQL for cloud saves and leaderboards. Set the connection string in `apps/server/.env`:

```
DATABASE_URL=postgresql://user:password@localhost:5432/token_empire
```

Run migrations:

```bash
cd apps/server
pnpm db:push
```

The game works fully offline without the backend — saves persist to localStorage.

## Documentation

- [Architecture Guide](docs/architecture.md) — Technical deep dive into the engine, state management, and simulation systems
- [How to Play](docs/how-to-play.md) — Player guide with mechanics, strategies, and tips

## License

All rights reserved.