# 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

| Location           | Project Name  | Description             |
| ------------------ | ------------- | ----------------------- |
| `apps/tara/web`    | `tara-web`    | Web application         |
| `apps/tara/mobile` | `tara-mobile` | React Native mobile app |
| `apps/tara/api`    | `tara-api`    | Backend API service     |

### Tara-Specific Libraries

| Location              | Project Name     | NPM Package       | Description                |
| --------------------- | ---------------- | ----------------- | -------------------------- |
| `libs/tara/database`  | `tara-database`  | `@tara/database`  | Database schema and client |
| `libs/tara/ui`        | `tara-ui`        | `@tara/ui`        | UI component library       |
| `libs/tara/content`   | `tara-content`   | `@tara/content`   | Content management         |
| `libs/tara/features`  | `tara-features`  | `@tara/features`  | Feature modules            |
| `libs/tara/analytics` | `tara-analytics` | `@tara/analytics` | Analytics tracking         |
| `libs/tara/config`    | `tara-config`    | `@tara/config`    | Configuration management   |

### Shared Meditation Libraries

| Location                    | Project Name           | NPM Package                   | Description              |
| --------------------------- | ---------------------- | ----------------------------- | ------------------------ |
| `libs/meditation/core`      | `meditation-core`      | `@oshun/meditation-core`      | Core types and utilities |
| `libs/meditation/player`    | `meditation-player`    | `@oshun/meditation-player`    | Audio player engine      |
| `libs/meditation/timer`     | `meditation-timer`     | `@oshun/meditation-timer`     | Meditation timer         |
| `libs/meditation/breathing` | `meditation-breathing` | `@oshun/meditation-breathing` | Breathing exercises      |
| `libs/meditation/progress`  | `meditation-progress`  | `@oshun/meditation-progress`  | Progress tracking        |
| `libs/meditation/offline`   | `meditation-offline`   | `@oshun/meditation-offline`   | Offline support          |
| `libs/meditation/session`   | `meditation-session`   | `@oshun/meditation-session`   | Session management       |
| `libs/meditation/analytics` | `meditation-analytics` | `@oshun/meditation-analytics` | Meditation analytics     |

## NPM Scopes

### `@tara/*` - Tara-Specific Packages

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

```typescript
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.

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

## Nx Tags

### Scope Tags

| Tag                | Description                      |
| ------------------ | -------------------------------- |
| `scope:tara`       | Tara-specific code               |
| `scope:meditation` | Shared meditation infrastructure |

### Layer Tags

| Tag            | Description              |
| -------------- | ------------------------ |
| `layer:ui`     | UI components            |
| `layer:domain` | Business logic           |
| `layer:data`   | Data access              |
| `layer:infra`  | Infrastructure utilities |

### 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

| Prefix        | Description                 |
| ------------- | --------------------------- |
| `TARA_`       | Tara-specific variables     |
| `MEDITATION_` | Shared meditation variables |

### Examples

```bash
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

```typescript
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

| Category        | Convention                       | Example                      |
| --------------- | -------------------------------- | ---------------------------- |
| Apps            | `tara-{name}`                    | `tara-web`, `tara-api`       |
| Tara Libs       | `@tara/{name}`                   | `@tara/ui`, `@tara/database` |
| Meditation Libs | `@oshun/meditation-{name}`       | `@oshun/meditation-player`   |
| Nx Tags         | `scope:tara`, `scope:meditation` | -                            |
| Files           | `kebab-case.ts`                  | `meditation-player.ts`       |
| Database        | `snake_case`                     | `meditation_session`         |
| API             | `/api/v1/{resource}`             | `/api/v1/meditations`        |
| Env Vars        | `TARA_*`, `MEDITATION_*`         | `TARA_DATABASE_URL`          |