Skip to content
BranchesTags

Repository files navigation

🏆College Sports Week Management Tool

Event: 3-Day Sports Week
Organizer: CSIT Students Faculties: CSIT, BCA, BSW, BBS

📚 Table of Contents

Project Overview

This tool manages a multi-faculty sports week event, providing real-time dashboards, live scoring, and automated leaderboards. Built with Bun, React, Express, PostgreSQL, Drizzle ORM, and Socket.io.

Tech Stack:

  • Runtime: Bun (v1.0+)
  • Frontend: React (Vite) + Tailwind CSS v4 + Lucide-React Icons
  • Backend: Express.js (Bun) + Drizzle ORM
  • Database: PostgreSQL 16 (Docker)
  • Real-time: Socket.io 4.8.3
  • Auth: JWT (Admin/Manager roles)
  • Deployment: Docker Compose + Tailscale VPN (recommended)
  • Reverse Proxy: Nginx
  • Container Registry: GitHub Container Registry (GHCR)

Deployment Scripts:

  • deploy-tailscale.sh - One-command Tailscale deployment
  • build-and-push.sh - Build and push Docker images to GHCR
  • deploy-homeserver.sh - Legacy homeserver deployment

Quick Links:

Entity Relationship Diagram

erDiagram
    FACULTY ||--o{ PLAYER : "enrolled in"
    FACULTY ||--o{ TEAM : "forms"
    GAME ||--o{ MATCH : "has"
    MATCH ||--o{ MATCH_PARTICIPANT : "contested by"
    TEAM ||--o{ MATCH_PARTICIPANT : "competes as"
    PLAYER ||--o{ MATCH_PARTICIPANT : "competes as"
    USER ||--o{ GAME : "assigned to manage"

    FACULTY {
        string id PK
        string name "CSIT, BCA, BSW, BBS"
        int totalPoints "Auto-calculated"
    }

    PLAYER {
        string id PK
        string name
        string facultyId FK
        string semester "e.g., 5th"
    }

    GAME {
        string id PK
        string name "Futsal, Chess, Cricket, etc."
        string type "TEAM or INDIVIDUAL"
        int pointWeight "Weight for Faculty Tally"
    }

    TEAM {
        string id PK
        string facultyId FK
        string gameId FK
        string name "e.g., CSIT 5th Tigers"
    }

    MATCH {
        string id PK
        string gameId FK
        datetime startTime
        string venue "Ground A, Hall B"
        string status "UPCOMING, LIVE, FINISHED"
    }

    MATCH_PARTICIPANT {
        string id PK
        string matchId FK
        string teamId FK "NULL if Individual"
        string playerId FK "NULL if Team"
        int score
        int pointsEarned "Points contributing to Faculty"
    }

    USER {
        string id PK
        string username
        string passwordHash
        string role "ADMIN or MANAGER"
    }
Loading

Deployment Architecture

See ARCHITECTURE.md for comprehensive deployment architecture diagrams.

Interactive Mermaid Diagrams:

  • System Architecture: Complete overview of Tailscale → Docker stack
  • Request Flow: Sequence diagram showing user interactions
  • Network Topology: Docker network and external access patterns
  • Deployment Process: Complete deployment flowchart
  • Security Layers: 4-layer security architecture
  • Scaling Options: Future growth paths
  • Traffic Patterns: User workflow diagrams
  • Monitoring Points: Observable metrics
  • Backup Strategy: Automated backup schedule

Key Architecture Highlights:

  • Tailscale VPN: WireGuard mesh network for secure access
  • Docker Compose: 4-container orchestration (nginx, backend, frontend, postgres)
  • Nginx Reverse Proxy: Routes traffic and handles WebSocket upgrades
  • Zero-Cost Hosting: Self-hosted on home server (Dell laptop)
  • Real-time Updates: Socket.io for live score broadcasting

Design System & UX/UI

See DESIGN_SYSTEM.md and UX_BEST_PRACTICES.md for full details.

Highlights:

  • Color system: Blue, green, amber, red, gray palettes
  • Typography: System UI, clear hierarchy, accessible sizes
  • Spacing: 4px grid, responsive layouts
  • Shadows, border radius, and interaction states
  • Accessibility: WCAG AA, keyboard navigation, ARIA labels
  • Responsive: Mobile-first, breakpoints for all devices

Animation System

See ANIMATIONS.md, ANIMATION_VISUAL_GUIDE.md, and ANIMATION_SUMMARY.md.

Key Components:

  • PageTransition: Smooth page loads
  • CardTransition: Staggered card/grid animations
  • StaggerContainer: Coordinated child animations
  • ListItemAnimation: List item slide/fade
  • ScaleAnimation: Badge pop-in

Specs:

  • Duration: 200-300ms
  • Easing: ease-out, spring (stiffness 300, damping 20)
  • Accessibility: Respects prefers-reduced-motion
  • GPU-accelerated (transform, opacity)

Backend & API

See backend/README.md, REFACTORING_SUMMARY.md, and BACKEND_TEST_REPORT.md.

Features:

  • Express.js backend (Bun runtime)
  • Drizzle ORM, PostgreSQL
  • JWT authentication (admin/manager)
  • Socket.io for real-time updates
  • Clean architecture: config, services, routes, middleware
  • API endpoints for faculties, games, teams, players, matches, points

Quick Start:

cd backend
bun install
bun run db:push
bun run seed
bun run dev

Frontend & Testing

See frontend/README.md, TESTING.md, and PHASE-9-CHECKLIST.md.

Features:

  • React (Vite), Tailwind CSS, Lucide Icons
  • Real-time Socket.io client
  • Protected routes (admin/manager)
  • Loading skeletons, error boundaries, toast notifications
  • Framer Motion animations
  • Comprehensive testing with Vitest, Testing Library

Testing:

cd frontend
bun test

Docker & Deployment

Complete Deployment Guides:

Local Development:

docker compose up -d
docker compose ps
docker compose logs -f

Services:

Tailscale Deployment (Recommended)

Why Tailscale?

  • ✅ $0 hosting cost
  • ✅ WireGuard encryption (bank-grade security)
  • ✅ 5-minute setup
  • ✅ No credit card required
  • ✅ No port forwarding needed
  • ✅ Works behind NAT
  • ✅ Both private AND public access options

Access Methods:

  1. Private Network (Primary) - 100% reliable, invite-only

    • Users join your Tailscale network
    • Access via: http://<device>.tail-scale.ts.net
    • Perfect for managers and authorized users

  2. Public Access (Tailscale Funnel) - Works for most users

    • Enabled with: tailscale funnel 80
    • Access via: https://<device>.saury-company.ts.net
    • No Tailscale required for viewers
    • Note: May have DNS restrictions on some mobile networks

One-Command Deployment:

./deploy-tailscale.sh

What it does:

  1. Checks prerequisites (Docker, Tailscale)
  2. Gets your Tailscale hostname automatically
  3. Generates secure passwords and JWT secret
  4. Creates .env with proper configuration
  5. Pulls Docker images from GHCR
  6. Starts all services with health checks
  7. Provides your access URLs (private + public)

Enable Public Access (Optional):

tailscale funnel 80

Build and Push Images:

./build-and-push.sh

User Access:

For Managers (Private Network):

  1. Install Tailscale
  2. Join your Tailscale network (via invite link)
  3. Access the private URL

For Public Viewers (Funnel):

  1. Just visit the public URL - no Tailscale needed!
  2. Works on most networks

See TAILSCALE_DEPLOYMENT.md for complete guide.

Cloudflare Tunnel Guide

See CLOUDFLARE_TUNNEL_SETUP.md for secure remote access setup.

Features:

  • Zero open ports on homeserver
  • Automatic HTTPS, DDoS protection
  • DNS setup, systemd service, troubleshooting

Homeserver Deployment

See HOMESERVER_DEPLOYMENT.md for full guide.

Steps:

  1. Install Docker & Compose
  2. Clone repo & configure .env
  3. Run docker compose up -d
  4. Monitor with docker compose logs -f
  5. Backup/restore database as needed

Code Architecture & Refactoring

See REFACTORING_SUMMARY.md and backend/README.md.

Highlights:

  • Clean separation: config, services, routes, middleware
  • TypeScript types throughout
  • Centralized error handling
  • Service layer for business logic
  • Real-time events: scoreUpdate, matchStatusChange, leaderboardUpdate

Testing & Reports

See BACKEND_TEST_REPORT.md, frontend/TESTING.md, and PHASE-9-COMPLETION.md.

Backend:

  • All endpoints tested (faculties, games, matches, players, teams, users, points)
  • Real-time Socket.io events verified
  • Data integrity and performance optimal

Frontend:

  • Unit/component tests with Vitest
  • 80%+ coverage on core components
  • Manual and automated test checklists

Project Phases & TODOs

See AI_CONTEXT.prompt.txt for full breakdown.

Phases:

  • Phase 0: Infrastructure Setup
  • Phase 1: Backend Foundation
  • Phase 2: Code Refactoring
  • Phase 3: Frontend & Socket.io
  • Phase 4: User Management
  • Phase 5: Admin CRUD
  • Phase 6: Manager Dashboard
  • Phase 7: Public Dashboard
  • Phase 8: Points Calculation
  • Phase 9: UI Polish & Testing
  • Phase 10: Deployment

Current Status:

  • All major features implemented
  • Production ready
  • See phase checklists for details

Support & Resources

Status: ✅ Production Ready | 🚀 Self-Hosted on Tailscale | 🌐 Publicly Accessible
Deployment: ✅ One-command setup (./deploy-tailscale.sh) - 5 minutes from zero to deployed
Cost: $0 - Self-hosted on home server (Dell laptop) with Tailscale VPN
Access:

  • 🔒 Private Network: Secure invite-only access for managers via Tailscale mesh
  • 🌍 Public Access: Available via Tailscale Funnel (no Tailscale required for viewers)
    Features: Real-time scoring, live leaderboards, team management, automated points calculation

Recommended Deployment: Tailscale (see TAILSCALE_DEPLOYMENT.md)
Alternative: Cloudflare Tunnel has free tier limitations - see DEPLOYMENT_COMPARISON.md

Documentation:

PS : This sevice may be unavailable after the event ends.

Last Updated: February 9, 2026

About

This tool manages a multi-faculty sports week event, providing real-time dashboards, live scoring, and automated leaderboards. Built with Bun, React, Express, PostgreSQL, Drizzle ORM, and Socket.io.

krishom-dell-1.saury-company.ts.net/

Topics

buncollege-projectdrizzle-ormexpressnetworkingpostgresqlreactself-hostedsystem-designtailscalewebsocket

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages