# ==============================================================================
# FASE 4: DDL-to-Backend Complete Mapping Matrix
# ==============================================================================
# Task: TASK-2026-02-05-ANALISIS-VALIDACION-MODELADO-BD
# Phase: 4 - Backend Architecture Analysis
# Generated: 2026-02-05
# Agent: Backend Architecture Specialist (Claude Opus 4.6)
# ==============================================================================

metadata:
  project: trading-platform (OrbiQuant IA)
  total_ddl_tables: 101
  total_schemas: 11
  backend_architecture: "Express.js 5.0.1 + Raw SQL (pg Pool) - NO ORM"
  entity_pattern: "TypeScript interfaces in types/*.ts (NOT TypeORM entities)"
  repository_pattern: "Custom repository classes with raw SQL queries"
  date_generated: "2026-02-05"

# ==============================================================================
# ARCHITECTURE NOTES
# ==============================================================================
# This project does NOT use TypeORM, Prisma, or any ORM.
# Instead it uses:
#   1. TypeScript interfaces (types/*.ts) as "entity" definitions
#   2. Raw SQL queries via pg Pool (shared/database module)
#   3. Custom repository pattern (only in investment, portfolio, risk modules)
#   4. Services contain SQL queries directly when no repository exists
#
# "Entity" coverage = TypeScript interface + Row type exists in types/*.ts
# "Repository" coverage = Dedicated *.repository.ts file exists
# "Service" coverage = A *.service.ts file handles operations for this table
# "Controller" coverage = A *.controller.ts file exposes API endpoints
# ==============================================================================

# ==============================================================================
# GLOBAL SUMMARY
# ==============================================================================
summary:
  total_tables: 101
  tables_with_type_interface: 85
  tables_with_row_type: 52
  tables_with_repository: 9
  tables_with_service: 76
  tables_with_controller: 62

  coverage_percentages:
    type_interface: 84.2   # 85/101
    row_type: 51.5         # 52/101
    repository: 8.9        # 9/101
    service: 75.2          # 76/101
    controller: 61.4       # 62/101
    full_stack: 7.9        # 8/101 (type + row + repo + service + controller)

  gap_counts:
    missing_type_interface: 16
    missing_row_type: 49
    missing_repository: 92
    missing_service: 25
    missing_controller: 39

# ==============================================================================
# SCHEMA: auth (12 tables)
# ==============================================================================
auth:
  total_tables: 12
  coverage:
    type_interface: 12   # 100%
    row_type: 10         # 83%
    repository: 0        # 0%
    service: 10          # 83%
    controller: 8        # 67%

  tables:
    - table: auth.users
      ddl_file: "01-users.sql"
      columns: 26
      type_interface: "User (auth.types.ts)"
      row_type: "PARTIAL - UserRow (users.types.ts)"
      repository: MISSING
      service: "email.service.ts, oauth.service.ts, phone.service.ts, users.service.ts"
      controller: "email-auth.controller.ts, oauth.controller.ts, phone-auth.controller.ts, auth.controller.ts, users.controller.ts"
      status: COVERED
      notes: "Core table. Well covered across multiple services. Row type exists but incomplete (missing some fields like backup_codes, suspended_at, suspended_reason)."

    - table: auth.user_profiles
      ddl_file: "02-user_profiles.sql"
      columns: 15
      type_interface: "Profile (auth.types.ts), UserProfile (users.types.ts)"
      row_type: "UserProfileRow (users.types.ts)"
      repository: MISSING
      service: "users.service.ts"
      controller: "users.controller.ts"
      status: COVERED
      notes: "Well mapped. Both camelCase and snake_case row types exist."

    - table: auth.oauth_accounts
      ddl_file: "03-oauth_accounts.sql"
      columns: 12
      type_interface: "OAuthAccount (auth.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "oauth.service.ts"
      controller: "oauth.controller.ts"
      status: PARTIAL
      notes: "Interface exists but no Row type for DB mapping."

    - table: auth.sessions
      ddl_file: "04-sessions.sql"
      columns: 18
      type_interface: "Session (auth.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "session-cache.service.ts, token.service.ts"
      controller: "token.controller.ts, auth.controller.ts"
      status: PARTIAL
      notes: "Partitioned table. Interface exists but no Row type."

    - table: auth.email_verifications
      ddl_file: "05-email_verifications.sql"
      columns: 9
      type_interface: "EmailVerification (auth.types.ts)"
      row_type: "EmailVerificationRow (auth.types.ts)"
      repository: MISSING
      service: "email.service.ts"
      controller: "email-auth.controller.ts"
      status: COVERED
      notes: "Fully mapped with both interface and Row type."

    - table: auth.phone_verifications
      ddl_file: "06-phone_verifications.sql"
      columns: 13
      type_interface: "PhoneVerification (auth.types.ts)"
      row_type: "PhoneVerificationRow (auth.types.ts)"
      repository: MISSING
      service: "phone.service.ts"
      controller: "phone-auth.controller.ts"
      status: COVERED
      notes: "Fully mapped with both interface and Row type."

    - table: auth.password_reset_tokens
      ddl_file: "07-password_reset_tokens.sql"
      columns: 9
      type_interface: "PasswordResetToken (auth.types.ts)"
      row_type: "PasswordResetTokenRow (auth.types.ts)"
      repository: MISSING
      service: "email.service.ts"
      controller: "email-auth.controller.ts"
      status: COVERED
      notes: "Fully mapped with both interface and Row type."

    - table: auth.auth_logs
      ddl_file: "08-auth_logs.sql"
      columns: 10
      type_interface: "AuthLog (auth.types.ts)"
      row_type: "AuthLogRow (auth.types.ts)"
      repository: MISSING
      service: "email.service.ts (indirect logging)"
      controller: NONE
      status: PARTIAL
      notes: "Interface and Row type exist. No dedicated service/controller; logs are written inline."

    - table: auth.login_attempts
      ddl_file: "09-login_attempts.sql"
      columns: 9
      type_interface: "LoginAttempt (auth.types.ts)"
      row_type: "LoginAttemptRow (auth.types.ts)"
      repository: MISSING
      service: "email.service.ts (indirect)"
      controller: NONE
      status: PARTIAL
      notes: "Interface and Row type exist. Used inline, no dedicated service."

    - table: auth.rate_limiting_config
      ddl_file: "10-rate_limiting_config.sql"
      columns: 10
      type_interface: "RateLimitingConfig (auth.types.ts)"
      row_type: "RateLimitingConfigRow (auth.types.ts)"
      repository: MISSING
      service: NONE
      controller: NONE
      status: PARTIAL
      notes: "Types defined but no service/controller. Configuration table used by middleware."

    - table: auth.notifications
      ddl_file: "11-notifications.sql"
      columns: 12
      type_interface: "Notification (auth.types.ts, notifications.types.ts)"
      row_type: "NotificationRow (auth.types.ts, notifications.types.ts)"
      repository: MISSING
      service: "notification.service.ts"
      controller: "notification.controller.ts"
      status: COVERED
      notes: "Dual type definitions in auth and notifications modules."

    - table: auth.user_push_tokens
      ddl_file: "12-user_push_tokens.sql"
      columns: 8
      type_interface: "UserPushToken (auth.types.ts)"
      row_type: "UserPushTokenRow (auth.types.ts), PushTokenRow (notifications.types.ts)"
      repository: MISSING
      service: "notification.service.ts"
      controller: "notification.controller.ts"
      status: COVERED
      notes: "Dual type definitions. Push token management via notification service."

