OMNILORE

Audio-first narrative AI RPG, English-first and i18n-ready — Expo + Firebase + BFF Cloud Run + Gemini app.

Quickstart

git clone https://github.com/Wanllii/omnilore.git
cd omnilore
corepack enable        # activates the pnpm version from packageManager
pnpm bootstrap         # checks Node/pnpm/Java, installs deps, creates .env, validates the stack

Done. To validate the environment and develop:

pnpm quality                          # full gate (doctor, types, lint, tests, deps)
pnpm test:watch                       # TDD loop (Vitest)
pnpm --filter @omnilore/mobile dev    # Expo app (Web + Android dev build)
pnpm dev:emulator                     # Emulator Suite (Firestore+Storage+Auth, requires Java)
pnpm seed:emulator                    # minimal dev seed in the emulator (idempotent)
pnpm dev:stack                        # one command: emulators + BFF (apps/api) + web, prefixed output
pnpm test:rules                       # Security Rules tests in the emulator

pnpm bootstrap is idempotent (safe to re-run) and reports what it skipped: Playwright comes in at C-7 and the Emulator Suite (requires Java) at A-1. Project rules and sources of truth: CLAUDE.md.

---

MAIN GOALS

IMMEDIATE GOAL (NOW): Develop the MVP (Vertical Slice) of the application.

MAIN GOAL (LONG TERM): Become the #1 application for user-personalized narrative experiences. Using the most advanced LLM models (currently Gemini LLM) to craft narrative texts that resonate with the user for entertainment, relaxation, and catharsis. Offering audio generated via Text-To-Speech (currently Gemini TTS) directly tied to the narrative texts. Supporting localized narratives and UI through the repo's i18n architecture, with worldbuilding and lore stored in the cloud (currently Firebase/Google Cloud).

CHOSEN TECH STACK

Definitive layers of the OMNILORE Tech Stack

1. App / Universal Frontend

Expo SDK 56
React Native 0.85.x
React 19.2.3
React Native Web 0.21.0
Expo Router v56
expo-audio
Hermes v1
TypeScript 6.0.3

---

2. Runtime / Package Manager

Node.js 22.18.x+ / Node 22 LTS line
pnpm 11.5.1
Corepack
pnpm-lock.yaml

---

3. Firebase / Product

Firebase JS SDK 12+
Firebase Auth
Cloud Firestore
Cloud Storage for Firebase
Firebase Hosting
Firebase App Check
Firebase Security Rules
Firebase Emulator Suite
Firebase Remote Config (future)

---

4. Backend / Secure API

Cloud Run Service
Node.js 22.18.x+
TypeScript 6.0.3
Express
Zod
Pino
Helmet
CORS
firebase-admin

---

5. AI / Narrative

@google/genai
Gemini LLM
Gemini Audio Understanding
Gemini-TTS
Gemini Live API (future)

---

6. Voice / TTS and STT

Primary TTS:
Gemini-TTS

Primary STT:
Gemini Audio Understanding

Real-time voice (future):
Gemini Live API

Fallback TTS:
Google Cloud Text-to-Speech (classic)

Fallback STT:
Google Cloud Speech-to-Text

---

7. Required Google Cloud / Infrastructure

Cloud Run
Secret Manager
Cloud Logging
Cloud Monitoring
Error Reporting
Cloud Text-to-Speech API as the Gemini-TTS surface

---

8. Deploy / Distribution

EAS Build
EAS Submit
EAS Update
Development Builds
Firebase Hosting
Cloud Run Deploy

---

9. Tests / Quality / Local Dev

Vitest
React Native Testing Library
Playwright
Firebase Emulator Suite
Expo Doctor
TypeScript strict
ESLint
Prettier

---

10. Initial regions

Firestore:
southamerica-east1

Cloud Run API:
southamerica-east1

Firebase Hosting:
global/CDN

Gemini/Gemini-TTS:
the service's available region/surface

---

Absolute summary

Expo SDK 56 = app.
Firebase = product, data, auth, and hosting.
Gemini = brain, ears, and voice.
Cloud Run = secure backend.
Classic Google Cloud = infrastructure or fallback.
pnpm = mandatory package manager.

FILE PATH

Read the file \omnilore\docs\ai-friendly-code-principles.md to learn how to write any file in this repository. Read the file \omnilore\docs\plans\omnilore-mvp-canonical-prd.md to begin the MVP PRD implementation. Read the file \omnilore\docs\omnilore-rpg-system\README.md to understand the OMNILORE RPG system.