Skip to main content

Open Genie monorepo structure

This document describes how the open-genie repository is organized: applications, shared packages, and how they relate.

High-level layout​

open-genie/
├── apps/
│   ├── web/              # Vite SPA + Hono backend (API, WebSocket, DB, media, optional Electron shell)
│   ├── phone/            # Expo iPhone app (expo-router, bottom tabs)
│   ├── tablet/           # Expo iPad app (expo-router, drawer)
│   └── tv/               # Apple TV (react-native-tvos, stack navigation)
├── packages/           # @genie/* libraries consumed by apps (see below)
├── docs/               # Docusaurus site package (config + `docs/docs/` page sources)
├── workplans/          # Plans and task notes (not shipped code)
├── data/               # Local runtime data (e.g. files/cache) when running stack locally; gitignored as appropriate
├── package.json        # npm workspaces root
├── tsconfig.json       # Root; extends `expo/tsconfig.base` (tooling default)
├── tsconfig.base.json  # Strict TS defaults extended by some packages and apps
├── eas.json            # EAS Build profiles (Expo: phone + tablet)
└── .npmrc              # `legacy-peer-deps=true`

The repo is an npm workspaces monorepo (apps/* and packages/*). Installing at the root links local @genie/* packages from packages/.

Applications​

apps/web — home hub (Vite + Hono + Node)​

The primary server and web app: Hono API framework, Vite SPA frontend (React + React Router v7), custom Node entry (server.ts), REST and WebSocket handlers, PostgreSQL (Drizzle), media pipeline, auth, and optional Electron (apps/web/electron/) to wrap the UI in a native window.

  • Stack: Vite, React, React Router v7, Hono, Tailwind, Storybook, Drizzle ORM (see apps/web/package.json).
  • Layout:
    • server/ — Hono API app (createApiApp()) and route handlers
    • client/ — Vite SPA (main.tsx, routes.tsx, pages/, components/)
    • lib/ — shared server-side logic (db, ws, auth, actions, media, plugins, …)
  • Workspace dependency: uses @genie/tokens for brand colors/typography shared with other clients.
  • Scripts (from monorepo root): web:dev, web:build, web:start, db:migrate, db:studio (see root package.json).

This is not an Expo app; it is the Genie "home" service and browser UI, not a fourth React Native target.

apps/phone — @genie/phone-app​

  • Expo (~54), expo-router, React Native 0.81, React 19.
  • iOS bundle ID (example from config): com.anonymous.genie-phone (apps/phone/app.json).
  • Packages: shared, connection, ui, tokens, chat, media, notifications, camera-sync.
  • Typical use: file-based routes under app/, local backup/SQLite/secure store where configured.

apps/tablet — @genie/tablet-app​

  • Expo (~54), expo-router, drawer navigation, React Native 0.81.
  • iOS bundle ID (example): com.developsmith.genie-tablet.
  • Packages: same set as phone (including camera-sync).

apps/tv — @genie/tv-app​

  • Not Expo — uses react-native via react-native-tvos (0.81.x), stack navigator, App.tsx + index.js entry.
  • Packages: shared, connection, ui, tokens, media (no chat, notifications, or camera-sync).
  • Scripts (from root): npm run tv (Metro), npm run tv:ios (runs the tvOS scheme/simulator in package.json).

packages/ — shared libraries​

All are private, scoped as @genie/<name>, and published only via the monorepo (not necessarily to npm).

Dependency graph (simplified)​

@genie/shared
@genie/tokens
     ↑
@genie/connection  →  @genie/shared
     ↑
@genie/camera-sync →  @genie/shared, @genie/connection
@genie/ui          →  (peer: react, react-native)
@genie/notifications → @genie/shared, @genie/connection
@genie/chat        →  @genie/shared, @genie/connection, @genie/ui
@genie/media       →  @genie/shared, @genie/connection, @genie/ui
  • @genie/shared: Types (message, device, chat, media, notification, camera, memory), config (e.g. server URLs), and utils. No other @genie/* dependencies.
  • @genie/tokens: Design tokens (brand colors, light/dark surfaces, typography) usable from Expo apps, TV, and the web app.
  • @genie/connection: WebSocket client, connection helpers, token/storage hooks — depends on shared and AsyncStorage.
  • @genie/ui: React Native design system (theme, primitives/components); peers on react / react-native.
  • @genie/chat: Chat UI and hooks; depends on shared, connection, ui.
  • @genie/media: Media library client, hooks, and RN components; depends on shared, connection, ui.
  • @genie/notifications: Push registration/handlers; depends on shared and connection (Expo notification peers).
  • @genie/camera-sync: Camera roll / background sync and UI for phone and tablet; depends on connection and shared (Expo module peers).

What is shared where​

AreaPhoneTabletTVWeb (server)
shared, connection, ui, tokens✓✓✓tokens (+ rest via server)
chat✓✓—(server/web chat)
media✓✓✓(server-side media)
notifications✓✓—(push from server)
camera-sync✓✓——

TypeScript and path aliases​

  • Expo apps (e.g. phone): tsconfig extends ../../tsconfig.base.json and maps @genie/* → ../../packages/*/src (see apps/phone/tsconfig.json).
  • Web app: path alias @/* → ./ (repo root of apps/web/), resolves @/lib/*, @/server/*, @/client/*, etc.; also resolves @genie/tokens via workspaces.

Root scripts (from open-genie/package.json)​

# Mobile / TV
npm run phone
npm run phone:ios
npm run phone:android
npm run tablet
npm run tablet:ios
npm run tv
npm run tv:ios

# Web app (home hub)
npm run web:dev        # Hono + Vite dev servers concurrently
npm run web:build      # Vite SPA + server TS build
npm run web:start      # Production server
npm run db:migrate     # Apply pending DB migrations
npm run db:studio      # Open Drizzle Studio

# Electron (desktop shell)
npm run electron:dev
npm run electron:build
npm run electron:pack
npm run electron:dist

# Repo
npm run lint

EAS (Expo Application Services)​

eas.json at the repo root defines development, preview, and production profiles (with autoIncrement on production) for the Expo apps. The TV and web/Electron stack are not built with EAS in this setup (TV: Xcode; web server: Node/Hono; native shell: Electron as documented in app READMEs).

TypeScript at the root​

  • tsconfig.json — minimal, extends expo/tsconfig.base for Expo-oriented tooling.
  • tsconfig.base.json — shared strict options (strict, moduleResolution: bundler, etc.) used by packages and some apps that extend it.

Each app may extend these differently (Expo vs Vite vs TV).

Documentation and planning​

  • docs/ — Human-facing docs (including this file).
  • workplans/ — Planning documents and task breakdowns; useful for roadmaps, not a runtime part of the monorepo.

For product setup and release processes, see other files under docs/ (e.g. publishing guides) as needed.