# ==============================================================================
# SCHEMA: trading (13 tables)
# ==============================================================================
trading:
  total_tables: 13
  coverage:
    type_interface: 13   # 100%
    row_type: 0          # 0%
    repository: 0        # 0%
    service: 13          # 100%
    controller: 11       # 85%

  tables:
    - table: trading.symbols
      ddl_file: "01-symbols.sql"
      columns: 14
      type_interface: "Symbol (entity.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "market.service.ts"
      controller: "trading.controller.ts"
      status: COVERED
      notes: "Full entity interface with Create/Update DTOs and Filters."

    - table: trading.watchlists
      ddl_file: "02-watchlists.sql"
      columns: 8
      type_interface: "INLINE (watchlist.service.ts)"
      row_type: MISSING
      repository: MISSING
      service: "watchlist.service.ts"
      controller: "watchlist.controller.ts"
      status: PARTIAL
      notes: "No dedicated type file - types used inline in service."

    - table: trading.watchlist_items
      ddl_file: "03-watchlist_items.sql"
      columns: 7
      type_interface: "INLINE (watchlist.service.ts)"
      row_type: MISSING
      repository: MISSING
      service: "watchlist.service.ts"
      controller: "watchlist.controller.ts"
      status: PARTIAL
      notes: "No dedicated type file - types used inline in service."

    - table: trading.bots
      ddl_file: "04-bots.sql"
      columns: 20
      type_interface: "TradingBot (entity.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "bots.service.ts"
      controller: "bots.controller.ts"
      status: COVERED
      notes: "Full entity interface with Create/Update DTOs and Filters."

    - table: trading.orders
      ddl_file: "05-orders.sql"
      columns: 18
      type_interface: "Order (order.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "order.service.ts"
      controller: "trading.controller.ts"
      status: COVERED
      notes: "Full entity interface with enums aligned to DDL."

    - table: trading.positions
      ddl_file: "06-positions.sql"
      columns: 22
      type_interface: "IMPLICIT (order.types.ts - PositionStatus)"
      row_type: MISSING
      repository: MISSING
      service: "order.service.ts, paper-trading.service.ts"
      controller: "trading.controller.ts, paper-trading.controller.ts"
      status: PARTIAL
      notes: "Only PositionStatus enum exists. No dedicated Position interface."

    - table: trading.trades
      ddl_file: "07-trades.sql"
      columns: 12
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "order.service.ts (indirect)"
      controller: "trading.controller.ts (indirect)"
      status: GAP
      notes: "No TypeScript interface. Table tracks order fills."

    - table: trading.signals
      ddl_file: "08-signals.sql"
      columns: 18
      type_interface: "TradingSignal (entity.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "ml-signal-stream.service.ts, ml-integration.service.ts"
      controller: "ml.controller.ts"
      status: COVERED
      notes: "ML-Trading interface table. Full entity with DTOs."

    - table: trading.trading_metrics
      ddl_file: "09-trading_metrics.sql"
      columns: 19
      type_interface: "TradingMetrics (entity.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "bots.service.ts (indirect)"
      controller: "bots.controller.ts (indirect)"
      status: PARTIAL
      notes: "Interface exists but managed indirectly through bots service."

    - table: trading.paper_balances
      ddl_file: "10-paper_balances.sql"
      columns: 12
      type_interface: "PaperBalance (entity.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "paper-trading.service.ts"
      controller: "paper-trading.controller.ts"
      status: COVERED
      notes: "Full entity interface with Create/Update/Reset DTOs."

    - table: trading.price_alerts
      ddl_file: "11-price_alerts.sql"
      columns: 12
      type_interface: "INLINE (alerts.service.ts)"
      row_type: MISSING
      repository: MISSING
      service: "alerts.service.ts"
      controller: "alerts.controller.ts"
      status: PARTIAL
      notes: "No dedicated type file. Types used inline."

    - table: trading.drawing_tools
      ddl_file: "12-drawing_tools.sql"
      columns: 16
      type_interface: "DrawingTool (drawing.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "drawing.service.ts"
      controller: NONE
      status: PARTIAL
      notes: "Full entity interface but no dedicated controller (drawing endpoints in other controllers or not exposed yet)."

    - table: trading.drawing_templates
      ddl_file: "13-drawing_templates.sql"
      columns: 12
      type_interface: "DrawingTemplate (drawing.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "drawing.service.ts"
      controller: NONE
      status: PARTIAL
      notes: "Full entity interface but no dedicated controller."

# ==============================================================================
# SCHEMA: education (19 tables)
# ==============================================================================
education:
  total_tables: 19
  coverage:
    type_interface: 19   # 100%
    row_type: 7          # 37%
    repository: 0        # 0%
    service: 18          # 95%
    controller: 15       # 79%

  tables:
    - table: education.categories
      ddl_file: "01-categories.sql"
      columns: 9
      type_interface: "Category (education.types.ts)"
      row_type: "CategoryRow (education.types.ts)"
      repository: MISSING
      service: "course.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: education.courses
      ddl_file: "02-courses.sql"
      columns: 19
      type_interface: "Course (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "course.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface with CourseWithDetails. Missing Row type."

    - table: education.modules
      ddl_file: "03-modules.sql"
      columns: 8
      type_interface: "Module (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "course.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface. ModuleWithLessons for nested data."

    - table: education.lessons
      ddl_file: "04-lessons.sql"
      columns: 14
      type_interface: "Lesson (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "course.service.ts, enrollment.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface with LessonWithProgress."

    - table: education.enrollments
      ddl_file: "05-enrollments.sql"
      columns: 12
      type_interface: "Enrollment (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "enrollment.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface with EnrollmentWithCourse."

    - table: education.progress
      ddl_file: "06-progress.sql"
      columns: 11
      type_interface: "LessonProgress (education.types.ts)"
      row_type: "LessonProgressRow (education.types.ts)"
      repository: MISSING
      service: "enrollment.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: education.quizzes
      ddl_file: "07-quizzes.sql"
      columns: 12
      type_interface: "Quiz (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "quiz.service.ts"
      controller: "quiz.controller.ts"
      status: COVERED
      notes: "Full interface with QuizWithQuestions."

    - table: education.quiz_questions
      ddl_file: "08-quiz_questions.sql"
      columns: 10
      type_interface: "QuizQuestion (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "quiz.service.ts"
      controller: "quiz.controller.ts"
      status: COVERED
      notes: "Full interface."

    - table: education.quiz_attempts
      ddl_file: "09-quiz_attempts.sql"
      columns: 12
      type_interface: "QuizAttempt (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "quiz.service.ts"
      controller: "quiz.controller.ts"
      status: COVERED
      notes: "Full interface."

    - table: education.certificates
      ddl_file: "10-certificates.sql"
      columns: 13
      type_interface: "Certificate (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "enrollment.service.ts (indirect)"
      controller: "education.controller.ts"
      status: PARTIAL
      notes: "Interface exists. Generated on course completion."

    - table: education.user_achievements
      ddl_file: "11-user_achievements.sql"
      columns: 10
      type_interface: "UserAchievement (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "gamification.service.ts"
      controller: "gamification.controller.ts"
      status: COVERED
      notes: "Full interface."

    - table: education.user_gamification_profile
      ddl_file: "12-user_gamification_profile.sql"
      columns: 14
      type_interface: "UserGamificationProfile (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "gamification.service.ts"
      controller: "gamification.controller.ts"
      status: COVERED
      notes: "Full interface with Update DTO."

    - table: education.user_activity_log
      ddl_file: "13-user_activity_log.sql"
      columns: 9
      type_interface: "UserActivityLog (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "gamification.service.ts (indirect)"
      controller: NONE
      status: PARTIAL
      notes: "Interface exists. Log written internally, no API exposure."

    - table: education.course_reviews
      ddl_file: "14-course_reviews.sql"
      columns: 10
      type_interface: "CourseReview (reviews.types.ts)"
      row_type: "CourseReviewRow (reviews.types.ts)"
      repository: MISSING
      service: "reviews.service.ts"
      controller: "reviews.controller.ts"
      status: COVERED
      notes: "Full interface + Row type. Dedicated module."

    - table: education.videos
      ddl_file: "15-videos.sql"
      columns: 24
      type_interface: "Video (education.types.ts)"
      row_type: "VideoRow (education.types.ts)"
      repository: MISSING
      service: "video.service.ts"
      controller: "video.controller.ts"
      status: COVERED
      notes: "Full interface + Row type. Complex multipart upload support."

    - table: education.review_helpful_votes
      ddl_file: "16-review_helpful_votes.sql"
      columns: 3
      type_interface: "ReviewHelpfulVote (education.types.ts)"
      row_type: "ReviewHelpfulVoteRow (education.types.ts)"
      repository: MISSING
      service: "reviews.service.ts"
      controller: "reviews.controller.ts"
      status: COVERED
      notes: "Simple junction table. Full types."

    - table: education.instructors
      ddl_file: "17-instructors.sql"
      columns: 14
      type_interface: "Instructor (education.types.ts)"
      row_type: "InstructorRow (education.types.ts)"
      repository: MISSING
      service: "instructor.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: education.course_tags
      ddl_file: "18-course_tags.sql"
      columns: 8
      type_interface: "CourseTag (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "tag.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Full interface."

    - table: education.course_tag_assignments
      ddl_file: "19-course_tag_assignments.sql"
      columns: 4
      type_interface: "CourseTagAssignment (education.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "tag.service.ts"
      controller: "education.controller.ts"
      status: COVERED
      notes: "Junction table interface."

