feat(core): add pro-league schema for professional lacrosse data

[jackwatters45]

Summary

• Add 8 database tables for professional lacrosse league data (PLL, NLL, MLL, MSL, WLA)
• Add transform layer to convert extracted API data into normalized schema
• Add LoadService to orchestrate file→transform→bulk upsert workflow

Schema tables

• pro_league: League reference (pll, nll, mll, msl, wla)
• pro_season: Season per league with external IDs
• pro_team: Teams with logos, colors, external IDs
• pro_player: Players with demographics, cross-league matching via canonical_player_id
• pro_player_season: Roster + stats (JSONB) per season
• pro_game: Games with scores, venue, status
• pro_standings: Team standings with daily snapshots for time-series
• pro_data_ingestion: Extraction provenance tracking

Transform layer

• NLL transforms: teams, players, player-seasons, games, standings
• PLL transforms: teams, players, player-seasons, events→games, standings
• Stats stored as Record<string, unknown> for JSONB flexibility

Test plan

• bun run typecheck passes
• bun run db:generate creates migration
• bun run deploy applies migration to PlanetScale
• Load NLL season via loadNLLSeason("225", "output/nll/225")
• Verify data in Drizzle Studio

🤖 Generated with Claude Code

[github-actions]

Code Review

Summary

This PR adds comprehensive database schema and service layers for professional lacrosse league data (PLL, NLL, MLL, MSL, WLA). It includes 8 database tables, repository patterns, service layer with Effect-TS, and transform functions to normalize data from external APIs. The implementation follows the project architecture well with proper separation of concerns.

Title Convention

✅ Title follows conventional commit format: feat(core): add pro-league schema for professional lacrosse data

Feedback

Architecture & Patterns (Strong)

• ✅ Excellent adherence to Effect-TS patterns throughout
• ✅ Proper separation: schema → SQL → repo → service → contract layers
• ✅ Good use of Effect Schema classes for type safety
• ✅ Comprehensive database indexes for common query patterns
• ✅ Proper foreign key cascades (onDelete: "cascade" for owned relationships, "set null" for optional)

Critical Issues

1. Performance: Sequential bulk operations (packages/core/src/pro-league/pro-league.repo.ts:243-287)

   • Bulk upsert methods process records sequentially in a loop instead of batch operations
   • Affects: bulkUpsertTeams, bulkUpsertPlayers, bulkUpsertPlayerSeasons, bulkUpsertGames, bulkUpsertStandings
   • Impact: N database round-trips for large datasets
   • Suggestion: Use Drizzle's .values([...]) for true batch inserts, or document why sequential is required

2. Bug: Wrong sort order (packages/core/src/pro-league/pro-league.repo.ts:817)

   getRecentIngestions: (leagueId: number, limit = 10) =>
     .orderBy(proDataIngestionTable.createdAt) // Missing desc()

   • Should be .orderBy(desc(proDataIngestionTable.createdAt)) to return recent items first

3. Type safety: Interface duplication (packages/pipeline/src/load/load.service.ts:118-146)

   • ProLeagueServiceInterface manually duplicates types from @laxdb/core
   • Risk of type drift when core schemas change
   • Suggestion: Import actual service types from @laxdb/core

Medium Priority Issues

4. Missing error handling (packages/core/src/pro-league/pro-league.service.ts:207,258)

   • Methods like getTeamByExternalId, getPlayerByExternalId pass through repo without error handling
   • Other methods (e.g., getLeagueByCode) properly catch and transform NoSuchElementException
   • Suggestion: Add consistent error handling with Effect.catchTag

5. Type assertions bypass type safety (violates CLAUDE.md anti-pattern: "no as Type")

   • packages/core/src/pro-league/pro-league.repo.ts:115: as Omit<ProLeague, "id">[]
   • packages/pipeline/src/load/nll.transform.ts:199-205: as unknown as Record<string, unknown>
   • While sometimes necessary for Drizzle patterns, document why type assertion is needed

6. Schema.Unknown defeats type safety

   • packages/core/src/pro-league/pro-league.schema.ts:186-188: Stats stored as Record<string, unknown>
   • packages/core/src/pro-league/pro-league.error.ts:59: Error cause uses Schema.Unknown
   • Note: May be intentional for JSONB flexibility, but worth acknowledging

7. Inconsistent ordering logic (packages/core/src/pro-league/pro-league.repo.ts:759)

   • getStandings orders by snapshotDate when no date provided, but should probably order by position
   • Suggestion: .orderBy(desc(proStandingsTable.snapshotDate), proStandingsTable.position)

Minor Issues

8. Magic number year derivation (packages/pipeline/src/load/load.service.ts:181)

   const baseYear = 2000 + Math.floor(Number(seasonId) / 10);

   • Derives year from NLL season ID (225 → 2024)
   • Fragile if NLL changes ID scheme
   • Suggestion: Add comment explaining formula or use lookup table

9. Inefficient array operations (packages/pipeline/src/load/pll.transform.ts:94-96)

   • Maps array twice: Math.max(...player.allTeams.map()) then .find()
   • Suggestion: Use reduce for O(n) instead of O(2n)

10. Date parsing fallback (packages/pipeline/src/load/pll.transform.ts:373-376)

    • Returns new Date() (current time) for invalid dates
    • May mask data quality issues
    • Suggestion: Consider returning null or throwing error

Suggestions

High Priority:

• Fix sequential bulk operations for performance
• Add missing error handling in service layer methods
• Fix getRecentIngestions sort order

Medium Priority:

• Remove type assertions where possible or document why needed
• Import types from core instead of duplicating interfaces
• Add consistent ordering to standings query

Low Priority:

• Document magic numbers (year derivation)
• Optimize array operations (map+find → reduce)
• Consider returning null for invalid dates instead of masking with current date

Test Coverage:

• Test plan shows bun run typecheck checked, but migration, deployment, and load verification are unchecked
• Ensure remaining test plan items are completed before merge

Security & Performance Notes:

• ✅ No SQL injection risks (parameterized queries via Drizzle)
• ✅ Excellent index coverage for common queries
• ✅ Input validation through Effect Schema
• ⚠️ Consider adding GIN indexes on JSONB columns if planning to query stats fields frequently

Overall

Strong implementation with excellent architecture and proper use of Effect-TS patterns. The database schema design is well thought out with appropriate indexes and constraints. Main concerns are bulk operation performance, a few missing error handlers, and type safety bypasses via assertions. These issues should be addressed before merge, especially the critical performance and bug fixes.

Grade: B+ - Solid work that follows project patterns, but needs fixes for production readiness.

---

Auto-generated review by Claude