NBA Fantasy App

A TypeScript-based NBA fantasy application where users can pick NBA players daily with a 30-day cooldown period. Built with a Domain-Driven Design architecture, AWS serverless deployment using CDK, and CI/CD with GitHub Actions.

Project Overview

This application allows users to:

• Create an account and log in
• Pick NBA players daily for their fantasy team
• Track player performance and scores
• View NBA game schedules and results
• Compete with other users based on player performance

The application includes an admin panel where administrators can:

• Trigger NBA game syncs for the 2024/2025 season
• Edit team rosters and scheduled games
• Relaunch NBA API synchronization

Architecture

Tech Stack

• Frontend: React 19, TypeScript, Material UI, Vite
• Backend: Node.js, TypeScript, AWS Lambda
• Database: Amazon DynamoDB
• Infrastructure: AWS CDK (Cloud Development Kit)
• CI/CD: GitHub Actions

Project Structure

The project is organized into three main folders:

/
├── backend/           # Backend services and API
│   ├── src/
│   │   ├── domain/            # Domain models and business logic
│   │   ├── application/       # Application services
│   │   ├── infrastructure/    # External services and repositories
│   │   └── interfaces/        # API endpoints and controllers
│   ├── tests/                 # Unit and integration tests
│   └── package.json
│
├── frontend/          # React frontend application
│   ├── src/
│   │   ├── components/        # Reusable UI components
│   │   ├── pages/             # Application pages
│   │   ├── services/          # API client services
│   │   └── context/           # React context providers
│   └── package.json
│
├── infrastructure/    # AWS CDK infrastructure code
│   ├── src/
│   │   ├── stacks/            # CDK stack definitions
│   │   └── constructs/        # Custom CDK constructs
│   └── package.json
│
└── .github/workflows/ # GitHub Actions CI/CD pipelines

Domain-Driven Design

The backend follows a strict Domain-Driven Design approach:

• Domain Layer: Contains the core business logic and entities (Player, Team, Game, etc.)
• Application Layer: Orchestrates the domain objects to perform specific use cases
• Infrastructure Layer: Implements technical capabilities like database access
• Interface Layer: Handles external communication (API endpoints, event handlers)

Serverless Architecture

The application uses AWS serverless services to ensure scalability and cost-efficiency:

• AWS Lambda: For executing backend code
• API Gateway: For handling HTTP requests
• DynamoDB: For data persistence
• S3 & CloudFront: For hosting the frontend
• EventBridge: For scheduling and event-driven processes

Getting Started

Prerequisites

• Node.js (v20 or later)
• AWS CLI configured with appropriate credentials
• AWS CDK installed globally (npm install -g aws-cdk)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd ttfl-fantasy
   

2. Install dependencies for all packages:

   # Backend
   cd backend
   npm install
   
   # Frontend
   cd ../frontend
   npm install
   
   # Infrastructure
   cd ../infrastructure
   npm install
   

Local Development

Backend

cd backend
npm run dev

Frontend

cd frontend
npm run dev

Testing

Running Backend Tests

cd backend
npm test
# For coverage report
npm run test:coverage

Running Frontend Tests

cd frontend
npm test

Building

Backend

cd backend
npm run build

Frontend

cd frontend
npm run build

Infrastructure

cd infrastructure
npm run build

Deployment

Manual Deployment

1. Deploy the infrastructure:

   cd infrastructure
   npm run deploy

2. Deploy the frontend:

   cd frontend
   npm run build
   # The CI/CD pipeline will handle the deployment to S3

CI/CD Pipeline

The project includes a GitHub Actions CI/CD pipeline that automatically:

1. Runs tests for both backend and frontend
2. Deploys infrastructure changes using CDK
3. Builds and deploys the frontend to S3
4. Invalidates the CloudFront cache

The pipeline is triggered on:

• Push to the main branch
• Pull requests to the main branch (only runs tests)

Key Features

User Features

• Daily player selection with 30-day cooldown period
• Real-time game and player statistics
• Leaderboards and user rankings
• Player performance history and analytics

Admin Features

• NBA data synchronization management
• Team and player roster management
• Game schedule management
• User management and analytics

License

ISC License