# ==============================================================================
# SCHEMA: financial (11 tables)
# ==============================================================================
financial:
  total_tables: 11
  coverage:
    type_interface: 11   # 100%
    row_type: 9          # 82%
    repository: 0        # 0%
    service: 9           # 82%
    controller: 7        # 64%

  tables:
    - table: financial.wallets
      ddl_file: "01-wallets.sql"
      columns: 18
      type_interface: "Wallet (financial.types.ts)"
      row_type: "WalletRow (financial.types.ts)"
      repository: MISSING
      service: "wallet.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Dual types in payments.types.ts and financial.types.ts."

    - table: financial.wallet_transactions
      ddl_file: "02-wallet_transactions.sql"
      columns: 20
      type_interface: "WalletTransaction (financial.types.ts)"
      row_type: "WalletTransactionRow (financial.types.ts)"
      repository: MISSING
      service: "wallet.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: financial.subscriptions
      ddl_file: "03-subscriptions.sql"
      columns: 22
      type_interface: "Subscription (financial.types.ts, payments.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "subscription.service.ts, stripe.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Dual interface definitions in financial and payments types."

    - table: financial.invoices
      ddl_file: "04-invoices.sql"
      columns: 26
      type_interface: "Invoice (financial.types.ts)"
      row_type: "InvoiceRow (financial.types.ts)"
      repository: MISSING
      service: "stripe.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: financial.payments
      ddl_file: "05-payments.sql"
      columns: 18
      type_interface: "Payment (payments.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "stripe.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Interface in payments.types.ts."

    - table: financial.wallet_audit_log
      ddl_file: "06-wallet_audit_log.sql"
      columns: 12
      type_interface: "WalletAuditLog (financial.types.ts)"
      row_type: "WalletAuditLogRow (financial.types.ts)"
      repository: MISSING
      service: "wallet.service.ts (indirect)"
      controller: NONE
      status: PARTIAL
      notes: "Interface + Row exist. Audit log written internally."

    - table: financial.currency_exchange_rates
      ddl_file: "07-currency_exchange_rates.sql"
      columns: 9
      type_interface: "CurrencyExchangeRate (financial.types.ts)"
      row_type: "CurrencyExchangeRateRow (financial.types.ts)"
      repository: MISSING
      service: "currency.service.ts"
      controller: "currency.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: financial.wallet_limits
      ddl_file: "08-wallet_limits.sql"
      columns: 22
      type_interface: "WalletLimit (financial.types.ts)"
      row_type: "WalletLimitRow (financial.types.ts)"
      repository: MISSING
      service: "wallet.service.ts (indirect)"
      controller: NONE
      status: PARTIAL
      notes: "Full types exist. Used internally by wallet service."

    - table: financial.customers
      ddl_file: "09-customers.sql"
      columns: 18
      type_interface: "Customer (financial.types.ts)"
      row_type: "CustomerRow (financial.types.ts)"
      repository: MISSING
      service: "stripe.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Full interface + Row type. Stripe customer mapping."

    - table: financial.payment_methods
      ddl_file: "10-payment_methods.sql"
      columns: 22
      type_interface: "SavedPaymentMethod (financial.types.ts)"
      row_type: "PaymentMethodRow (financial.types.ts)"
      repository: MISSING
      service: "stripe.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Full interface + Row type. Comprehensive payment method support."

    - table: financial.refunds
      ddl_file: "11-refunds.sql"
      columns: 14
      type_interface: "Refund (financial.types.ts)"
      row_type: "RefundRow (financial.types.ts)"
      repository: MISSING
      service: "refund.service.ts"
      controller: "payments.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

