# Tara — Systems Deep Dive

> The `apps/tara/` area: the three deployable applications — a Hono REST API, an
> Expo/React-Native mobile app, and a Next.js PWA — that together ship **Tara**,
> the meditation and mindfulness product, on top of the shared Oshun platform.

## What this area is

Tara is an end-user meditation platform: guided meditations, structured courses,
an unguided timer, breathing exercises, progress/streak tracking, offline
downloads, and subscriptions. Unlike the `libs/` domains, `apps/tara/` is the
**product surface** — three Nx _applications_ (`projectType: "application"`),
each carrying a `scope:tara` tag, that are actually built and deployed rather
than imported. They are `@tara/api` (the backend), `@tara/mobile` (iOS/Android),
and `@tara/web` (the browser PWA).

The three apps split along a clean client/server boundary. `@tara/api` owns all
persistence and business rules — it is a Hono server
(`apps/tara/api/src/app.ts`) backed by Drizzle/Postgres
(`apps/tara/api/src/db/schema.ts`) and Redis, exposing a versioned `/api/v1/*`
REST surface plus an OpenAPI 3.1 document and Swagger UI. `@tara/mobile` and
`@tara/web` are its two front ends: both render the same catalog, player, and
progress experiences, the mobile one with Expo Router + Zustand and the web one
with the Next.js App Router. Neither client embeds business logic that belongs
on the server; they call the API and manage local UI/session state.

Beyond the three application entities, the directory also carries non-project
supporting material that is _not_ an Nx node: `apps/tara/content/` (JSON-schema
definitions and sample meditation/course/teacher content), and `apps/tara/docs/`
(store-submission checklists, legal pages, help center, marketing copy). Those
are assets and documentation, not buildable projects, so they do not appear in
the entity reference below.

## How it fits the wider system

Tara composes shared Oshun infrastructure rather than reinventing it: the API's
authentication is configured on top of `@oshun/auth` (`createAuthService` in
`apps/tara/api/src/auth/service.ts`, HS256 JWTs with lockout and a password
policy), and both clients share cross-device resume logic through the
`@tara/features` library (`buildResumeSyncBundle`,
`checkpointFromIrisSessionMemory`, `checkpointFromPsycheResumeEnvelope`), which
bridges Tara's session state to the Iris assistant and Psyche personalization
domains.

The most explicit platform seam is the **Oshun BFF facade**. `@tara/api` mounts
a second, non-`/api` router at `/v1/oshun/*`
(`apps/tara/api/src/oshun-facade/routes.ts`) that the Oshun BFF's Tara adapter
dials service-to-service. It speaks the `@oshun/contracts` partial-failure
envelope (`{ results, errors, partial }`), is fail-closed in production behind
`TARA_OSHUN_FACADE_TOKEN`, and is backed by the same Postgres tables as the
native routes via `DrizzleTaraOshunStore`. That is how the wider Oshun shell
surfaces Tara's recommendations, continue-session, course-progress, favorites,
audio, history, and streak data without re-implementing them. The clients
consume the public `/api/v1/*` surface; the BFF consumes `/v1/oshun/*`.

## Entity reference

### @tara/api

The Tara backend (`apps/tara/api`, `sourceRoot apps/tara/api/src`) — a real,
fully-implemented Hono service, not a scaffold. `src/app.ts` builds an
`OpenAPIHono` app with security headers, CORS, request-id, RFC-7807 error
handling (`src/middleware/error-handler.ts`), tiered rate limiting
(anonymous/free/premium), and JWT `authMiddleware`, then mounts ~17 route groups
under `/api/v1/*` (`auth`, `users`, `meditations`, `courses`, `teachers`,
`collections`, `search`, `sessions`, `progress`, `achievements`, `favorites`,
`history`, `downloads`, `subscription`, `notifications`, `analytics` +
`dashboard`, and an inline `recommendations` handler), plus `/health`, `/ready`,
and a generated `openapi.json` + Swagger UI at `/api/docs`. Persistence is
Drizzle ORM over Postgres (`src/db/schema.ts`, with checked-in migrations under
`drizzle/`) and Redis (`src/redis`); supporting services include Stripe billing
(`src/services/billing.ts`), Apple/FCM push (`src/services/notifications/`), CDN
signed URLs, avatar storage, email, and Apple-ID token verification. It also
hosts the `/v1/oshun/*` BFF facade described above. Tested with Vitest unit
specs, a Vitest integration suite (`test/integration/`), and k6 load tests
(`test/load/api-load.k6.js`, wired as `load-test` targets).

### @tara/mobile

The Tara iOS/Android app (`apps/tara/mobile`) — a real React Native + Expo
(SDK 51) application using Expo Router file-based routing. `app/` defines the
navigation tree: an `(onboarding)` flow (goals, experience, preferences,
notifications), a `(tabs)` shell (home `index`, `meditate`, `timer`, `progress`,
`profile`), and stack routes for the player (`player/[id].tsx`),
`meditation/[id]`, `course/[id]`, `breathing`, `library`, `search`, `settings`,
and `storage`. State lives in Zustand stores under `src/store/`
(`meditationStore`, `userStore`, `onboardingStore`, `accessibilityStore`),
persisted via `AsyncStorage`. `src/services/` implements audio playback
(`audio.ts`, expo-av), push notifications, offline `download.ts`, deep links,
and in-app purchases (`purchases.ts`, `apple.ts`, `android.ts`). Cross-device
resume is shared with the web client and the Iris/Psyche domains through
`@tara/features` (imported in `src/store/meditationStore.ts`). Targets cover
Expo start, EAS build/submit, Jest tests, and Maestro e2e flows (`e2e/flows/`).

### @tara/web

The Tara browser app (`apps/tara/web`, `sourceRoot apps/tara/web/src`) — a real
Next.js App Router PWA, not a scaffold. Routing is locale-prefixed
(`src/app/[locale]/…`, next-intl) and split into an `(app)` group (`meditate`,
`courses`, `teachers`, `timer`, `breathing`, `library`, `search`, `play/[id]`,
`progress`, `settings/*`, `subscription/*`) and an `(auth)` group (`login`,
`signup`, `forgot-password`, `reset-password`, `verify-email`, social
`callback`). It ships PWA support (`public/sw.js`, `offline` route), SEO
surfaces (`robots.ts`, `sitemap.ts`, `components/seo/JsonLd.tsx`), and an
accessibility/UI component set under `src/components/`. Client logic lives in
`src/lib/`: an auth API client + Zustand store + React context (`lib/auth/`),
the catalog reader (`tara-web-meditation-catalog.ts`), library-action state, the
assistant follow-up memory, and `tara-resume-sync.ts`, which (via
`@tara/features`) merges Iris session-memory and Psyche resume envelopes into
canonical resume checkpoints shared with the mobile app. Quality tooling is
extensive: Vitest unit + performance specs, Playwright e2e (`e2e/tests/`),
Storybook, and Lighthouse CI.