NFL Fantasy Football Draft Assistant
Expert development assistant for NFLDrafter, a local-first fantasy football scoring application. This skill provides specialized guidance for building and maintaining a full-stack fantasy football draft tool with custom scoring profiles, player analysis, and news integration.
Project Context
NFLDrafter is a fantasy football open scorer with:
React + Vite + TypeScript frontend with TanStack QueryFastAPI + Pydantic v2 backend with async SQLAlchemy 2.xSQLite database (WAL mode) with FTS5 for news searchETL pipeline using Typer CLI, APScheduler, pandas, and nfl_data_pyYahoo OAuth authentication with AuthlibInstructions
When assisting with NFLDrafter development, follow these guidelines:
1. Code Standards
**Python Backend:**
Use Python 3.9+ features with complete type hintsImplement async/await patterns following FastAPI best practicesUse SQLAlchemy 2.x async syntax with proper session managementApply Pydantic models for validation and error handlingUtilize dependency injection for database sessions and servicesFollow PEP 8 with 88-character line limit (black formatter)Run ruff for linting and mypy for type checking**TypeScript/React Frontend:**
Enable TypeScript strict modeImplement error boundaries and loading statesUse TanStack Query for server state managementFollow React hooks best practicesApply Tailwind CSS utility classes consistentlyDesign responsive layoutsDefine proper TypeScript interfaces for API responses**Database:**
Use SQLite with WAL mode enabledIndex frequently queried columnsImplement FTS5 for full-text search on newsFollow SQLAlchemy async best practicesDefine foreign key constraints and relationships2. Architecture Patterns
**API Design:**
Create RESTful endpoints with consistent namingReturn proper HTTP status codes and error responsesValidate requests/responses with Pydantic modelsImplement rate limiting for external API callsApply authentication middleware for protected routes**Data Models:**
`Players`: Core player info with cross-platform IDs`PlayerWeekStats`: Normalized weekly statistics (long format)`ScoringProfiles`: Custom scoring rule sets`ScoringRules`: Individual rules with multipliers, bonuses, caps`NewsItems`: RSS feed content with player associations**Scoring Engine:**
Support flexible scoring with multipliers, bonuses, and capsImplement per-unit scoring (e.g., 0.1 points per yard)Handle bonus thresholds and maximum point capsEnsure deterministic and testable calculationsTarget <50ms per profile calculation time**ETL Processes:**
Use nfl_data_py for player data and weekly statisticsImplement idempotent data ingestion with upsert patternsValidate and clean data during ingestionSupport historical data loading for multiple seasons3. Security Guidelines
Store OAuth secrets in environment variablesValidate and sanitize all inputsUse parameterized queries (prevent SQL injection)Configure proper CORS policies for local developmentNever commit secrets or credentials to version control4. Testing Requirements
Write unit tests for scoring engine with known snapshotsCreate integration tests for API endpointsImplement performance tests (scoring <50ms per profile)Add data validation tests for ETL processesTest error handling and edge cases5. Performance Optimization
Complete scoring calculations in <50ms per profileUse proper database indexingImplement virtualization for large frontend data setsLeverage FTS5 for fast news text queriesProfile and optimize slow queries6. Development Workflow
When implementing features, follow this order:
1. Set up local SQLite database environment
2. Seed player data and historical statistics
3. Implement scoring profiles and rules
4. Build player explorer and news integration
5. Add Yahoo OAuth for league integration
6. Implement advanced features (tiering, watchlists, ADP)
7. Code Quality
Run ruff for Python linting and formattingApply black for consistent Python code styleExecute mypy for type checkingImplement comprehensive error handling and loggingWrite clear docstrings and commentsFollow consistent naming conventions across codebase8. File Organization
Follow this project structure:
```
fantasy-open-scorer/
├─ frontend/ # Vite React app
├─ api/
│ ├─ app/
│ │ ├─ main.py # FastAPI entry
│ │ ├─ deps.py # DI dependencies
│ │ ├─ db.py # Database connection
│ │ ├─ models.py # SQLAlchemy models
│ │ ├─ schemas.py # Pydantic schemas
│ │ ├─ scoring.py # Scoring engine
│ │ ├─ routers/ # API routes
│ │ └─ services/ # Business logic
│ ├─ cli.py # Typer CLI
│ └─ alembic/ # Migrations
```
9. Future-Proofing
Design with these considerations:
Easy migration path from SQLite to PostgresExport/import functionality for scoring profilesSupport for projections and what-if scenariosReal-time game data integration capabilityMulti-user support scalabilityExamples
**Creating a scoring rule:**
```python
Use Pydantic v2 with proper validation
class ScoringRuleCreate(BaseModel):
stat_key: str
multiplier: float = 1.0
bonus_threshold: float | None = None
bonus_points: float | None = None
max_points: float | None = None
```
**Async database query:**
```python
Use SQLAlchemy 2.x async patterns
async def get_player_stats(
session: AsyncSession,
player_id: str,
season: int
) -> list[PlayerWeekStats]:
result = await session.execute(
select(PlayerWeekStats)
.where(PlayerWeekStats.player_id == player_id)
.where(PlayerWeekStats.season == season)
)
return result.scalars().all()
```
**Frontend API call with TanStack Query:**
```typescript
// Use proper TypeScript interfaces
interface PlayerStats {
playerId: string;
season: number;
stats: Record<string, number>;
}
const { data, isLoading } = useQuery({
queryKey: ['playerStats', playerId, season],
queryFn: () => fetchPlayerStats(playerId, season)
});
```
Constraints
Maintain compatibility with Python 3.9+Keep scoring calculations under 50ms per profileDesign database schema for SQLite-to-Postgres migrationFollow OAuth best practices for Yahoo integrationEnsure all external API calls are rate-limitedImplement proper error handling at all layersWrite tests for all scoring engine logic