SECFB API

A REST API for SEC college football data, built with NestJS and TypeScript.

Overview

The SECFB API provides a backend service for managing college football data including teams, games, seasons, and stadiums. This API supports applications that need SEC football information with full CRUD operations.

Replaces the outdated sec-web-backend repository.

Endpoints

# ===== GAMES =====
POST     /games
GET      /games
GET      /games/:identifier
PATCH    /games/:identifier
DELETE   /games/:identifier

PATCH    /games/:identifier/score
PATCH    /games/:identifier/finalize

# ===== SEASONS =====
POST     /seasons
GET      /seasons
GET      /seasons/:identifier
PATCH    /seasons/:identifier
DELETE   /seasons/:identifier

PATCH   /seasons/:identifier/current

# ===== STADIUMS =====
POST     /stadiums
GET      /stadiums
GET      /stadiums/:identifier
PATCH    /stadiums/:identifier
DELETE   /stadiums/:identifier

# ===== TEAMS =====
POST     /teams
GET      /teams
GET      /teams/:identifier
PATCH    /teams/:identifier
DELETE   /teams/:identifier

PATCH    /teams/:identifier/logo
DELETE   /teams/:identifier/logo

POST     /teams/:identifier/performance/:seasonIdentifier
GET      /teams/:identifier/performance/:seasonIdentifier
PATCH    /teams/:identifier/performance/:seasonIdentifier
DELETE   /teams/:identifier/performance/:seasonIdentifier

Features

Core Functionality

• Admin Authentication: JWT-based authentication with refresh token support
• Games Management: Game scheduling, results, and participant tracking
• Seasons Management: Multi-year season tracking with current season indicators
• Stadiums Management: Stadium information including capacity, location, and team associations
• Teams Management: Team profiles with logos, conference info, and season stats

Technical Features

• Rate Limiting: Built-in request throttling
• API Documentation: Auto-generated Swagger/OpenAPI docs
• Data Validation: Input validation with class-validator
• Database Management: Prisma ORM with PostgreSQL
• CORS Support: Cross-origin resource sharing
• Structured Responses: Consistent API response format
• Security: Bcrypt password hashing, signed cookies, JWT tokens

Tech Stack

• Framework: NestJS
• Language: TypeScript
• Database: PostgreSQL
• ORM: Prisma
• Authentication: Passport.js with JWT
• Documentation: Swagger/OpenAPI
• Validation: class-validator
• Code Quality: ESLint, Prettier, Husky, Commitlint

Prerequisites

• Node.js (v18 or higher)
• npm
• Docker and Docker Compose
• Git

Installation & Setup

1. Clone the Repository

git clone https://github.com/your-username/secfb-api.git
cd secfb-api

2. Install Dependencies

npm install

3. Start Database Services

Start the PostgreSQL database using Docker Compose:

docker compose up -d

4. Environment Configuration

Create a .env file in the root directory:

cp .env.example .env

Configure the following environment variables:

DATABASE_URL="postgresql://postgres:postgres@localhost:5432/secfb_db"

NODE_ENV="development"
PORT="3000"
ADDRESS="0.0.0.0"

CORS_ORIGIN_REGEXP="^http://localhost:\d+$"

COOKIE_SECRET="secret"
COOKIE_NAME="SECFB_REFRESH_TOKEN"
COOKIE_PATH="/"
COOKIE_DOMAIN="localhost"
COOKIE_LIFETIME="604800"

JWT_SECRET="secret"
JWT_EXPIRES_IN="15m"
JWT_REFRESH_SECRET="secret"
JWT_REFRESH_EXPIRES_IN="7d"

SALT_ROUNDS="10"

ADMIN_USERNAME="admin"
ADMIN_PASSWORD_HASH="hash"

Important: Generate secure secrets for production:

openssl rand -hex 32

Important: Generate admin password hash:

node -e "console.log(require('bcrypt').hashSync('password', 10))"

5. Database Setup

Generate Prisma client and run migrations:

# Generate Prisma client
npm run db:generate

# Run database migrations
npm run db:migrate

6. Start the Development Server

npm run start:dev

API Documentation

Once the server is running, access the interactive API documentation at:

• Swagger UI: http://localhost:3000/api

Available Scripts

# Development
npm run start:dev          # Start development server with hot reload
npm run start:debug        # Start with debugging enabled

# Production
npm run build              # Build the application
npm run start:prod         # Start production server

# Database
npm run db:migrate         # Run database migrations
npm run db:generate        # Generate Prisma client
npm run db:reset           # Reset database (destructive)
npm run db:studio          # Open Prisma Studio

# Code Quality
npm run lint               # Run ESLint
npm run format             # Format code with Prettier

Project Structure

src/
├── common/                # Shared utilities and configurations
│   ├── decorators/        # Decorators
│   ├── dtos/              # Data Transfer Objects
│   ├── filters/           # Exception filters
│   ├── interceptors/      # Response interceptors
│   ├── prisma/            # Database schema and migrations
│   ├── repositories/      # Repositories
│   └── utils/             # Utility functions
├── modules/               # Feature modules
│   ├── auth/              # Auth management
│   ├── games/             # Games management
│   ├── prisma/            # Database service
│   ├── seasons/           # Seasons management
│   ├── stadiums/          # Stadiums management
│   └── teams/             # Teams management
├── app.module.ts          # Root application module
├── config.ts              # Environment configuration
└── main.ts                # Application entry point

---

Note: This project is currently in active development. Some features may be incomplete or subject to change.