# ==============================================================================
# SCHEMA: investment (10 tables)
# ==============================================================================
investment:
  total_tables: 10
  coverage:
    type_interface: 9    # 90%
    row_type: 0          # 0%
    repository: 5        # 50%
    service: 8           # 80%
    controller: 7        # 70%

  tables:
    - table: investment.products
      ddl_file: "01-products.sql"
      columns: 16
      type_interface: "INLINE (product.repository.ts)"
      row_type: MISSING
      repository: "product.repository.ts"
      service: "product.service.ts"
      controller: "investment.controller.ts"
      status: COVERED
      notes: "Types defined inline in repository/service."

    - table: investment.risk_questionnaire
      ddl_file: "02-risk_questionnaire.sql"
      columns: 10
      type_interface: "RiskQuestionnaire (investment.types.ts)"
      row_type: "RiskQuestionnaireRow (risk.types.ts)"
      repository: MISSING
      service: "risk.service.ts"
      controller: "risk.controller.ts"
      status: COVERED
      notes: "Types split across investment and risk modules."

    - table: investment.accounts
      ddl_file: "03-accounts.sql"
      columns: 17
      type_interface: "InvestmentAccount (investment.types.ts)"
      row_type: MISSING
      repository: "account.repository.ts"
      service: "account.service.ts"
      controller: "investment.controller.ts"
      status: COVERED
      notes: "Full repository + service + controller chain."

    - table: investment.distributions
      ddl_file: "04-distributions.sql"
      columns: 16
      type_interface: "Distribution (investment.types.ts)"
      row_type: MISSING
      repository: "distribution.repository.ts"
      service: "account.service.ts (indirect)"
      controller: "investment.controller.ts"
      status: COVERED
      notes: "Has repository. Managed through account service."

    - table: investment.transactions
      ddl_file: "05-transactions.sql"
      columns: 18
      type_interface: "InvestmentTransaction (investment.types.ts)"
      row_type: MISSING
      repository: "transaction.repository.ts"
      service: "transaction.service.ts"
      controller: "investment.controller.ts"
      status: COVERED
      notes: "Full stack: type + repo + service + controller."

    - table: investment.withdrawal_requests
      ddl_file: "06-withdrawal_requests.sql"
      columns: 19
      type_interface: "WithdrawalRequest (investment.types.ts)"
      row_type: MISSING
      repository: "withdrawal.repository.ts"
      service: "transaction.service.ts"
      controller: "investment.controller.ts"
      status: COVERED
      notes: "Full stack with dedicated repository."

    - table: investment.daily_performance
      ddl_file: "07-daily_performance.sql"
      columns: 20
      type_interface: "DailyPerformance (investment.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "account.service.ts (indirect)"
      controller: "investment.controller.ts"
      status: PARTIAL
      notes: "Interface exists. No dedicated repository."

    - table: investment.distribution_history
      ddl_file: "08-distribution_history.sql"
      columns: 8
      type_interface: "DistributionHistory (investment.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "account.service.ts (indirect)"
      controller: "investment.controller.ts"
      status: PARTIAL
      notes: "Interface exists. No dedicated repository."

    - table: investment.distribution_runs
      ddl_file: "09-distribution_runs.sql"
      columns: 10
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: NONE
      controller: NONE
      status: GAP
      notes: "System/batch table for tracking distribution processing. No backend representation."

    - table: investment.agent_executions
      ddl_file: "10-agent_executions.sql"
      columns: 25
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "agents.service.ts (partial)"
      controller: "agents.controller.ts (partial)"
      status: GAP
      notes: "Complex table. agents module exists but may not fully map to DDL."

# ==============================================================================
# SCHEMA: llm (5 tables)
# ==============================================================================
llm:
  total_tables: 5
  coverage:
    type_interface: 5    # 100%
    row_type: 5          # 100%
    repository: 0        # 0%
    service: 5           # 100%
    controller: 5        # 100%

  tables:
    - table: llm.conversations
      ddl_file: "01-conversations.sql"
      columns: 14
      type_interface: "Conversation (llm.types.ts)"
      row_type: "ConversationRow (llm.types.ts)"
      repository: MISSING
      service: "llm.service.ts"
      controller: "llm.controller.ts"
      status: COVERED
      notes: "Full interface + Row type. Exemplary coverage."

    - table: llm.messages
      ddl_file: "02-messages.sql"
      columns: 16
      type_interface: "Message (llm.types.ts)"
      row_type: "MessageRow (llm.types.ts)"
      repository: MISSING
      service: "llm.service.ts"
      controller: "llm.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: llm.user_preferences
      ddl_file: "03-user_preferences.sql"
      columns: 20
      type_interface: "UserPreferences (llm.types.ts)"
      row_type: "UserPreferencesRow (llm.types.ts)"
      repository: MISSING
      service: "llm.service.ts"
      controller: "llm.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: llm.user_memory
      ddl_file: "04-user_memory.sql"
      columns: 14
      type_interface: "UserMemory (llm.types.ts)"
      row_type: "UserMemoryRow (llm.types.ts)"
      repository: MISSING
      service: "llm.service.ts"
      controller: "llm.controller.ts"
      status: COVERED
      notes: "Full interface + Row type."

    - table: llm.embeddings
      ddl_file: "05-embeddings.sql"
      columns: 18
      type_interface: "Embedding (llm.types.ts)"
      row_type: "EmbeddingRow (llm.types.ts)"
      repository: MISSING
      service: "llm.service.ts"
      controller: "llm.controller.ts"
      status: COVERED
      notes: "Full interface + Row type. Uses pgvector."

