# BaoLife - Project Status

**Last Updated:** 2026-06-02

> **Current initiative:** Release hardening. The MVP plumbing is done; work is now organized as a stack of autonomous GoalBuddy campaigns driving toward a release-readiness bar measured on four dimensions — **Fun / Playable / Complete / Releasable** (see [Release Readiness](#release-readiness) below). The apex board is `docs/goals/baolife-release-ready/`.
>
> Historical MVP design: [plans/2026-04-13-baolife-mvp-completion-design.md](./plans/2026-04-13-baolife-mvp-completion-design.md) and [plans/2026-04-13-baolife-mvp-implementation.md](./plans/2026-04-13-baolife-mvp-implementation.md).

## Architecture Overview

| Component | Technology | Status |
|-----------|------------|--------|
| **Backend (Production)** | Node.js + TypeScript (`server/`), run via `tsx src/index.ts` | Deployed — `baolife-websocket.service` on `lichun-master` |
| **Backend (Legacy)** | Python (`ws/`) | Reference only; NOT running in production |
| **iOS app** | SwiftUI (`ios/`) | Active development — MVP target platform |
| **Android app** | Kotlin + Compose (`android/`) | Feature parity ~85%; deferred to v1.1 (post-MVP) |
| **Web frontend** | — | Deleted 2026-04-13 (was `index.html` + `main.js`) |
| **Legacy PHP API** | — | Deleted 2026-04-13 (was `api/`, replaced by Node push service) |
| **Database** | MySQL `lifesim` on localhost | Shared, stable |

## TypeScript Backend (`server/`)

Primary development target. ~230 source files, 151 test files, **1718/1718 tests passing** (last verified green 2026-05-29, tsc clean). Deploys to production via push-to-main webhook.

### Structure

```
server/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Environment-based config
│   ├── server/               # WebSocket server, dispatcher, registry
│   ├── game/                 # PlayerSession loop, BatchedUpdate, EventRegistry
│   ├── handlers/             # 30+ WebSocket command handlers
│   ├── models/               # Player, Person, MessageEvent, Question
│   ├── events/               # 200+ life events (14 categories)
│   ├── services/             # 13 service modules (dating, jobs, health, retention, monetization, NPCs, AI, ...)
│   ├── database/             # MySQL pool, player CRUD, conversations
│   ├── auth/                 # JWT
│   ├── monetization/         # Diamonds, energy refills, time skips
│   └── monitoring/           # Performance, health checks, rate limiting
└── tests/                    # Vitest unit + integration tests (64 files)
```

### Running

```bash
cd server
npm install
npm run dev      # Development with hot reload (tsx watch)
npm run build    # Optional: emit dist/ for local npm start. NOT used by production.
npm test         # Vitest full suite
```

### Feature status

**Done:**
- Game loop with time simulation and batched updates
- Event system (200+ events across 14 categories)
- Player state management and save/load
- AI conversations (multi-provider: OpenAI / Together / Mistral / OpenRouter)
- Conversation memory, fact extraction, summarization, token budgeting
- Authentication (JWT)
- Rate limiting, monitoring, structured logging
- Push notifications (APNs HTTP/2, stub mode fallback)
- Weather system (daily roll, seasonal probabilities)
- Retention: 40+ achievements, daily rewards, daily quests, tutorial flow
- Monetization: diamond economy, energy refills, time skips, 5 IAP packs
- Dating: compatibility, swipe matching, date activities
- Education: school/college catalogs, GPA tracking
- Health: conditions, habits, death
- Jobs: 26 occupations × 5 levels
- NPC daily schedules and location-based interactions

**Shipped since MVP (release-hardening campaigns):**
- Career progression wired into both loops (was dead code; salary now climbs) — `db3dd13b`
- Online/offline loop parity: weekly romance + GPA drift, offline milestone credit — `322b9c33`
- `straight_a` achievement made reachable (GPA threaded through graduation lifecycle) — `08065b1e`
- Headless lifetime economy simulator with real career progression + per-age income/net-worth curve
- Content-safety: all romance gated to 18+ both parties (App Store risk closed) — `98bf9d1a`
- Money-affordability gate on event/dilemma choices + soft-lock fix — `6eb29958`, `8c759cef`
- Real account deletion (Apple 5.1.1) + cancel-on-login + reachable Settings hub — `4d1af840`, `78a0793e`, `6bf7860b`
- Daily-quest wiring (dead quest types fixed/pruned) — `e65c8835`
- Env-gated IAP receipt validation + grounded iOS privacy manifest — `b33bb862`

**Resolved:** architectural issue C1 (function-based question events couldn't deliver positive rewards) — fixed in the v2 EventRuntime; regression test in place.

**Remaining gaps:** see [Release Readiness](#release-readiness).

## iOS App (`ios/`)

316 Swift files, 13 feature modules, full cozy design system, onboarding, GDPR flows, in-app purchases.

**Test scaffolding present:**
- `lichunWebsocketTests/` (unit): AnalyticsManager, EventV2 decoding/rendering/response, ToastManager, WebSocketService
- `lichunWebsocketUITests/` (UI automation): ActivityEnrollment, Onboarding, PurchaseFlow, LaunchTests

**Recent UX work (2026-05):**
- Collapsing-hero header redesign (seasonal scene + clock + frosted control tray; collapses on Home scroll, compact elsewhere)
- Sunrise splash redesign (replaced the heart "BaoLife" splash; storyboard + animated SwiftUI overlay)
- Micro-animation + haptic polish pass — `650e20b6`
- In-app validation loop fixed Health=0, GPA scale, and dilemma cost-currency display bugs

**Gaps:**
- No snapshot tests for screens (`swift-snapshot-testing` not yet added)
- UI test coverage is thin — doesn't exercise long sessions or full onboarding → save → relaunch → continue
- Surfaces not yet hands-on driven in-app: Messaging deep-dive, Dating actions (Date/Gift/Chat), daily rewards/quests UI, "Do an Activity" loop

See [ios/CLAUDE.md](../ios/CLAUDE.md) for iOS architecture.

## Android App (`android/`)

167 Kotlin files, ~85% iOS feature parity. **Deferred to v1.1.** Known issues on the backlog: 4 memory leaks (CoroutineScope), 11 empty WebSocket handlers, money-as-Int type bug. Will be addressed after iOS ships to TestFlight.

## Production

**Host:** `lichun-master` (GCE, Debian 11, us-central1-c)
**Path:** `/var/www/lichun.app/lichun`
**Service:** `baolife-websocket.service` (systemd, runs as `www-data`)
**Backend:** TypeScript, run directly via `node_modules/.bin/tsx src/index.ts` (no build step)
**Webserver:** Apache 2 (`/etc/apache2/sites-enabled/lichun.app-le-ssl.conf`) — proxies `/wss/` to `localhost:8001`, serves static `assets/` directly

See [../CLAUDE.md](../CLAUDE.md#production-server) for deployment steps and SSH access.

## Release Readiness

Release readiness is judged on four dimensions (the apex goal oracle in `docs/goals/baolife-release-ready/`). A green test suite alone is **not** release-readiness — the bar requires real in-app walkthroughs plus Craig's launch sign-off.

| Dimension | State | Remaining work |
|-----------|-------|----------------|
| **Fun** — core loop engages, balanced progression | 🟢 Largely met | Minor content-balance items (e.g. medical-emergency affordability for a broke player) |
| **Playable** — every flow works end-to-end, no dead-wired features, no crashes | 🟡 iOS mostly validated | Drive remaining iOS surfaces (Messaging, Dating actions, dailies UI, activity loop); **Android not hands-on validated** |
| **Complete** — no half-built systems | 🟠 Gaps | **Avatar/identity feature is half-built and uncommitted** (biggest completeness gap); Android ~85% parity (v1.1) |
| **Releasable** — store compliance, monetization, stability, assets | 🟠 Gaps | IAP receipt validation wired but **flag-OFF** (needs `APPLE_SHARED_SECRET` + prod-enable); **store assets/metadata/screenshots not created**; account deletion + privacy manifest + 18+ content-safety ✅ done |

### Owner decisions blocking the final release audit (`baolife-release-ready` T999)

These are gated on Craig, not autonomous work:
1. **Avatar feature** — scope and finish (QuiverAI pipeline is WIP/uncommitted)
2. **Android** — launch scope (ship v1 alongside iOS, or defer to v1.1)
3. **IAP** — provide `APPLE_SHARED_SECRET` and decide whether to enable server-side validation in prod
4. **Store ops** — create App Store assets/metadata/screenshots; submission

### Net assessment

Core systems and gameplay are in strong shape (1718 tests green, multiple inert-mechanic bugs found+fixed, balance tuned, content-safety + account-deletion + privacy done). The path to "releasable" is now mostly **finish the avatar feature, create store assets, and make the IAP/Android launch-scope calls** — not further core gameplay engineering.

Out of scope for v1: AI conversation refactoring, localization, iPad layouts. Android may be v1 or v1.1 pending the scope call above.

## Server URLs

| Environment | URL |
|-------------|-----|
| Local dev | `ws://localhost:8001/` |
| Production | `wss://lichun.app/wss/` |

## Related Documentation

- [../CLAUDE.md](../CLAUDE.md) — Main project documentation
- [plans/2026-04-13-baolife-mvp-completion-design.md](./plans/2026-04-13-baolife-mvp-completion-design.md) — Current MVP design
- [plans/2026-04-13-baolife-mvp-implementation.md](./plans/2026-04-13-baolife-mvp-implementation.md) — Current MVP executable plan
- [CODEBASE_MAP.md](./CODEBASE_MAP.md) — Full architecture map
- [../ios/CLAUDE.md](../ios/CLAUDE.md) — iOS development guide
- [../ios/BACKEND.md](../ios/BACKEND.md) — WebSocket protocol reference