Add README and documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-24 18:10:43 -04:00
parent 0ff8a32b95
commit 6c7348f924
3 changed files with 639 additions and 0 deletions
@@ -0,0 +1,103 @@
+# AI Tycoon
+
+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
+
+```
+ai-tycoon/
+├── 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/ai_tycoon
+```
+
+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.