# ==============================================================================
# SCHEMA: ml (12 tables)
# ==============================================================================
ml:
  total_tables: 12
  coverage:
    type_interface: 7    # 58%
    row_type: 0          # 0%
    repository: 0        # 0%
    service: 9           # 75%
    controller: 7        # 58%

  tables:
    - table: ml.models
      ddl_file: "01-models.sql"
      columns: 16
      type_interface: "MLModel (ml.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "ml-model-registry.service.ts"
      controller: "ml.controller.ts"
      status: COVERED
      notes: "Full interface with CreateModelDTO."

    - table: ml.model_versions
      ddl_file: "02-model_versions.sql"
      columns: 20
      type_interface: "MLModelVersion (ml.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "ml-model-registry.service.ts"
      controller: "ml.controller.ts"
      status: COVERED
      notes: "Full interface with CreateModelVersionDTO."

    - table: ml.predictions
      ddl_file: "03-predictions.sql"
      columns: 15
      type_interface: "MLPredictionRecord (ml.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "ml-data.service.ts"
      controller: "ml.controller.ts"
      status: COVERED
      notes: "Full interface with CreatePredictionDTO."

    - table: ml.prediction_outcomes
      ddl_file: "04-prediction_outcomes.sql"
      columns: 11
      type_interface: "MLPredictionOutcome (ml.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "ml-data.service.ts"
      controller: "ml.controller.ts"
      status: COVERED
      notes: "Full interface."

    - table: ml.feature_store
      ddl_file: "05-feature_store.sql"
      columns: 11
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "ml-data.service.ts (indirect)"
      controller: NONE
      status: GAP
      notes: "No TypeScript interface. Used by Python ML engine, not Express backend."

    - table: ml.llm_predictions
      ddl_file: "06-llm_predictions.sql"
      columns: 13
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: NONE
      controller: NONE
      status: GAP
      notes: "No backend representation. May be managed by Python LLM service."

    - table: ml.llm_prediction_outcomes
      ddl_file: "07-llm_prediction_outcomes.sql"
      columns: 11
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: NONE
      controller: NONE
      status: GAP
      notes: "No backend representation. Outcome tracking for LLM predictions."

    - table: ml.llm_decisions
      ddl_file: "08-llm_decisions.sql"
      columns: 10
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: NONE
      controller: NONE
      status: GAP
      notes: "No backend representation. Decision log for LLM."

    - table: ml.risk_events
      ddl_file: "09-risk_events.sql"
      columns: 8
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "risk.service.ts (partial)"
      controller: "risk.controller.ts (partial)"
      status: GAP
      notes: "No TypeScript interface. Risk module exists but may not fully cover this table."

    - table: ml.backtest_runs
      ddl_file: "10-backtest_runs.sql"
      columns: 10
      type_interface: "BacktestResult (ml.types.ts - partial)"
      row_type: MISSING
      repository: MISSING
      service: "ml-backtest.service.ts"
      controller: "ml.controller.ts"
      status: PARTIAL
      notes: "BacktestResult interface exists but not fully aligned with DDL table columns."

    - table: ml.llm_signals
      ddl_file: "11-llm_signals.sql"
      columns: 9
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "ml-signal-stream.service.ts (partial)"
      controller: "ml.controller.ts (partial)"
      status: GAP
      notes: "SERIAL PK (not UUID). No dedicated TypeScript interface."

    - table: ml.prediction_overlays
      ddl_file: "12-prediction_overlays.sql"
      columns: 15
      type_interface: "PredictionOverlay (ml.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "prediction-overlay.service.ts, ml-overlay.service.ts"
      controller: "ml-overlay.controller.ts"
      status: COVERED
      notes: "Full interface with Create/Update DTOs."

# ==============================================================================
# SCHEMA: market_data (4 tables)
# ==============================================================================
market_data:
  total_tables: 4
  coverage:
    type_interface: 4    # 100%
    row_type: 4          # 100%
    repository: 0        # 0%
    service: 4           # 100%
    controller: 4        # 100%

  tables:
    - table: market_data.tickers
      ddl_file: "01-tickers.sql"
      columns: 10
      type_interface: "TickerInfo (market-data.types.ts)"
      row_type: "TickerRow (market-data.types.ts)"
      repository: MISSING
      service: "marketData.service.ts"
      controller: "market-data.controller.ts"
      status: COVERED
      notes: "SERIAL PK. Full types."

    - table: market_data.ohlcv_5m
      ddl_file: "02-ohlcv_5m.sql"
      columns: 9
      type_interface: "OHLCV (market-data.types.ts)"
      row_type: "Ohlcv5mRow (market-data.types.ts)"
      repository: MISSING
      service: "marketData.service.ts"
      controller: "market-data.controller.ts"
      status: COVERED
      notes: "BIGSERIAL PK. Full types."

    - table: market_data.ohlcv_15m
      ddl_file: "03-ohlcv_15m.sql"
      columns: 9
      type_interface: "OHLCV (market-data.types.ts)"
      row_type: "Ohlcv15mRow (market-data.types.ts)"
      repository: MISSING
      service: "marketData.service.ts"
      controller: "market-data.controller.ts"
      status: COVERED
      notes: "BIGSERIAL PK. Shares OHLCV interface."

    - table: market_data.ohlcv_5m_staging
      ddl_file: "04-staging.sql"
      columns: 8
      type_interface: "OhlcvStagingRow (market-data.types.ts)"
      row_type: "OhlcvStagingRow (market-data.types.ts)"
      repository: MISSING
      service: "marketData.service.ts (bulk import)"
      controller: "market-data.controller.ts"
      status: COVERED
      notes: "Staging table for bulk data imports."

