# Tara — Systems Deep Dive

> The `libs/tara/` area: eight Nx libraries that make up the full vertical slice
> of **Tara**, the app-store-safe meditation / mindfulness product — from the
> Prisma data model up through domain logic to the React design system.

## What this area is

Tara is one of the consumer-facing products in the Oshun monorepo: a meditation
and mindfulness app. Unlike the `libs/contracts/` area (pure wire types) or a
single-purpose engine library, `libs/tara/` is a **product's entire client/edge
stack expressed as eight separate Nx libraries**, each owning one architectural
layer. The `libs/tara/README.md` states the charter directly — these are
"Tara-specific libraries for the meditation platform" — and the Prisma schema
header (`libs/tara/database/prisma/schema.prisma`) calls Tara "an app-store-safe
meditation app."

The eight projects are tagged by layer, and together they form a clean stack:
`@tara/database` (`layer:data`) is the Postgres/Prisma data model at the bottom;
`tara-api-client` and `@tara/content` (`layer:domain`) are the wire/transport
and content-domain layers; `@tara/features` and `@tara/analytics`
(`layer:domain`) hold deterministic product logic; `@tara/config` and
`@tara/monitoring` (`layer:infra`) provide runtime configuration and
observability; and `@tara/ui` (`layer:ui`) is the design system and component
library at the top. Every project carries the `scope:tara` tag.

The libraries depend on each other in the expected direction — for example
`@tara/features` imports `isFeatureEnabled` / `TaraFeatureFlagKey` from
`@tara/config` (`libs/tara/features/src/gates.ts`) to drive its feature gates. A
naming note: the `README.md` proposes a `tara-{library-name}` project-name
convention, but in practice only `tara-api-client` follows it; the other seven
projects use their `@tara/*` package name as their Nx project name as well.

## How it fits the wider system

A hard content-isolation boundary defines this area: the `README.md` states Tara
libraries may depend on other `@tara/*` libraries, `@oshun/meditation-*`, and
general `@oshun/*` shared libraries, but **must not** depend on `@lilith/*` or
any adult/explicit-content library. Tara is the "safe" surface, kept
structurally separate from that part of the monorepo.

Two distinct API surfaces meet here. `tara-api-client` is a **generated** typed
client for the Oshun V1 BFF — it talks to `/api/v1/tara/...` endpoints (ritual
templates, sessions, taxonomies, sitting-completion events) and is regenerated
from OpenAPI by `libs/openapi/scripts/generate-oshun-v1-api-clients.ts`.
Separately, `@tara/content` carries its own hand-written `ContentClient` for the
meditation-content catalog (meditations, courses, teachers, sounds). The
`@tara/features` library is also the integration seam to sibling Oshun domains:
its trigger engine and prompt modules reference `arete`, `veritas`, `nyx`,
`nisaba`, `metis`, and `sophia` (see the `TARA_TRIGGER_SOURCE_DOMAIN_VALUES`
union in `libs/tara/features/src/triggers/trigger-engine.ts`). Walk the "used
by" edges on any node below to see exactly who depends on it.

## Entity reference

### @tara/analytics

The product analytics library (`libs/tara/analytics`, `layer:domain`). It is a
real, comprehensive implementation, not a thin wrapper: a `TaraTracker`
(`createTracker`/`getTracker`) with pluggable providers
(`createInternalProvider`, `createConsoleProvider`, `createMemoryProvider`), a
large strongly-typed event taxonomy (`TaraEventMap` covering meditation, course,
timer, breathing, subscription, content, search, notification, streak,
achievement, onboarding, and app-lifecycle events) with matching builders and
type guards, a metrics type surface, and an `ExperimentManager` for A/B tests
and feature flags. The experiment engine does **deterministic user bucketing via
murmurhash3** (`libs/tara/analytics/src/experiments/experiment-manager.ts`),
with a default config of `hashSeed: 'tara-experiments'`,
`confidenceLevel: 0.95`, and `minimumDetectableEffect: 0.05`.

### tara-api-client

The generated V1 wire client (`libs/tara/api-client`; Nx project name
`tara-api-client`, package `@tara/api-client`, marked `private`). The header of
`src/client.ts` states it "is generated by
libs/openapi/scripts/generate-oshun-v1-api-clients.ts." It exposes a
`createTaraApiClient` returning seven `ResourceClient`s for the Tara V1 sync
surface — `durationBuckets`, `lineageTaxonomies`, `ritualSteps`,
`ritualTemplates`, `continuationStates`, `ritualSessions`, and
`sittingCompletionEvents` — each offering `list` / `create` / `get` / `upsert` /
`tombstone` over `/api/v1/tara/...` paths, with cursor pagination,
`includeTombstones` soft-delete semantics, an injectable `FetchLike`, and a
typed `OshunApiClientError`. The OpenAPI component types live in
`src/generated/openapi.ts`. This is the persistence/sync transport, distinct
from `@tara/content`'s catalog client.

### @tara/config

The runtime configuration and feature-flag library (`libs/tara/config`,
`layer:infra`, `private`) — its `package.json` describes it as "Central Tara
runtime configuration and feature flag resolution." `src/environment.ts`
implements `createTaraConfig` (deriving analytics/crash-reporting defaults from
the environment) and `configFromEnvironment`, which reads `TARA_ENV` /
`NODE_ENV`, `TARA_API_URL` / `TARA_WEB_URL` / `TARA_CDN_URL`, and boolean
`TARA_ANALYTICS_ENABLED` / `TARA_CRASH_REPORTING_ENABLED` flags. The barrel
(`src/index.ts`) re-exports `types`, `defaults`, `environment`, and `features`;
the last supplies the `isFeatureEnabled` / `TaraFeatureFlagKey` surface that
`@tara/features` consumes for its gates. Real implementation.

