synthra 0.1.0

data/tech_docs/templates/README.md

@@ -0,0 +1,805 @@
+# Schema Templates Gallery
+
+Production-ready schema templates for common use cases. Copy and customize for your needs.
+
+## Table of Contents
+
+- [API Response](#api-response)
+- [User Authentication](#user-authentication)
+- [E-Commerce](#e-commerce)
+- [Social Media](#social-media)
+- [Webhook Events](#webhook-events)
+- [Database Seeding](#database-seeding)
+- [GraphQL Types](#graphql-types)
+- [IoT Sensor Data](#iot-sensor-data)
+- [Financial Transactions](#financial-transactions)
+- [Logging & Analytics](#logging--analytics)
+- [Messaging & Chat](#messaging--chat)
+- [Content Management](#content-management)
+
+---
+
+## API Response
+
+Standard REST API response wrapper with pagination.
+
+```dsl
+# api_response.dsl
+APIResponse:
+  success: boolean(true:95%)
+  data: object
+  meta: ResponseMeta
+  errors?: array(APIError, 0..3)
+
+ResponseMeta:
+  request_id: uuid
+  timestamp: now
+  version: const("1.0")
+  pagination?: Pagination
+
+Pagination:
+  page: number(1..100)
+  per_page: number(10..100)
+  total_items: number(0..10000)
+  total_pages: number(1..100)
+
+APIError:
+  code: enum(VALIDATION_ERROR, NOT_FOUND, UNAUTHORIZED, RATE_LIMITED)
+  message: text(20..100)
+  field?: text(5..30)
+```
+
+**Ruby Usage:**
+```ruby
+schema = FakeDataDSL.load('api_response.dsl')
+response = schema.generate(seed: 42)
+```
+
+**CLI Usage:**
+```bash
+fake_data_dsl generate APIResponse -d schemas/ --pretty
+```
+
+---
+
+## User Authentication
+
+Complete user authentication system with sessions and tokens.
+
+```dsl
+# auth.dsl
+User:
+  id: uuid(unique: true)
+  email: email
+  password_hash: password_hash
+  first_name: first_name
+  last_name: last_name
+  full_name: custom(:full_name)
+  role: enum(user:80%, admin:5%, moderator:15%)
+  status: enum(active:85%, suspended:5%, pending:10%)
+  email_verified: boolean(true:90%)
+  created_at: past_date(2y)
+  updated_at: past_date(30d)
+  last_login?: past_date(7d)
+
+Session:
+  id: uuid
+  user_id: Ref(User.id)
+  token: sha256
+  ip_address: ip
+  user_agent: user_agent
+  expires_at: future_date(7d)
+  created_at: now
+
+AuthToken:
+  access_token: sha256
+  refresh_token: sha256
+  token_type: const("Bearer")
+  expires_in: number(3600..86400)
+  scope: enum(read, write, admin)
+  user_id: Ref(User.id)
+
+LoginAttempt:
+  id: uuid
+  email: email
+  success: boolean(true:85%)
+  ip_address: ip
+  user_agent: user_agent
+  timestamp: now
+  failure_reason?: enum(invalid_password, account_locked, email_not_found)
+```
+
+**Register custom function:**
+```ruby
+FakeDataDSL.register_function(:full_name) do |ctx|
+  "#{ctx['first_name']} #{ctx['last_name']}"
+end
+```
+
+---
+
+## E-Commerce
+
+Complete e-commerce system with products, orders, and inventory.
+
+```dsl
+# ecommerce.dsl
+Product:
+  id: uuid(unique: true)
+  sku: sku
+  name: product_name
+  description: text(50..500)
+  price: money(range: 9.99..999.99)
+  sale_price?: money(range: 4.99..499.99)
+  category: product_category
+  subcategory: product_subcategory
+  brand: company_name
+  in_stock: boolean(true:85%)
+  stock_quantity: number(0..1000)
+  images: array(url, 1..5)
+  tags: array(text(3..20), 0..10)
+  rating: number(1..5)
+  review_count: number(0..500)
+  created_at: past_date(2y)
+
+Order:
+  id: uuid(unique: true)
+  order_number: digit_sequence(start: "ORD-", pad: 8)
+  customer: Customer
+  customer_id: copy("customer.id")
+  items: array(OrderItem, 1..10)
+  subtotal: custom(:calculate_subtotal)
+  tax: custom(:calculate_tax)
+  shipping: money(range: 0..50)
+  total: custom(:calculate_total)
+  status: enum(pending:20%, processing:15%, shipped:30%, delivered:30%, cancelled:5%)
+  shipping_address: Address
+  billing_address: Address
+  payment_method: PaymentMethod
+  created_at: past_date(30d)
+  updated_at: past_date(7d)
+
+OrderItem:
+  id: uuid
+  product_id: Ref(Product.id)
+  product_name: product_name
+  quantity: number(1..5)
+  unit_price: money(range: 9.99..999.99)
+  discount?: number(0..50)
+
+Customer:
+  id: uuid(unique: true)
+  email: email
+  first_name: first_name
+  last_name: last_name
+  phone?: phone
+  tier: enum(standard:70%, silver:20%, gold:10%)
+  lifetime_value: money(range: 0..10000)
+  created_at: past_date(3y)
+
+Address:
+  street: address
+  city: city
+  state: state
+  postal_code: postal_code
+  country: country_code
+
+PaymentMethod:
+  type: enum(credit_card:60%, paypal:25%, apple_pay:10%, bank_transfer:5%)
+  last_four?: text(4)
+  card_type?: credit_card_type
+```
+
+**Custom functions:**
+```ruby
+FakeDataDSL.register_function(:calculate_subtotal) do |ctx|
+  items = ctx['items'] || []
+  items.sum { |item| (item['quantity'] || 1) * (item['unit_price'] || 0) }.round(2)
+end
+
+FakeDataDSL.register_function(:calculate_tax) do |ctx|
+  ((ctx['subtotal'] || 0) * 0.08).round(2)
+end
+
+FakeDataDSL.register_function(:calculate_total) do |ctx|
+  subtotal = ctx['subtotal'] || 0
+  tax = ctx['tax'] || 0
+  shipping = ctx['shipping'] || 0
+  (subtotal + tax + shipping).round(2)
+end
+```
+
+---
+
+## Social Media
+
+Social media platform with posts, comments, and followers.
+
+```dsl
+# social_media.dsl
+SocialUser:
+  id: snowflake_id
+  username: social_handle
+  display_name: full_name
+  bio?: text(0..160)
+  avatar_url: avatar
+  verified: boolean(true:5%)
+  follower_count: number(0..1000000)
+  following_count: number(0..5000)
+  post_count: number(0..10000)
+  joined_at: past_date(5y)
+  location?: city
+
+Post:
+  id: snowflake_id
+  author: SocialUser
+  author_id: copy("author.id")
+  content: text(1..280)
+  media?: array(MediaAttachment, 0..4)
+  hashtags: array(hashtag_text, 0..5)
+  mentions: array(social_handle, 0..10)
+  like_count: number(0..100000)
+  repost_count: number(0..10000)
+  reply_count: number(0..5000)
+  created_at: past_date(30d)
+  is_reply: boolean(true:30%)
+  reply_to_id?: snowflake_id
+
+MediaAttachment:
+  id: uuid
+  type: enum(image:70%, video:20%, gif:10%)
+  url: url
+  thumbnail_url?: url
+  width: number(100..4000)
+  height: number(100..4000)
+  duration_ms?: number(1000..600000)
+
+Comment:
+  id: uuid
+  post_id: Ref(Post.id)
+  author_id: Ref(SocialUser.id)
+  content: text(1..500)
+  like_count: number(0..1000)
+  created_at: past_date(7d)
+  is_edited: boolean(true:10%)
+
+Follow:
+  id: uuid
+  follower_id: Ref(SocialUser.id)
+  following_id: Ref(SocialUser.id)
+  created_at: past_date(2y)
+  notifications_enabled: boolean(true:60%)
+```
+
+---
+
+## Webhook Events
+
+Generic webhook event system for integrations.
+
+```dsl
+# webhooks.dsl
+WebhookEvent:
+  id: uuid
+  type: enum(user.created, user.updated, order.placed, order.shipped, payment.completed)
+  version: const("1.0")
+  created_at: now
+  data: WebhookPayload
+  metadata: WebhookMetadata
+
+WebhookPayload:
+  object_type: enum(user, order, payment, subscription)
+  object_id: uuid
+  previous_attributes?: object
+  current_attributes: object
+
+WebhookMetadata:
+  request_id: uuid
+  idempotency_key: uuid
+  webhook_id: uuid
+  attempt: number(1..5)
+  timestamp: unix_timestamp_ms
+
+WebhookDelivery:
+  id: uuid
+  event_id: Ref(WebhookEvent.id)
+  endpoint_url: url
+  status: enum(pending, delivered, failed, retrying)
+  http_status?: number(200..599)
+  response_time_ms?: number(50..5000)
+  error_message?: text(10..200)
+  attempts: number(1..5)
+  next_retry_at?: future_date(1h)
+  delivered_at?: past_date(1h)
+
+WebhookEndpoint:
+  id: uuid
+  url: url
+  secret: sha256
+  events: array(enum(user.created, user.updated, order.placed), 1..5)
+  enabled: boolean(true:90%)
+  created_at: past_date(1y)
+```
+
+---
+
+## Database Seeding
+
+Database seed data for development environments.
+
+```dsl
+# database_seed.dsl
+Department:
+  id: id_sequence
+  name: department_corporate
+  code: text(2..4)
+  manager_id?: Ref(Employee.id)
+  budget: money(range: 50000..5000000)
+  created_at: past_date(5y)
+
+Employee:
+  id: id_sequence
+  employee_number: digit_sequence(start: "EMP", pad: 6)
+  email: email
+  first_name: first_name
+  last_name: last_name
+  department_id: Ref(Department.id)
+  job_title: job_title
+  salary: money(range: 30000..250000)
+  hire_date: past_date(10y)
+  termination_date?: past_date(1y)
+  is_active: boolean(true:90%)
+  manager_id?: Ref(Employee.id)
+
+Project:
+  id: id_sequence
+  name: catch_phrase
+  code: text(3..8)
+  department_id: Ref(Department.id)
+  lead_id: Ref(Employee.id)
+  budget: money(range: 10000..1000000)
+  start_date: past_date(2y)
+  end_date?: future_date(1y)
+  status: enum(planning:10%, active:50%, completed:30%, cancelled:10%)
+
+TimeEntry:
+  id: id_sequence
+  employee_id: Ref(Employee.id)
+  project_id: Ref(Project.id)
+  date: past_date(30d)
+  hours: number(1..8)
+  description: text(10..200)
+  billable: boolean(true:80%)
+  approved: boolean(true:85%)
+```
+
+---
+
+## GraphQL Types
+
+GraphQL-style types with connections and edges.
+
+```dsl
+# graphql_types.dsl
+PageInfo:
+  hasNextPage: boolean
+  hasPreviousPage: boolean
+  startCursor: uuid
+  endCursor: uuid
+
+UserConnection:
+  edges: array(UserEdge, 0..20)
+  pageInfo: PageInfo
+  totalCount: number(0..1000)
+
+UserEdge:
+  node: GraphQLUser
+  cursor: uuid
+
+GraphQLUser:
+  id: uuid
+  email: email
+  name: full_name
+  avatar: avatar
+  createdAt: timestamp
+  updatedAt: timestamp
+  posts: PostConnection
+
+PostConnection:
+  edges: array(PostEdge, 0..10)
+  pageInfo: PageInfo
+  totalCount: number(0..100)
+
+PostEdge:
+  node: GraphQLPost
+  cursor: uuid
+
+GraphQLPost:
+  id: uuid
+  title: text(10..100)
+  body: paragraph(1..3)
+  author: GraphQLUser
+  publishedAt?: timestamp
+  tags: array(text(3..20), 0..5)
+```
+
+---
+
+## IoT Sensor Data
+
+IoT device telemetry and sensor readings.
+
+```dsl
+# iot.dsl
+Device:
+  id: uuid(unique: true)
+  device_id: text(10..20)
+  name: text(5..50)
+  type: enum(temperature, humidity, motion, light, air_quality)
+  location: DeviceLocation
+  firmware_version: app_version
+  battery_level?: number(0..100)
+  is_online: boolean(true:90%)
+  last_seen: past_date(1h)
+  registered_at: past_date(2y)
+
+DeviceLocation:
+  building: text(5..30)
+  floor: number(1..50)
+  room: text(3..20)
+  latitude: latitude
+  longitude: longitude
+
+SensorReading:
+  id: uuid
+  device_id: Ref(Device.id)
+  timestamp: now
+  reading_type: enum(temperature, humidity, motion, light, co2, pm25)
+  value: number(0..1000)
+  unit: enum(celsius, fahrenheit, percent, lux, ppm, ug_m3)
+  quality: enum(good:80%, moderate:15%, poor:5%)
+
+Alert:
+  id: uuid
+  device_id: Ref(Device.id)
+  type: enum(threshold_exceeded, device_offline, battery_low, anomaly_detected)
+  severity: enum(info:40%, warning:35%, critical:20%, emergency:5%)
+  message: text(20..200)
+  acknowledged: boolean(true:60%)
+  acknowledged_by?: email
+  acknowledged_at?: past_date(1d)
+  created_at: past_date(7d)
+
+Telemetry:
+  device_id: Ref(Device.id)
+  timestamp: now
+  cpu_usage: number(0..100)
+  memory_usage: number(0..100)
+  network_latency_ms: number(1..500)
+  uptime_seconds: number(0..31536000)
+```
+
+---
+
+## Financial Transactions
+
+Banking and financial transaction data.
+
+```dsl
+# financial.dsl
+BankAccount:
+  id: uuid(unique: true)
+  account_number: account_number
+  routing_number: bank_routing_number
+  type: enum(checking:60%, savings:30%, money_market:10%)
+  balance: money(range: 0..1000000)
+  currency: currency
+  holder_name: full_name
+  opened_at: past_date(10y)
+  status: enum(active:90%, frozen:5%, closed:5%)
+
+Transaction:
+  id: uuid
+  reference_number: digit_sequence(start: "TXN", pad: 12)
+  account_id: Ref(BankAccount.id)
+  type: enum(deposit:30%, withdrawal:25%, transfer:25%, payment:15%, fee:5%)
+  amount: transaction_amount
+  currency: currency
+  balance_after: money(range: 0..1000000)
+  description: text(10..100)
+  category: enum(income, expense, transfer, fee, refund)
+  merchant?: MerchantInfo
+  status: enum(completed:85%, pending:10%, failed:3%, reversed:2%)
+  created_at: past_date(90d)
+  processed_at?: past_date(90d)
+
+MerchantInfo:
+  name: company_name
+  category: enum(retail, food, transport, utilities, entertainment)
+  mcc_code: text(4)
+  city?: city
+  country: country_code
+
+Investment:
+  id: uuid
+  account_id: Ref(BankAccount.id)
+  symbol: text(1..5)
+  name: company_name
+  type: enum(stock:50%, etf:25%, bond:15%, mutual_fund:10%)
+  quantity: number(1..10000)
+  purchase_price: money(range: 1..5000)
+  current_price: money(range: 1..5000)
+  purchase_date: past_date(5y)
+
+Wire Transfer:
+  id: uuid
+  reference: digit_sequence(start: "WIRE", pad: 10)
+  sender_account: BankAccount
+  sender_account_id: copy("sender_account.id")
+  recipient_name: full_name
+  recipient_iban: iban
+  recipient_swift: bank_swift_bic
+  amount: transaction_amount
+  currency: currency
+  fee: money(range: 10..50)
+  purpose: text(10..100)
+  status: enum(initiated:10%, processing:20%, completed:60%, failed:5%, cancelled:5%)
+  initiated_at: past_date(7d)
+  completed_at?: past_date(7d)
+```
+
+---
+
+## Logging & Analytics
+
+Application logs and analytics events.
+
+```dsl
+# logging.dsl
+LogEntry:
+  id: uuid
+  timestamp: now
+  level: enum(DEBUG:10%, INFO:50%, WARN:25%, ERROR:12%, FATAL:3%)
+  service: enum(api, worker, scheduler, auth, payment)
+  message: text(20..500)
+  context: LogContext
+  stack_trace?: text(100..2000)
+
+LogContext:
+  request_id: uuid
+  user_id?: uuid
+  session_id?: uuid
+  ip_address: ip
+  user_agent?: user_agent
+  duration_ms?: number(1..30000)
+  http_method?: enum(GET, POST, PUT, DELETE, PATCH)
+  http_path?: text(5..100)
+  http_status?: number(200..599)
+
+AnalyticsEvent:
+  id: uuid
+  event_name: enum(page_view, button_click, form_submit, purchase, signup, login)
+  timestamp: now
+  user_id?: uuid
+  session_id: uuid
+  device_id: uuid
+  properties: EventProperties
+  context: AnalyticsContext
+
+EventProperties:
+  page_url?: url
+  referrer?: url
+  element_id?: text(5..50)
+  value?: text(1..100)
+  revenue?: money(range: 0..10000)
+  currency?: currency
+
+AnalyticsContext:
+  app_version: app_version
+  platform: enum(web:60%, ios:25%, android:15%)
+  os: enum(Windows, macOS, Linux, iOS, Android)
+  browser?: enum(Chrome, Firefox, Safari, Edge)
+  screen_width: number(320..3840)
+  screen_height: number(480..2160)
+  locale: language_code
+  timezone: timezone
+
+Metric:
+  name: enum(response_time, error_rate, throughput, cpu_usage, memory_usage)
+  value: number(0..100000)
+  unit: enum(ms, percent, requests_per_second, bytes)
+  tags: MetricTags
+  timestamp: now
+
+MetricTags:
+  service: enum(api, worker, database, cache)
+  environment: enum(production, staging, development)
+  region: enum(us-east-1, us-west-2, eu-west-1, ap-southeast-1)
+  instance_id: text(10..20)
+```
+
+---
+
+## Messaging & Chat
+
+Real-time messaging and chat application.
+
+```dsl
+# messaging.dsl
+Conversation:
+  id: uuid
+  type: enum(direct:60%, group:40%)
+  name?: text(3..50)
+  participants: array(ConversationParticipant, 2..50)
+  created_by: Ref(ChatUser.id)
+  created_at: past_date(1y)
+  updated_at: past_date(1h)
+  last_message_at?: past_date(1h)
+
+ConversationParticipant:
+  user_id: Ref(ChatUser.id)
+  role: enum(member:80%, admin:15%, owner:5%)
+  joined_at: past_date(1y)
+  muted: boolean(true:10%)
+  last_read_at?: past_date(1h)
+
+ChatUser:
+  id: uuid(unique: true)
+  username: social_handle
+  display_name: full_name
+  avatar_url: avatar
+  status: enum(online:30%, away:20%, busy:10%, offline:40%)
+  last_seen: past_date(1d)
+
+Message:
+  id: snowflake_id
+  conversation_id: Ref(Conversation.id)
+  sender_id: Ref(ChatUser.id)
+  content: message_text
+  type: enum(text:85%, image:8%, file:5%, system:2%)
+  attachments?: array(MessageAttachment, 0..5)
+  reactions: array(Reaction, 0..20)
+  reply_to_id?: snowflake_id
+  edited_at?: past_date(1h)
+  deleted_at?: past_date(1h)
+  created_at: past_date(30d)
+
+MessageAttachment:
+  id: uuid
+  type: enum(image, video, audio, document)
+  url: url
+  filename: file_name
+  size_bytes: number(1000..100000000)
+  mime_type: mime_type
+
+Reaction:
+  user_id: Ref(ChatUser.id)
+  emoji: enum(👍, ❤️, 😂, 😮, 😢, 🎉)
+  created_at: past_date(7d)
+
+TypingIndicator:
+  conversation_id: Ref(Conversation.id)
+  user_id: Ref(ChatUser.id)
+  started_at: now
+  expires_at: future_date(5s)
+```
+
+---
+
+## Content Management
+
+CMS and content management system.
+
+```dsl
+# cms.dsl
+Article:
+  id: uuid(unique: true)
+  slug: text(10..100)
+  title: text(20..200)
+  excerpt: text(50..300)
+  content: paragraphs(3..10)
+  author: Author
+  author_id: copy("author.id")
+  category: Category
+  tags: array(Tag, 0..10)
+  featured_image?: MediaAsset
+  status: enum(draft:20%, published:70%, archived:10%)
+  published_at?: past_date(1y)
+  created_at: past_date(2y)
+  updated_at: past_date(30d)
+  view_count: number(0..100000)
+  reading_time_minutes: number(1..30)
+
+Author:
+  id: uuid
+  name: full_name
+  email: email
+  bio?: text(50..500)
+  avatar: avatar
+  social_links?: SocialLinks
+
+SocialLinks:
+  twitter?: url
+  linkedin?: url
+  github?: url
+  website?: url
+
+Category:
+  id: uuid
+  name: text(3..50)
+  slug: text(3..50)
+  description?: text(20..200)
+  parent_id?: uuid
+  article_count: number(0..1000)
+
+Tag:
+  id: uuid
+  name: text(2..30)
+  slug: text(2..30)
+  article_count: number(0..500)
+
+MediaAsset:
+  id: uuid
+  type: enum(image:70%, video:20%, document:10%)
+  url: url
+  alt_text?: text(10..100)
+  width?: number(100..4000)
+  height?: number(100..4000)
+  size_bytes: number(1000..50000000)
+  uploaded_at: past_date(1y)
+
+Comment:
+  id: uuid
+  article_id: Ref(Article.id)
+  author_name: full_name
+  author_email: email
+  content: text(10..1000)
+  status: enum(pending:20%, approved:70%, spam:10%)
+  parent_id?: uuid
+  created_at: past_date(30d)
+  likes: number(0..100)
+```
+
+---
+
+## Usage Tips
+
+### 1. Combine Templates
+
+```dsl
+# Combine auth + ecommerce
+Order:
+  customer: User  # From auth template
+  items: array(OrderItem, 1..5)  # From ecommerce template
+```
+
+### 2. Customize for Your Needs
+
+```dsl
+# Extend with custom fields
+User:
+  id: uuid
+  # ... base fields ...
+  tenant_id: uuid  # Multi-tenant extension
+  preferences: UserPreferences  # Custom extension
+```
+
+### 3. Use with Registry
+
+```ruby
+registry = FakeDataDSL::Registry.new
+registry.load_file('auth.dsl')
+registry.load_file('ecommerce.dsl')
+
+# Generate with cross-schema references
+order = registry.schema('Order').generate(registry: registry)
+```
+
+---
+
+## Next Steps
+
+- [CI/CD Integration Guide](../integration/ci_cd_guide.md)
+- [Complex Types Reference](../dsl/complex_types.md)
+- [Custom Types Guide](../api/custom_types.md)
+