# ==============================================================================
# SCHEMA: audit (7 tables)
# ==============================================================================
audit:
  total_tables: 7
  coverage:
    type_interface: 7    # 100%
    row_type: 0          # 0%
    repository: 0        # 0%
    service: 7           # 100%
    controller: 7        # 100%

  tables:
    - table: audit.audit_logs
      ddl_file: "01-audit_logs.sql"
      columns: 14
      type_interface: "AuditLog (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

    - table: audit.security_events
      ddl_file: "02-security_events.sql"
      columns: 17
      type_interface: "SecurityEvent (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

    - table: audit.system_events
      ddl_file: "03-system_events.sql"
      columns: 13
      type_interface: "SystemEvent (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

    - table: audit.trading_audit
      ddl_file: "04-trading_audit.sql"
      columns: 17
      type_interface: "TradingAudit (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

    - table: audit.api_request_logs
      ddl_file: "05-api_request_logs.sql"
      columns: 13
      type_interface: "ApiRequestLog (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

    - table: audit.data_access_logs
      ddl_file: "06-data_access_logs.sql"
      columns: 13
      type_interface: "DataAccessLog (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

    - table: audit.compliance_logs
      ddl_file: "07-compliance_logs.sql"
      columns: 13
      type_interface: "ComplianceLog (audit.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "audit.service.ts"
      controller: "audit.controller.ts"
      status: COVERED
      notes: "Full interface with Create DTO and Filters."

# ==============================================================================
# SCHEMA: portfolio (5 tables)
# ==============================================================================
portfolio:
  total_tables: 5
  coverage:
    type_interface: 5    # 100%
    row_type: 0          # 0%
    repository: 3        # 60%
    service: 5           # 100%
    controller: 5        # 100%

  tables:
    - table: portfolio.portfolios
      ddl_file: "01-portfolios.sql"
      columns: 14
      type_interface: "Portfolio (portfolio.types.ts)"
      row_type: MISSING
      repository: "portfolio.repository.ts"
      service: "portfolio.service.ts"
      controller: "portfolio.controller.ts"
      status: COVERED
      notes: "Full stack: type + repo + service + controller."

    - table: portfolio.portfolio_allocations
      ddl_file: "02-portfolio_allocations.sql"
      columns: 13
      type_interface: "PortfolioAllocation (portfolio.types.ts)"
      row_type: MISSING
      repository: "portfolio.repository.ts (shared)"
      service: "portfolio.service.ts"
      controller: "portfolio.controller.ts"
      status: COVERED
      notes: "Managed within portfolio repository."

    - table: portfolio.portfolio_goals
      ddl_file: "03-portfolio_goals.sql"
      columns: 13
      type_interface: "PortfolioGoal (portfolio.types.ts)"
      row_type: MISSING
      repository: "goal.repository.ts"
      service: "portfolio.service.ts"
      controller: "portfolio.controller.ts"
      status: COVERED
      notes: "Dedicated goal repository."

    - table: portfolio.rebalance_history
      ddl_file: "04-rebalance_history.sql"
      columns: 11
      type_interface: "RebalanceHistory (portfolio.types.ts)"
      row_type: MISSING
      repository: MISSING
      service: "portfolio.service.ts"
      controller: "portfolio.controller.ts"
      status: COVERED
      notes: "Interface exists. Managed in portfolio service directly."

    - table: portfolio.portfolio_snapshots
      ddl_file: "05-portfolio_snapshots.sql"
      columns: 9
      type_interface: "PortfolioSnapshot (portfolio.types.ts)"
      row_type: MISSING
      repository: "snapshot.repository.ts"
      service: "portfolio.service.ts"
      controller: "portfolio.controller.ts"
      status: COVERED
      notes: "Dedicated snapshot repository."

# ==============================================================================
# SCHEMA: feature_flags (3 tables)
# ==============================================================================
feature_flags:
  total_tables: 3
  coverage:
    type_interface: 0    # 0%
    row_type: 0          # 0%
    repository: 0        # 0%
    service: 3           # 100%
    controller: 3        # 100%

  tables:
    - table: feature_flags.flags
      ddl_file: "01-flags.sql"
      columns: 14
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "feature-flags.service.ts"
      controller: "feature-flags.controller.ts"
      status: PARTIAL
      notes: "Service and controller exist but no dedicated type file. Types likely inline."

    - table: feature_flags.user_flags
      ddl_file: "01-flags.sql (same file)"
      columns: 7
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "feature-flags.service.ts"
      controller: "feature-flags.controller.ts"
      status: PARTIAL
      notes: "User-specific flag overrides. No dedicated types."

    - table: feature_flags.evaluations
      ddl_file: "01-flags.sql (same file)"
      columns: 6
      type_interface: MISSING
      row_type: MISSING
      repository: MISSING
      service: "feature-flags.service.ts"
      controller: "feature-flags.controller.ts"
      status: PARTIAL
      notes: "Flag evaluation history. No dedicated types."