### @tara/content

The meditation-content management library (`libs/tara/content`, `layer:domain`)
— the largest and deepest project in the area. It owns an extensive domain type
system (`Meditation`, `Course`, `Teacher`, `Collection`, `Program`,
`AmbientSound`, `BackgroundMusic`, `BellSound`, `BinauralBeat`, and their
summaries/filters/results), plus four substantial subsystems with real
algorithms: a `ContentClient` with typed error hierarchy and many presets
(`createProductionClient`, `createResilientClient`, etc.); a multi-layer cache
(`InMemoryContentCache`, `PersistentContentCache`, an SWR manager with
`withSWR`/`createPrefetcher`); a composable filter library (core combinators
`and`/`or`/`not`/`inRange`/`textSearch` plus meditation- and course-specific
filters); and a full-text search engine (`tokenize`, `levenshteinDistance`,
`stringSimilarity`, spelling correction, query expansion, snippet generation).
It also ships WebVTT caption parsing/validation under `accessibility/` and a
full set of React hooks (`useMeditations`, `useCourse`, `useTeacher`, …).
Verified by spec files across `api/`, `cache/`, `filters/`, `search/`, and
`accessibility/`.

### @tara/database

The data layer (`libs/tara/database`, `layer:data`): a Prisma schema plus a
checked-in generated client for the meditation platform. `prisma/schema.prisma`
targets PostgreSQL with the `uuid-ossp`, `pgcrypto`, `vector`, and `pg_trgm`
extensions and defines the full domain model — `User`, `Profile`,
`Subscription`, `Payment`, `Device`, `Teacher`, `Meditation`, `AmbientSound`,
`Course`, `Lesson`, `LessonContent`, `MeditationSession`, `UserProgress`,
`Streak`, `Achievement`, `UserAchievement`, `Favorite`, `Download`,
`HistoryEntry`, `Notification`, `UserSettings`, `Feedback`, `RelatedMeditation`,
and `Ritual`. The barrel (`src/index.ts`) re-exports `taraDbClient` with
`connect` / `disconnect` / `healthCheck` plus the generated Prisma model types.
It carries a real migration (`prisma/migrations/20260506000000_initial`), seed
scripts (`seed.ts`, `seed-test.ts`), and Nx targets for `prisma:generate`,
`prisma:migrate:*`, `prisma:studio`, and `db:seed`.

### @tara/features

The product-logic library (`libs/tara/features`, `layer:domain`, `private`) —
described as "Tara feature state selectors and feature-gated product helpers."
Its barrel (`src/index.ts`) composes a wide set of pure, deterministic modules,
each with its own `.spec`: `progress` and `streak` (`calculateStreak` computes
current/longest streaks from completed-session dates), `gates` (feature gating
over `@tara/config`), ritual modules (`ritual-template`, `ritual-session`,
`ritual-completion-event`, `continuation-state`), several taxonomies (`mood`,
`theme`, `modality`, `lineage`, `duration-buckets`, `context-tags`), a
`triggers/` engine supporting `time-of-day` / `post-event` / `location-aware` /
`calendar-event-derived` kinds, and cross-domain helpers
(`nisaba-passage-companions`, `arete-next-steps`, `nyx-perspective-prompts`,
`veritas-sophia-explanatory-notes`, `humane-recovery`, `library-actions`,
`resume-memory`, `assistant-follow-ups`). This is where Tara wires into sibling
domains (arete, veritas, nyx, nisaba, metis, sophia).

### @tara/monitoring

The observability library (`libs/tara/monitoring`, `layer:infra`): a
Sentry-style error-tracking and performance-monitoring stack. The error side
provides a `TaraErrorTracker` with `captureException` / `captureMessage`,
breadcrumbs, scopes, user/tag/extra context, Tara-specific error contexts
(meditation, subscription, audio), and three providers — `ConsoleErrorProvider`,
a `MemoryErrorProvider` for testing, and a `ServerErrorProvider` backed by an
`InMemoryErrorStore`. The performance side
(`src/performance/performance-monitor.ts`) implements `Span`, `Transaction`, and
a `PerformanceMonitor` with `startTransaction`, `trace`/`traceSync`,
measurements, and web-vitals types. Real implementation with a
`monitoring.spec.ts`.

### @tara/ui

The design-system and component library (`libs/tara/ui`, `layer:ui`). It exposes
a theme layer (`TaraThemeProvider`, `useTheme`, `ThemeScript` with
light/dark/system modes), a full design-token set (colors including a dedicated
`meditation` palette, typography, spacing, effects, and breakpoints, each with
`generate*CSSProperties` helpers), React hooks, an animation toolkit (`micro`,
`primitives`, `transitions`, each paired with a CSS module), and **32
components** under `src/components/` spanning meditation-specific widgets
(`AudioPlayer`, `MiniPlayer`, `BreathingVisualizer`, `MeditationCard`,
`SoundMixer`, `StreakDisplay`, `TimerDisplay`, `SessionComplete`,
`AchievementBadge`, `CourseProgress`, `TeacherCard`) and a general primitive set
(`Button`, `Card`, `Input`, `Modal`, `Toast`, `TabBar`, `BottomSheet`,
`Typography`, and more). Each component ships with snapshot tests, and the
library has a dedicated `accessibility.spec.tsx`.