aurora-schema

# ✅ CORRECT
version: 0.0.1
boundedContextName: iam
moduleName: permission
description: >
    Module containing the permissions associated with each bounded context, to be used
    to manage access to each API.
aggregateProperties:
  - name: id

# ❌ INCORRECT - Missing description
version: 0.0.1
boundedContextName: iam
moduleName: permission
aggregateProperties:
  - name: id

# ❌ BAD
- name: stat          # → status
- name: dt            # → createdAt
- name: qty           # → quantity
- name: active        # → isActive (boolean prefix)
- name: author        # → authorId (if it's a foreign key)
  type: id

# ✅ GOOD
- name: status
- name: createdAt
- name: quantity
- name: isActive
- name: authorId
  type: id

# ❌ BAD - States the obvious
- name: price
  type: decimal
  description: The price of the book

# ✅ GOOD - Explains context and usage
- name: price
  type: decimal
  decimals: [10, 2]
  description: >
      Retail price in the store's base currency (configured in settings). Does
      not include taxes or discounts. Used as base for price calculations.

- name: isbn
  type: varchar
  maxLength: 17
  index: unique
  description: >
      International Standard Book Number in ISBN-13 format. Must be unique
      across all books. Validated against checksum algorithm. Example:
      978-3-16-148410-0

# ❌ Bad - arbitrary lengths
- name: username
  type: varchar
  maxLength: 50

- name: description
  type: varchar
  maxLength: 500

# ✅ Good - byte-optimized lengths
- name: username
  type: varchar
  maxLength: 64
  description: >
      User's display name. Max 64 characters.

- name: description
  type: varchar
  maxLength: 510
  description: >
      Brief description of the item. Max 510 characters.

# ✅ CORRECT
- name: id
  type: id
  primaryKey: true
  description: >
      Unique identifier for the record. UUID v4 format, generated automatically
      on creation.

# ❌ INCORRECT - Remove length property
- name: id
  type: id
  length: 36  # ← DELETE THIS
  primaryKey: true

# Standard across all modules:
- name: id             # Not: ID, _id, uuid, identifier
- name: createdAt      # Not: created, createdDate, createTime
- name: updatedAt      # Not: updated, modifiedAt, updateTime
- name: deletedAt      # Not: deleted, removedAt, deletionDate
- name: isActive       # Not: active, enabled, status

# Find all Aurora YAMLs
fd -e yaml -e yml aurora

# Find specific module
fd "book.aurora.yaml"

## Analysis of [module].aurora.yaml

### Summary
- Total fields: X
- Fields without description: Y
- Naming improvements needed: Z
- Module has description: Yes/No

### Module Description ❌ (if missing)
**Suggested:**
```yaml
description: >
    [Purpose and role within bounded context]

---

## Editing Workflow

### Creating Fields

```yaml
- name: publishedAt
  type: timestamp
  nullable: true
  description: >
      Timestamp when the book was published. NULL indicates unpublished.
      Automatically set when status changes to PUBLISHED.

# Before
- name: status
  type: varchar

# After (changing to enum)
- name: status
  type: enum
  enumOptions: [DRAFT, PUBLISHED, ARCHIVED]
  description: >
      Current publication status. DRAFT: Not ready. PUBLISHED: Available to
      readers. ARCHIVED: Preserved but no longer available.

# Search for field references
rg "fieldName" cliter/ -g "*.aurora.yaml"

- name: status
  type: enum
  enumOptions: [PENDING, APPROVED, REJECTED, CANCELLED]
  defaultValue: PENDING
  description: >
      Workflow status. PENDING: Awaiting review. APPROVED: Accepted and active.
      REJECTED: Denied (see rejectionReason). CANCELLED: Withdrawn by user.

- name: deletedAt
  type: timestamp
  nullable: true
  description: >
      Soft delete timestamp. NULL means active record. When set, record is
      excluded from normal queries. Enables audit trail and recovery.

- name: amount
  type: decimal
  decimals: [12, 2]
  description: >
      Monetary amount in smallest currency unit with 2 decimal places.
      Currency determined by currencyCode field.

- name: currencyCode
  type: char
  length: 3
  description: >
      ISO 4217 currency code (USD, EUR, GBP). Must be valid and supported.

- name: slug
  type: varchar
  maxLength: 2046
  index: unique
  description: >
      URL-friendly identifier. Lowercase, hyphenated. Auto-generated from name
      if not provided. Example: "my-awesome-product". Max 2046 chars for URL
      compatibility.

# Find all Aurora YAMLs
fd -e yaml aurora

# Search for fields without descriptions
rg -A1 "^  - name:" cliter/ -g "*.aurora.yaml" | rg -v "description:"

# Find id fields with length (incorrect)
rg -A2 "type: id" cliter/ -g "*.aurora.yaml" | rg "length:"

# Check for missing module descriptions
rg -L "^description:" cliter/ -g "*.aurora.yaml"

# Search for field usage across modules
rg "fieldName" cliter/ -g "*.aurora.yaml"

# Validate YAML syntax
yamllint cliter/**/*.aurora.yaml

User explicitly requested edit? ────YES───> Edit mode
      │
      NO
      │
Is this an analysis request? ────YES───> Analysis mode
      │
      NO
      │
Ask user for clarification

Is it a UUID identifier? ────YES───> type: id (NO length!)
      │
      NO
      │
Is it true/false? ────YES───> type: boolean (use is*/has*/can* prefix)
      │
      NO
      │
Is it money? ────YES───> type: decimal with decimals: [12, 2]
      │
      NO
      │
Fixed set of options? ────YES───> type: enum with enumOptions
      │
      NO
      │
Date and time? ────YES───> type: timestamp
      │
      NO
      │
Short text (< 255 chars)? ────YES───> type: varchar with maxLength
      │
      NO
      │
Long text? ────YES───> type: text
      │
      NO
      │
Review use case and choose appropriate type

## Schema Changes - 2026-01-17

### tesla/model.aurora.yaml

#### Created
- `isActive` (boolean) - Flag to indicate if model is currently available

#### Modified
- `status`: Changed type from `varchar` to `enum` with options [ACTIVE, INACTIVE, DISCONTINUED]
- Module: Added `description` property explaining module purpose

#### Deleted
- `legacyCode` (varchar) - Removed after confirming no dependencies

#### Fixed
- `id`: Removed `length: 36` property (not needed for id type)