{"id":29407789,"url":"https://github.com/Simon-Fontaine/spectra","last_synced_at":"2025-07-11T01:11:17.880Z","repository":{"id":276041291,"uuid":"925744676","full_name":"Simon-Fontaine/spectra","owner":"Simon-Fontaine","description":"A Next.js application demonstrating custom authentication using sessions, CSRF protection, and email verification.","archived":false,"fork":false,"pushed_at":"2025-02-06T14:05:38.000Z","size":2438,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-14T05:39:50.403Z","etag":null,"topics":["admin-dashboard","authentication","csrf-protection","email-verification","nextjs","overwatch-2","postgresql","prisma","rate-limiting","redis","session-management","tailwindcss","team-management","typescript","upstash","vercel"],"latest_commit_sha":null,"homepage":"https://owspectra.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Simon-Fontaine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-01T16:39:47.000Z","updated_at":"2025-02-06T14:05:41.000Z","dependencies_parsed_at":"2025-04-14T05:46:48.661Z","dependency_job_id":null,"html_url":"https://github.com/Simon-Fontaine/spectra","commit_stats":null,"previous_names":["simon-fontaine/spectra"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Simon-Fontaine/spectra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simon-Fontaine%2Fspectra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simon-Fontaine%2Fspectra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simon-Fontaine%2Fspectra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simon-Fontaine%2Fspectra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Simon-Fontaine","download_url":"https://codeload.github.com/Simon-Fontaine/spectra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Simon-Fontaine%2Fspectra/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264703380,"owners_count":23651955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin-dashboard","authentication","csrf-protection","email-verification","nextjs","overwatch-2","postgresql","prisma","rate-limiting","redis","session-management","tailwindcss","team-management","typescript","upstash","vercel"],"created_at":"2025-07-11T01:11:13.642Z","updated_at":"2025-07-11T01:11:17.845Z","avatar_url":"https://github.com/Simon-Fontaine.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spectra\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/Simon-Fontaine/spectra?tab=MIT-1-ov-file)\n\n**Spectra** is a **Next.js 15+** application designed primarily for Overwatch 2 e-sport **team management**—including rosters, schedules, and admin tooling—while showcasing a robust, **reusable** custom authentication system. Its modular auth logic (featuring sessions, CSRF tokens, email verification, and rate-limiting) can be easily **ported** or **adapted** into other Next.js projects.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)  \n- [Features](#features)  \n- [Tech Stack](#tech-stack)  \n- [Project Structure](#project-structure)  \n- [Getting Started](#getting-started)  \n  - [Requirements](#requirements)  \n  - [1. Clone the Repository](#1-clone-the-repository)  \n  - [2. Install Dependencies](#2-install-dependencies)  \n  - [3. Set Up Environment Variables](#3-set-up-environment-variables)  \n  - [4. Run Database Migrations](#4-run-database-migrations)  \n  - [5. Start the Development Server](#5-start-the-development-server)  \n- [Scripts](#scripts)  \n- [Deployment](#deployment)  \n- [Authentication Flow](#authentication-flow)  \n- [Security Considerations](#security-considerations)  \n- [Contributing](#contributing)  \n- [License](#license)  \n- [Additional Resources](#additional-resources)\n\n---\n\n## Overview\n\n**Spectra** is a Next.js website that manages an Overwatch 2 e-sport team—from rosters to user roles and schedules—backed by a **bespoke, self-contained auth** system. While the site itself is dedicated to Overwatch 2 management, the **authentication** logic (short-lived sessions, email verification, etc.) is **modular** enough for you to lift and integrate into your own Next.js applications.\n\n**Key Highlights**:\n\n- Tailored for Overwatch 2 team management but adaptable to any team-based or membership scenario.\n- **Reusable** authentication layer that uses short-lived sessions, rate-limiting, and secure email verification.\n- Offers advanced admin features like user role management, invite-only registration, session revocation, and more.\n\n---\n\n## Features\n\n1. **Team Management**  \n   - Create and maintain Overwatch 2 rosters, including roles (DPS, Tank, Support), coaches, and subs.\n   - Admin dashboards to oversee player stats, replays, schedules, etc.\n\n2. **Custom Auth System**  \n   - Registration with optional invite-only workflow.\n   - Passwords hashed via [bcrypt](https://github.com/kelektiv/node.bcrypt.js).\n   - **Email verification** links and forced email validation.\n\n3. **Sessions \u0026 CSRF**  \n   - Short-lived **httpOnly** session cookies with **sliding expiration**.\n   - Per-session CSRF token to thwart cross-site request forgery attacks.\n\n4. **Rate Limiting**  \n   - [Upstash Ratelimit](https://github.com/upstash/ratelimit-js) protects against brute-force login attempts.\n\n5. **GeoIP \u0026 Analytics** *(Optional)*  \n   - Integrates [MaxMind GeoIP2](https://github.com/maxmind/GeoIP2-node) for approximate user location.\n\n6. **Email Services**  \n   - Transactional emails managed by [Resend](https://resend.com).\n\n---\n\n## Tech Stack\n\n- **Next.js 15+** (App Router)  \n- **TypeScript**  \n- **Prisma** + PostgreSQL  \n- **Bcrypt** for password hashing  \n- **Upstash** Redis \u0026 Ratelimit for login security  \n- **GeoIP2** for optional location lookups  \n- **Resend** for emails  \n- **Tailwind CSS** for UI  \n- **Zod** for schema validation  \n- Deployed on **Vercel** or any Next.js-friendly platform\n\n---\n\n## Project Structure\n\nHere's a quick look at the repo:\n\n```bash\nspectra/\n├── app/                    # Next.js App Router \n│   ├── (auth)/             # Auth pages (sign-in, sign-up, reset password, etc.)\n│   ├── (home)/             # Public pages (news, roster, etc.)\n│   ├── dashboard/          # Protected admin/team management\n│   ├── api/                # Route handlers (e.g., /api/auth/login)\n│   ├── middleware.ts       # Session \u0026 auth checks\n│   └── ...\n├── components/             # UI components (forms, nav, etc.)\n├── hooks/                  # Custom React hooks\n├── lib/                    # Core utilities (prisma, redis, email, auth logic, etc.)\n├── prisma/                 # Prisma schema \u0026 migrations\n├── public/                 # Static assets\n├── types/                  # TS type definitions\n├── .env.example\n├── package.json\n├── tailwind.config.ts\n└── README.md\n```\n\n---\n\n## Getting Started\n\n### Requirements\n\n1. **Node.js 18+**  \n2. **PostgreSQL** (local or hosted)  \n3. **Upstash Redis** (optional but recommended for rate-limiting)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/Simon-Fontaine/spectra.git\n```\n\n### 2. Install Dependencies\n\n```bash\ncd spectra\nnpm install --legacy-peer-deps\n# or yarn install / pnpm install\n```\n\n### 3. Set Up Environment Variables\n\nCreate a `.env.local` (or use `.env.example` as reference):\n\n```env\nDATABASE_URL=\"your-postgres-url\"\nUPSTASH_REDIS_REST_TOKEN=\"your-upstash-redis-token\"\nUPSTASH_REDIS_REST_URL=\"your-upstash-redis-url\"\nBLOB_READ_WRITE_TOKEN=\"your-vercel-blob-read-write-token\"\nJWT_SECRET=\"your-jwt-secret\"\nJWT_ISSUER=\"your-jwt-issuer\"\nJWT_AUDIENCE=\"your-jwt-audience\"\nRESEND_API_KEY=\"your-resend-api-key\"\nPULSE_API_KEY=\"(optional) for Prisma Pulse\"\nREGISTRATION_ENABLED=true\nREGISTRATION_INVITE_ONLY=true\n```\n\n### 4. Run Database Migrations\n\n```bash\nnpx prisma migrate deploy\n```\n\n### 5. Start the Development Server\n\n```bash\nnpm run dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) to explore.\n\n---\n\n## Scripts\n\n| Script             | Description                                           |\n|--------------------|-------------------------------------------------------|\n| **`npm run dev`**  | Starts the local dev server (with turbopack).         |\n| **`npm run build`**| Builds production bundles for Next.js.               |\n| **`npm run start`**| Runs the app in production mode.                      |\n| **`npm run lint`** | Lints the code with Biome/ESLint.                     |\n\n---\n\n## Deployment\n\nYou can deploy this project to **Vercel** or any Next.js-supporting platform:\n\n1. Ensure environment variables (in `.env.*`) are set in your host’s config.  \n2. Run build scripts (`npm run build`) or rely on your host’s auto-build.  \n3. Confirm your **database**, **redis** config, and **email** provider keys.  \n\nOnce deployed, your Overwatch 2 team management site, along with its robust custom authentication, is live.\n\n---\n\n## Authentication Flow\n\n1. **Registration**  \n   - Invite-based or open registration, depending on environment config.\n   - User picks a unique username, email, and password.\n\n2. **Email Verification**  \n   - A verification link is sent to the user’s email.\n   - Clicking it confirms the user’s email in the database.\n\n3. **Login**  \n   - On successful credential check, a short-lived session cookie + CSRF token is issued.\n\n4. **Session Management**  \n   - Sessions extend automatically if the user is active but expire after prolonged inactivity.\n   - CSRF tokens protect state-changing requests.\n\n5. **Logout**  \n   - Session is invalidated server-side, and client cookies are cleared.\n\n---\n\n## Security Considerations\n\n- **Password Hashing**: Uses bcrypt to hash passwords.  \n- **HTTP-Only Cookies**: Session tokens are not accessible to JavaScript.  \n- **CSRF Protection**: Each session has a unique CSRF secret validated on requests.  \n- **Rate Limiting**: Helps thwart brute-force attempts on login endpoints.  \n- **Sliding Expiration**: Sessions refresh on activity but eventually expire if idle.\n\n---\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. **Fork** the repository.  \n2. **Create a branch** with your feature/fix.  \n3. **Make changes** and commit.  \n4. **Open a PR** to merge into `main`.\n\nThank you for helping improve **Spectra**!\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](https://github.com/Simon-Fontaine/spectra?tab=MIT-1-ov-file). Feel free to modify or adapt for commercial and personal use.\n\n---\n\n## Additional Resources\n\n- [Upstash Ratelimit](https://github.com/upstash/ratelimit-js)  \n- [Redis](https://github.com/upstash/redis-js)  \n- [MaxMind GeoIP2](https://github.com/maxmind/GeoIP2-node)  \n- [Vercel](https://vercel.com)  \n- [bcrypt](https://github.com/kelektiv/node.bcrypt.js)\n\n---\n\nEnjoy your **Overwatch 2** team management site with fully customizable authentication! If you run into any issues, feel free to open an [issue](https://github.com/Simon-Fontaine/spectra/issues) or discussion.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimon-Fontaine%2Fspectra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSimon-Fontaine%2Fspectra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimon-Fontaine%2Fspectra/lists"}