Tara Naming Conventions

This document defines the naming conventions for all Tara-related code, assets, and configuration in the Oshun monorepo.

Overview#

Tara is a meditation platform designed to be fully App Store compliant. It shares meditation infrastructure with Lilith but maintains completely separate content, branding, and user data.

Canonical Object Model#

Use the following Tara object names consistently across shared contracts, search, routing, UI copy, and API adapters:

• ritual
  • a structured Tara practice definition, launch sequence, or guided entry wrapper
  • not a user progress record
  • canonical web launch path: /meditate/ritual/:ritualId
• meditation
  • reusable Tara catalog content such as guided, breathing, sleep, or transition practices
  • canonical web launch path: /meditate/session/:meditationId
• meditation session
  • a user execution or progress record created when someone starts or resumes a meditation
  • canonical web resume path: /meditate/resume/:sessionId

Do not use session as a blanket synonym for reusable Tara catalog content. When the object is launchable content, name it meditation. When the object is the user's in-progress or completed run, name it meditation session.

Meditation Subtypes#

Within the canonical meditation object model, use these subtype names consistently:

• guided
  • the default Tara meditation subtype for general guided or unguided practice
• breathing
  • a breath-led session such as box breathing, coherent breathing, or extended exhale work
• sleep
  • a sleep-first session optimized for bedtime descent, body scans, yoga nidra, or sleep stories
• transition
  • a state-shift session meant to move someone between contexts such as commute arrival, pre-meeting reset, or evening close

Breathing, sleep, and transition practices are not separate top-level Tara domains. They are canonical Tara meditation subtypes and should route through the meditation launch path unless explicitly modeled as rituals.

Project Naming#

Applications#

Tara-Specific Libraries#

Shared Meditation Libraries#

NPM Scopes#

@tara/* - Tara-Specific Packages#

Used for packages that are specific to the Tara platform and should not be used by other domains.

import { MeditationCard, Timer } from '@tara/ui';
import { taraDbClient } from '@tara/database';
import { useConfig } from '@tara/config';

@oshun/meditation-* - Shared Meditation Packages#

Used for packages that provide shared meditation infrastructure. These can be used by both Tara and Lilith.

import { MeditationPlayer } from '@oshun/meditation-player';
import { BreathingEngine } from '@oshun/meditation-breathing';
import { ProgressTracker } from '@oshun/meditation-progress';

Nx Tags#

Scope Tags#

Layer Tags#

Dependency Rules#

1. Tara can import from:

   • scope:shared (Oshun foundation)
   • scope:contracts (Shared contracts)
   • scope:auth (Authentication)
   • scope:meditation (Shared meditation)
   • scope:tara (Other Tara packages)

2. Tara cannot import from:

   • scope:lilith (Content isolation)
   • Other domain scopes

3. Meditation can import from:

   • scope:shared
   • scope:contracts
   • scope:meditation

File Naming#

TypeScript Files#

kebab-case.ts       # General files
kebab-case.spec.ts  # Test files
kebab-case.test.ts  # Test files (alternative)
index.ts            # Module entry points

Component Files#

ComponentName.tsx       # React components
ComponentName.spec.tsx  # Component tests
ComponentName.stories.tsx # Storybook stories

Configuration Files#

app.config.ts       # Application config
features.config.ts  # Feature flags
content.config.ts   # Content config

Database Naming#

Tables#

• Use snake_case for table names
• Use singular nouns (e.g., user, meditation, not users, meditations)
• Map to plural in Prisma with @@map()

Columns#

• Use snake_case for column names
• Foreign keys: {related_table}_id
• Timestamps: created_at, updated_at, deleted_at
• Boolean flags: is_active, is_published, is_premium

Indexes#

idx_{table}_{column}           # Single column index
idx_{table}_{col1}_{col2}      # Composite index
uniq_{table}_{column}          # Unique index

API Naming#

Endpoints#

GET    /api/v1/meditations           # List
GET    /api/v1/meditations/:id       # Get one
POST   /api/v1/meditations           # Create
PATCH  /api/v1/meditations/:id       # Update
DELETE /api/v1/meditations/:id       # Delete

Query Parameters#

?page=1&limit=20              # Pagination
?sort=created_at&order=desc   # Sorting
?category=sleep&premium=true  # Filtering
?search=morning               # Search

Environment Variables#

Prefixes#

Examples#

TARA_DATABASE_URL=postgresql://...
TARA_REDIS_PREFIX=tara:
TARA_API_PORT=3007
TARA_JWT_SECRET=...

MEDITATION_AUDIO_CDN_URL=https://...
MEDITATION_DOWNLOAD_MAX_SIZE=...

Content Naming#

Content Files#

{category}/{teacher-slug}/{content-slug}.mp3
{category}/{teacher-slug}/{content-slug}.metadata.json

Example:

meditations/sarah-chen/morning-peace.mp3
meditations/sarah-chen/morning-peace.metadata.json

Asset Files#

{type}-{name}-{variant}@{scale}.{ext}

Examples:

icon-meditation-filled@2x.png
icon-meditation-outline@3x.png
bg-sleep-gradient.jpg

Testing Naming#

Test Files#

{subject}.spec.ts          # Unit tests
{subject}.integration.ts   # Integration tests
{subject}.e2e.ts           # End-to-end tests

Test Descriptions#

describe('MeditationPlayer', () => {
  describe('play()', () => {
    it('should start playback when audio is loaded', () => {
      // ...
    });

    it('should throw error when no track is loaded', () => {
      // ...
    });
  });
});

Version Control#

Branch Naming#

feature/tara-{feature-name}
fix/tara-{bug-description}
chore/tara-{task-description}

Commit Messages#

feat(tara): add meditation player component
fix(tara): resolve audio playback on background
chore(meditation): update dependencies
docs(tara): add API documentation

Summary#