# ==============================================================================
# COHERENCE MATRIX (Per-Schema Summary)
# ==============================================================================
coherence_matrix:
  - schema: auth
    tables: 12
    type_coverage: "100%"
    row_coverage: "83%"
    repo_coverage: "0%"
    service_coverage: "83%"
    controller_coverage: "67%"
    overall_health: GOOD

  - schema: trading
    tables: 13
    type_coverage: "100%"
    row_coverage: "0%"
    repo_coverage: "0%"
    service_coverage: "100%"
    controller_coverage: "85%"
    overall_health: MODERATE
    notes: "Zero row types is a significant gap"

  - schema: education
    tables: 19
    type_coverage: "100%"
    row_coverage: "37%"
    repo_coverage: "0%"
    service_coverage: "95%"
    controller_coverage: "79%"
    overall_health: GOOD

  - schema: financial
    tables: 11
    type_coverage: "100%"
    row_coverage: "82%"
    repo_coverage: "0%"
    service_coverage: "82%"
    controller_coverage: "64%"
    overall_health: GOOD

  - schema: investment
    tables: 10
    type_coverage: "90%"
    row_coverage: "0%"
    repo_coverage: "50%"
    service_coverage: "80%"
    controller_coverage: "70%"
    overall_health: MODERATE
    notes: "Best repository coverage of all schemas"

  - schema: llm
    tables: 5
    type_coverage: "100%"
    row_coverage: "100%"
    repo_coverage: "0%"
    service_coverage: "100%"
    controller_coverage: "100%"
    overall_health: EXCELLENT
    notes: "Model schema for DDL-Backend alignment"

  - schema: ml
    tables: 12
    type_coverage: "58%"
    row_coverage: "0%"
    repo_coverage: "0%"
    service_coverage: "75%"
    controller_coverage: "58%"
    overall_health: WEAK
    notes: "Many tables managed by Python ML engine, not Express backend"

  - schema: market_data
    tables: 4
    type_coverage: "100%"
    row_coverage: "100%"
    repo_coverage: "0%"
    service_coverage: "100%"
    controller_coverage: "100%"
    overall_health: EXCELLENT

  - schema: audit
    tables: 7
    type_coverage: "100%"
    row_coverage: "0%"
    repo_coverage: "0%"
    service_coverage: "100%"
    controller_coverage: "100%"
    overall_health: GOOD
    notes: "All types exist but no Row types for DB mapping"

  - schema: portfolio
    tables: 5
    type_coverage: "100%"
    row_coverage: "0%"
    repo_coverage: "60%"
    service_coverage: "100%"
    controller_coverage: "100%"
    overall_health: GOOD
    notes: "Second best repository coverage"

  - schema: feature_flags
    tables: 3
    type_coverage: "0%"
    row_coverage: "0%"
    repo_coverage: "0%"
    service_coverage: "100%"
    controller_coverage: "100%"
    overall_health: WEAK
    notes: "Service/controller exist but NO type definitions at all"

# ==============================================================================
# CRITICAL GAPS (Tables with STATUS: GAP)
# ==============================================================================
critical_gaps:
  - table: trading.trades
    schema: trading
    reason: "No TypeScript interface at all. Tracks order fills."
    impact: HIGH
    recommendation: "Create Trade interface in order.types.ts"

  - table: investment.distribution_runs
    schema: investment
    reason: "No backend representation. System/batch processing table."
    impact: MEDIUM
    recommendation: "Create DistributionRun interface. May be needed for admin dashboard."

  - table: investment.agent_executions
    schema: investment
    reason: "Complex table (25 columns) with no dedicated TypeScript mapping."
    impact: HIGH
    recommendation: "Create AgentExecution interface in investment.types.ts"

  - table: ml.feature_store
    schema: ml
    reason: "Python ML engine manages this, not Express backend."
    impact: LOW
    recommendation: "Create read-only interface for admin/monitoring endpoints."

  - table: ml.llm_predictions
    schema: ml
    reason: "Managed by Python LLM service. No Express backend access."
    impact: LOW
    recommendation: "Create read-only interface for dashboard/monitoring."

  - table: ml.llm_prediction_outcomes
    schema: ml
    reason: "Outcome tracking for LLM predictions. Python-managed."
    impact: LOW
    recommendation: "Create read-only interface."

  - table: ml.llm_decisions
    schema: ml
    reason: "LLM decision log. Python-managed."
    impact: LOW
    recommendation: "Create read-only interface."

  - table: ml.risk_events
    schema: ml
    reason: "No TypeScript interface. Risk module may not cover this."
    impact: MEDIUM
    recommendation: "Create RiskEvent interface in ml.types.ts or risk.types.ts."

  - table: ml.llm_signals
    schema: ml
    reason: "SERIAL PK, no UUID. No dedicated TypeScript interface."
    impact: MEDIUM
    recommendation: "Create LLMSignal interface in ml.types.ts."

# ==============================================================================
# ROW TYPE GAP ANALYSIS
# ==============================================================================
# Row types (snake_case DB mapping interfaces) are critical for type-safe
# database operations. Only 52 of 101 tables have Row types.
# ==============================================================================
row_type_gaps:
  schemas_with_zero_row_types:
    - trading    # 13 tables, 0 row types
    - investment # 10 tables, 0 row types
    - audit      # 7 tables, 0 row types
    - portfolio  # 5 tables, 0 row types
    - feature_flags # 3 tables, 0 row types

  schemas_with_partial_row_types:
    - auth       # 12 tables, 10 row types (missing: oauth_accounts, sessions)
    - education  # 19 tables, 7 row types (missing: courses, modules, lessons, enrollments, quizzes, quiz_questions, quiz_attempts, certificates, user_achievements, user_gamification_profile, user_activity_log, course_tags)
    - financial  # 11 tables, 9 row types (missing: subscriptions, payments)

  schemas_with_full_row_types:
    - llm         # 5/5
    - market_data # 4/4
    - ml          # 0/12 (all missing, but 7 have entity interfaces)