Tara is a meditation and mindfulness platform providing guided meditations, structured courses, ambient sounds, progress tracking, achievements, and subscription management. The platform consists of a RESTful API server, a Next.js progressive web application, and an Expo/React Native mobile application, all backed by a PostgreSQL database and Redis cache.
Prerequisites#
Required Software#
| Software | Minimum Version | Purpose |
|---|---|---|
| Node.js | >= 20.0.0 | Runtime for API and web server |
| pnpm | >= 10.0.0 | Package manager (monorepo workspace) |
| Docker | >= 24.0 | Infrastructure (PostgreSQL, Redis) |
| TypeScript | ^6.0.3 | Type checking and compilation |
| Git | >= 2.40 | Version control |
For Mobile Development#
| Software | Version | Purpose | Installation |
|---|---|---|---|
| Expo CLI | Latest | React Native tooling | npm install -g expo-cli |
| EAS CLI | >= 7.0 | Expo build service | npm install -g eas-cli |
| Xcode | 15+ | iOS Simulator | Mac App Store |
| Android Studio | Latest | Android Emulator | developer.android.com |
| Maestro | Latest | Mobile E2E testing | brew install maestro |
For Testing#
| Software | Version | Purpose | Installation |
|---|---|---|---|
| Playwright | Latest | Web E2E testing | pnpm nx e2e:install @tara/web |
| k6 | Latest | API load testing | brew install k6 |
Project Structure#
apps/tara/
api/ # REST API server (Hono + Drizzle ORM)
web/ # Next.js 14 PWA with i18n (next-intl)
mobile/ # Expo/React Native app (iOS + Android)
content/ # Static content catalog (meditations, courses, sounds, teachers)
docs/ # App store checklists, legal docs, marketing copy
libs/tara/
analytics/ # Analytics event tracking (@tara/analytics)
config/ # Configuration
content/ # Content hooks and helpers (@tara/content)
database/ # Prisma schema and client (@tara/database)
features/ # Feature flags
monitoring/ # Application monitoring (@tara/monitoring)
ui/ # Shared UI components (@tara/ui)
libs/meditation/ # Cross-platform meditation libraries
analytics/ # Meditation-specific analytics
breathing/ # Breathing exercise engine (@oshun/meditation-breathing)
core/ # Core meditation types and utilities
offline/ # Offline download manager (@oshun/meditation-offline)
player/ # Audio player abstraction (@oshun/meditation-player)
progress/ # Progress tracking (@oshun/meditation-progress)
session/ # Session management (@oshun/meditation-session)
timer/ # Meditation timer (@oshun/meditation-timer)
Application Roles#
| Application | Framework | Purpose |
|---|---|---|
api |
Hono 4 + Drizzle | REST API with OpenAPI docs and JWT auth |
web |
Next.js 14 + React | SSR/PWA web client with i18n |
mobile |
Expo 51 + RN 0.74 | Native iOS and Android mobile app |
content |
Static JSON/YAML | Content catalog for meditations and courses |
Library Roles#
| Library | Package Name | Layer | Purpose |
|---|---|---|---|
@tara/database |
libs/tara/database |
data | Prisma schema, client, and generated types |
@tara/ui |
libs/tara/ui |
ui | Shared React components and design tokens |
@tara/content |
libs/tara/content |
domain | Content hooks (collections, courses) |
@tara/analytics |
libs/tara/analytics |
domain | Event tracking and analytics |
@tara/monitoring |
libs/tara/monitoring |
infra | Application monitoring and observability |
| Breathing | @oshun/meditation-breathing |
core | Breathing exercise patterns and engine |
| Player | @oshun/meditation-player |
core | Cross-platform audio player |
| Timer | @oshun/meditation-timer |
core | Meditation timer with intervals |
| Session | @oshun/meditation-session |
domain | Session lifecycle management |
| Offline | @oshun/meditation-offline |
domain | Download manager for offline access |
| Progress | @oshun/meditation-progress |
domain | Streak and progress calculations |
Local Development Setup#
1. Start Infrastructure#
Tara requires PostgreSQL and Redis. Both are provided by the monorepo Docker Compose configuration.
# Start core infrastructure (PostgreSQL + Redis)
docker compose -f docker/docker-compose.dev.yml up -d
# Verify services are running
docker compose -f docker/docker-compose.dev.yml ps
This starts:
- PostgreSQL (port 5432) with the
oshun_devdatabase (used by Tara) - Redis (port 6379) for session caching, rate limiting, and feature flags
- MinIO (ports 9000/9001) for S3-compatible audio/image storage
2. Install Dependencies#
pnpm install
3. Set Environment Variables#
The root .env file contains defaults for local development. Key variables used
by Tara services:
| Variable | Default | Used By |
|---|---|---|
TARA_DATABASE_URL |
postgresql://oshun:oshun_dev@localhost:5432/oshun_dev |
@tara/database |
DATABASE_URL |
postgresql://oshun:oshun_dev@localhost:5432/oshun_dev |
API (Drizzle) |
REDIS_URL |
redis://localhost:6379 |
API cache |
PORT |
3001 |
API server |
HOST |
0.0.0.0 |
API server |
CORS_ORIGIN |
* |
API CORS |
NODE_ENV |
development |
All services |
NEXT_PUBLIC_API_BASE_URL |
http://localhost:8080 |
Web client |
NEXT_PUBLIC_WS_URL |
ws://localhost:8080 |
Web WebSocket |
NEXT_PUBLIC_CDN_URL |
(empty) | Web CDN prefix |
EXPO_PUBLIC_API_URL |
https://api.tara.app |
Mobile client |
4. Database Setup (Prisma)#
The Tara database uses Prisma ORM with a PostgreSQL schema defined at
libs/tara/database/prisma/schema.prisma.
# Generate the Prisma client
pnpm nx run @tara/database:prisma:generate
# Run database migrations (development mode - creates migration if needed)
pnpm nx run @tara/database:prisma:migrate:dev
# Or push the schema directly for rapid iteration (no migration file created)
cd libs/tara/database && npx prisma db push
# Open Prisma Studio to browse data
pnpm nx run @tara/database:prisma:studio
5. Seed the Database#
# Seed with standard content (meditations, courses, teachers, sounds)
pnpm nx run @tara/database:db:seed
# Seed with test fixtures
pnpm nx run @tara/database:db:seed:test
Running Services#
API Server#
The Tara API is a Hono-based REST server running on port 3001.
# Development with hot reload (tsx watch)
pnpm nx serve @tara/api
# Alternative: run directly from the app directory
cd apps/tara/api && pnpm dev
Once running, the following endpoints are available:
| URL | Description |
|---|---|
http://localhost:3001/ |
API root (service info) |
http://localhost:3001/health |
Health check (DB + Redis) |
http://localhost:3001/ready |
Readiness probe |
http://localhost:3001/api/docs |
Swagger UI |
http://localhost:3001/api/v1/openapi.json |
OpenAPI 3.1 specification |
http://localhost:3001/api/v1 |
API version info |
API Route Summary:
| Route Prefix | Auth Required | Description |
|---|---|---|
/api/v1/auth |
No | Registration, login, password reset |
/api/v1/users |
Yes | User profile and preferences |
/api/v1/meditations |
Optional | Meditation content catalog |
/api/v1/courses |
Partial | Course listing (public), progress (auth) |
/api/v1/teachers |
No | Teacher profiles |
/api/v1/collections |
No | Curated content collections |
/api/v1/search |
No | Full-text content search |
/api/v1/sessions |
Yes | Meditation session tracking |
/api/v1/progress |
Yes | User stats, streaks, milestones |
/api/v1/achievements |
Yes | Achievement badges |
/api/v1/favorites |
Yes | Favorite meditations and courses |
/api/v1/history |
Yes | Listening history |
/api/v1/downloads |
Yes | Offline content management |
/api/v1/subscription |
Partial | Subscription management + webhook |
/api/v1/notifications |
Yes | Push notification preferences |
/api/v1/analytics |
Partial | Event tracking and experiments |
/api/v1/recommendations |
No | Personalized suggestions |
Key middleware stack (applied in order):
secureHeaders- Security response headerscors- CORS with configurable originlogger- Request loggingtiming- Server-Timing headersprettyJSON- Pretty-printed JSON (development only)requestIdMiddleware- Unique request ID (tara_prefix)rateLimitMiddleware- Rate limiting on/api/*routesauthMiddleware- JWT authentication (per-route)
Web Application#
The Tara web client is a Next.js 14 application with SSR, PWA support, and
internationalization via next-intl.
# Development server (port 3001)
pnpm nx dev @tara/web
# Or run directly
cd apps/tara/web && pnpm dev
Key features:
- Server-side rendering with Next.js App Router
- Internationalization with
next-intl(locale-based routing:/en/,/es/, etc.) - UI built with Radix UI primitives, Tailwind CSS, and
@tara/uicomponents - State management with Zustand and TanStack Query
- Animations with Framer Motion
- PWA with offline support and service worker
- Storybook for component development (port 6007)
Web app pages:
| Route | Description |
|---|---|
/[locale]/ |
Landing / home page |
/[locale]/meditate |
Meditation catalog |
/[locale]/meditate/[id] |
Individual meditation detail |
/[locale]/play/[id] |
Audio player page |
/[locale]/courses |
Course catalog |
/[locale]/courses/[id] |
Individual course detail |
/[locale]/timer |
Meditation timer |
/[locale]/library |
User library (favorites, downloads) |
/[locale]/progress |
Progress dashboard |
/[locale]/search |
Content search |
/[locale]/teachers/[id] |
Teacher profile |
/[locale]/settings/profile |
Profile settings |
/[locale]/settings/security |
Security settings |
/[locale]/settings/subscription |
Subscription settings |
/[locale]/subscription |
Subscription plans and billing |
/[locale]/login |
Login |
/[locale]/signup |
Registration |
Mobile Application#
The Tara mobile app is built with Expo 51 and React Native 0.74, using Expo Router for file-based navigation.
# Start the Expo development server
cd apps/tara/mobile && pnpm start
# Start with iOS Simulator
cd apps/tara/mobile && pnpm ios
# Start with Android Emulator
cd apps/tara/mobile && pnpm android
Mobile app screens (Expo Router file-based routing):
| Tab / Route | Description |
|---|---|
(tabs)/index |
Home feed |
(tabs)/meditate |
Meditation catalog |
(tabs)/timer |
Meditation timer |
(tabs)/progress |
Progress and streaks |
(tabs)/profile |
User profile |
meditation/[id] |
Meditation detail |
player/[id] |
Audio player |
courses |
Course catalog |
course/* |
Course detail |
search |
Content search |
library |
User library |
breathing |
Breathing exercises |
settings |
App settings |
storage |
Download management |
(onboarding)/* |
Onboarding flow |
Key mobile dependencies:
expo-avfor audio playbackexpo-file-systemfor offline downloadsexpo-notificationsfor push notificationsreact-native-purchases(RevenueCat) for in-app subscriptionsreact-native-reanimatedfor animationszustandfor state management
EAS Build Profiles:
| Profile | Distribution | iOS | Android |
|---|---|---|---|
development |
internal | Simulator build | APK (debug) |
preview |
internal | Device build | APK (release) |
production |
store | App Store build | AAB (release) |
Building#
Build All Tara Projects#
pnpm nx run-many --target=build --projects=tag:scope:tara
Build Individual Projects#
# API (TypeScript via @nx/js:tsc)
pnpm nx build @tara/api
# Output: dist/apps/tara/api/
# Web (Next.js build)
pnpm nx build @tara/web
# Output: apps/tara/web/.next/ and apps/tara/web/out/
# Database library (requires Prisma generate first)
pnpm nx build @tara/database
# Output: dist/libs/tara/database/
# UI library
pnpm nx build @tara/ui
# Output: dist/libs/tara/ui/
# Analytics library
pnpm nx build @tara/analytics
# Output: dist/libs/tara/analytics/
# Content library
pnpm nx build @tara/content
# Output: dist/libs/tara/content/
Build Mobile (EAS)#
cd apps/tara/mobile
# Development build (for simulators)
eas build --profile development --platform ios
eas build --profile development --platform android
# Preview build (for internal testing)
eas build --profile preview --platform all
# Production build (for app stores)
eas build --profile production --platform all
Testing#
Test Runner Configuration#
| Project | Runner | Executor | Config File |
|---|---|---|---|
@tara/api |
Vitest | nx:run-commands |
apps/tara/api/vitest.config.ts |
@tara/web |
Vitest | nx:run-commands |
apps/tara/web/vitest.config.ts |
@tara/mobile |
Jest | (package script) | jest-expo preset |
@tara/database |
Vitest | @nx/vite:test |
libs/tara/database/vitest.config.ts |
@tara/ui |
Vitest | @nx/vite:test |
libs/tara/ui/vitest.config.ts |
@tara/analytics |
Vitest | @nx/vite:test |
libs/tara/analytics/vitest.config.ts |
Running Tests#
# Run all Tara tests
pnpm nx run-many --target=test --projects=tag:scope:tara
# Individual project tests
pnpm nx test @tara/api
pnpm nx test @tara/web
pnpm nx test @tara/database
pnpm nx test @tara/ui
# Mobile tests
cd apps/tara/mobile && pnpm test
# Watch mode
cd apps/tara/api && pnpm test:watch
cd apps/tara/web && pnpm test:watch
# Coverage
cd apps/tara/web && pnpm test:coverage
API test coverage thresholds (configured in vitest.config.ts):
- Lines: 70%
- Functions: 70%
- Branches: 70%
- Statements: 70%
Integration Tests#
# API integration tests (requires running database and Redis)
cd apps/tara/api && pnpm test:integration
# Run both unit and integration tests
cd apps/tara/api && pnpm test:all
E2E Tests (Web)#
The web application uses Playwright for end-to-end testing.
# Install Playwright browsers (first time)
pnpm nx e2e:install @tara/web
# Run all E2E tests
pnpm nx e2e @tara/web
# Run with UI mode (interactive)
pnpm nx e2e:ui @tara/web
# Run in debug mode
pnpm nx e2e @tara/web --configuration=debug
# Run headed (visible browser)
pnpm nx e2e @tara/web --configuration=headed
# View test report
pnpm nx e2e:report @tara/web
# Generate test code
cd apps/tara/web && pnpm e2e:codegen
E2E page objects are located in apps/tara/web/e2e/pages/:
auth.page.ts- Authentication flowsmeditation.page.ts- Meditation browsingprogress.page.ts- Progress dashboardsubscription.page.ts- Subscription managementtimer.page.ts- Meditation timer
E2E Tests (Mobile)#
The mobile application uses Maestro for end-to-end testing.
cd apps/tara/mobile
# Run all mobile E2E flows
pnpm e2e
# Run smoke suite
pnpm e2e:smoke
# Run regression suite
pnpm e2e:regression
# Run specific flow suites
pnpm e2e:auth
pnpm e2e:meditation
pnpm e2e:offline
# Interactive test recording
pnpm e2e:studio
Load Testing#
The API includes k6 load test scripts in apps/tara/api/test/load/.
# Run default load test scenario
pnpm nx load-test @tara/api
# Smoke test (quick validation)
pnpm nx load-test:smoke @tara/api
# Stress test (high load)
pnpm nx load-test:stress @tara/api
Linting#
# Lint all Tara projects
pnpm nx run-many --target=lint --projects=tag:scope:tara
# Lint individual projects
pnpm nx lint @tara/api
pnpm nx lint @tara/web
pnpm nx lint @tara/ui
# Type checking (web)
pnpm nx typecheck @tara/web
Storybook (UI Development)#
# Start Storybook dev server (port 6007)
pnpm nx storybook @tara/web
# Build static Storybook
pnpm nx storybook:build @tara/web
Lighthouse (Performance)#
# Run Lighthouse CI audit
pnpm nx lighthouse @tara/web
# Collect Lighthouse metrics
pnpm nx lighthouse:collect @tara/web
# Assert performance thresholds
pnpm nx lighthouse:assert @tara/web
# Run performance tests
pnpm nx test:performance @tara/web
Common Development Tasks#
Adding a New API Route#
-
Create a route directory under
apps/tara/api/src/routes/<name>/. -
Define the route file with Hono route handlers:
typescriptimport { OpenAPIHono } from '@hono/zod-openapi'; const router = new OpenAPIHono(); router.get('/', async (c) => { // Implementation return c.json({ success: true, data: [] }); }); export { router as myRouter }; -
Create an
index.tsbarrel export in the route directory. -
Mount the router in
apps/tara/api/src/app.ts:typescriptimport { myRouter } from './routes/my-route/index.js'; app.route('/api/v1/my-route', myRouter); -
Apply authentication middleware if needed:
typescriptapp.use('/api/v1/my-route/*', authMiddleware());
Adding a New Database Model#
-
Edit the Prisma schema at
libs/tara/database/prisma/schema.prisma. -
Regenerate the Prisma client:
bashpnpm nx run @tara/database:prisma:generate -
Create a migration:
bashpnpm nx run @tara/database:prisma:migrate:dev -
Export the new types from
libs/tara/database/src/index.ts. -
If the API uses Drizzle ORM for this model, also update
apps/tara/api/src/db/schema.tswith the Drizzle table definition.
Adding a New Web Page#
-
Create a page file under the App Router directory:
textapps/tara/web/src/app/[locale]/(app)/<name>/page.tsx -
The page automatically gets locale-based routing via
next-intl. -
Add translations to the relevant message files.
-
Use
@tara/uicomponents and@tara/contenthooks for content fetching.
Adding Content to the Catalog#
The content catalog is stored as static files in apps/tara/content/:
meditations/- Guided meditation definitionscourses/- Multi-lesson course definitionsteachers/- Teacher profilessounds/- Ambient sound definitionscollections/- Curated content collectionsschemas/- Validation schemas for content files
Add new content files following the schema format, then seed the database:
pnpm nx run @tara/database:db:seed
Working with Subscriptions#
The subscription system supports three platforms:
- Web (Stripe) - Handled via
/api/v1/subscription/checkoutand webhook - iOS (App Store) - Verified via
/api/v1/subscription/ios/verify - Android (Google Play) - Verified via
/api/v1/subscription/android/verify - Mobile (RevenueCat) - The mobile app uses
react-native-purchases
The webhook endpoint (/api/v1/subscription/webhook) is public (no auth) to
allow Stripe to deliver payment events.
Debugging Tips#
API Not Starting#
- Verify PostgreSQL is running:
docker ps | grep postgres - Verify Redis is running:
docker ps | grep redis - Check the
DATABASE_URLenvironment variable points to a valid database - Check that the Prisma client is generated:
pnpm nx run @tara/database:prisma:generate - Review the
/healthendpoint response for service-level status
Database Issues#
- If migrations are out of sync, reset:bash
cd libs/tara/database && npx prisma migrate reset - For schema drift during development:bash
cd libs/tara/database && npx prisma db push - View the database with Prisma Studio:bash
pnpm nx run @tara/database:prisma:studio
Web Application Issues#
- The web app uses
output: 'standalone'in Next.js config (not static export) - Ensure workspace packages are listed in
transpilePackagesinnext.config.js - i18n routing issues: check that the locale prefix matches a supported locale
- CDN/asset issues: verify
NEXT_PUBLIC_CDN_URLis set correctly (or empty for local development) - Security headers are configured in
next.config.jsheaders()function
Mobile Application Issues#
- Clear Expo cache:
expo start --clear - Reset Metro bundler cache:
npx react-native start --reset-cache - If native dependencies change, rebuild the development client:bash
eas build --profile development --platform <ios|android> - Check EAS build logs on
https://expo.devfor build failures - For purchase testing, use RevenueCat sandbox environments
Rate Limiting#
The API implements tiered rate limiting:
| Tier | Requests/min |
|---|---|
| Anonymous | 60 |
| Free | 300 |
| Premium | 1000 |
Rate limit headers are included in all API responses:
X-RateLimit-Limit- Maximum requests per windowX-RateLimit-Remaining- Requests remainingX-RateLimit-Reset- Unix timestamp when the limit resets
Authentication Flow#
The API uses JWT tokens with refresh token rotation:
- Client authenticates via
/api/v1/auth/login(email/password) or OAuth (Apple/Google) - Server returns an access token and refresh token
- Access tokens are short-lived; include in
Authorization: Bearer <token> - Refresh tokens are used to obtain new access tokens without re-authentication
- Protected routes use
authMiddleware()which validates the JWT
Error Response Format#
All API errors follow RFC 7807 Problem Details:
{
"type": "https://api.tara-app.com/problems/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "Invalid email format",
"instance": "/api/v1/auth/register",
"requestId": "tara_abc123",
"timestamp": "2024-01-15T12:00:00Z"
}
Performance Considerations#
- The API uses Drizzle ORM for query building alongside Prisma for schema management and type generation
- Denormalized counters (
playCount,completionCount,favoriteCount) on theMeditationmodel avoid expensive JOINs for catalog listings - Redis is used for session caching, rate limit state, and feature flag storage
- The web app uses
next/imagewith WebP/AVIF formats and CDN-based caching - Static assets (
/_next/static/) are cached withmax-age=31536000, immutable - Audio files are cached for 7 days via
Cache-Controlheaders