How sachin210506/sportsrealtime works
Purpose and entry points
SportRealTime is a full-stack live sports management and commentary system. The Node/Express API starts at src/index.js; it exposes REST endpoints and attaches the WebSocket transport. The React/Vite single-page client starts at client/src/main.jsx and renders its application shell from client/src/App.jsx.
API composition and access control
Route modules separate domain APIs for identity, matches, live commentary/events, subscriptions, and notifications: src/routes/auth.js, src/routes/matches.js, and src/routes/commentary.js. Authentication is JWT/session-based with viewer, commentator, and admin roles, enforced through src/middleware/auth.js. Request payload boundaries are validated with Zod schemas under src/validation/, notably src/validation/matches.js and src/validation/events.js.
Persistent domain model
PostgreSQL is the system of record, accessed through pg and Drizzle in src/db/db.js. The central relational model—users, matches, commentary, subscriptions, match events, and notifications—is defined in src/db/schema.js; its initial migration is drizzle/0000_next_klaw.sql. This creates a clear boundary between route-level command/query handling and database persistence.
Live-update pipeline
The WebSocket server in src/ws/server.js owns connection and per-match subscription management at /ws. Clients subscribe or unsubscribe by match ID; authenticated connections can restore subscriptions. Match creation, commentary writes, structured events, score changes, and status changes flow from REST mutations to WebSocket broadcasts, allowing subscribed clients to update without polling.
Match lifecycle and external data
Match APIs in src/routes/matches.js manage list/detail views, creation, scores, and status. Commentary and structured incidents are distinct streams handled by src/routes/commentary.js and src/routes/events.js. Real fixtures/results are imported from TheSportsDB through src/services/sportsdb.js; the seed workflow in src/seed/seed.js maps external events into local matches and can simulate a live match. Match status interpretation is centralized in src/utils/match-status.js.
Client state and interaction boundaries
The React client calls the REST API through client/src/api.js, while client/src/contexts/WsContext.jsx maintains the live socket and distributes updates. client/src/contexts/AuthContext.jsx owns authenticated user/session state. Primary product views are client/src/pages/MatchesPage.jsx, client/src/pages/MatchDetail.jsx, and client/src/pages/NotificationsPage.jsx; these combine initial HTTP data with WebSocket-driven changes.
Runtime, infrastructure, and protection
The backend runs on Node.js with Express and ws; the frontend builds with Vite. PostgreSQL may be hosted by Neon, configured through DATABASE_URL, with Drizzle migrations configured by drizzle.config.js. TheSportsDB is an external fixture/results provider. Optional operational controls include Arcjet request protection in src/arcjet.js and APM configured through environment variables. CORS connects the separately deployed client and API, with the client configured via its environment settings.
Main entry points: index.js Express API · matches.js Match API · db.js Drizzle database access · commentary.js Commentary API
Components 17
React client
- Application shell
client/src/App.jsx - REST API client
client/src/api.js - Auth state · Owns authenticated user and session state.
client/src/contexts/AuthContext.jsx - Socket state · Maintains the live connection and distributes updates.
client/src/contexts/WsContext.jsx - Match and notification views · Combines initial HTTP data with live changes.
client/src/pages/MatchDetail.jsx
Node API
- Express API · Hosts REST endpoints and attaches WebSocket transport.
src/index.js - JWT and role guard · Enforces viewer, commentator, and admin access.
src/middleware/auth.js - Match API · Handles match views, creation, scores, and status.
src/routes/matches.js - Commentary API · Handles commentary writes.
src/routes/commentary.js - Event API · Handles structured match incidents.
src/routes/events.js - Request schemas
src/validation/matches.js
Live updates
- Match subscription server · Manages authenticated connections and per-match subscriptions at /ws.
src/ws/server.js
Data and integrations
- PostgreSQL · Stores users, matches, commentary, subscriptions, events, and notifications.
src/db/schema.js - Drizzle database access
src/db/db.js - Fixture import and seed · Maps external events to local matches and can simulate live play.
src/seed/seed.js - TheSportsDB · Provides fixture and result data.
src/services/sportsdb.js - Match status rules · Centralizes status interpretation.
src/utils/match-status.js
Connections 24
- Application shell → Auth state: reads session
- Application shell → Socket state: uses live state
- Application shell → Match and notification views: renders
- Match and notification views → REST API client: initial queries and mutations
- Match and notification views → Socket state: live changes
- REST API client → Express API: REST
- Socket state → Match subscription server: WebSocket /ws
- Express API → JWT and role guard: protects requests
- Express API → Match API: routes
- Express API → Commentary API: routes
- Express API → Event API: routes
- Match API → Request schemas: validates payloads
- Commentary API → Request schemas: validates payloads
- Event API → Request schemas: validates payloads
- Match API → Drizzle database access: reads and writes matches
- Commentary API → Drizzle database access: writes commentary
- Event API → Drizzle database access: writes incidents
- Match API → Match status rules: interprets status
- Drizzle database access → PostgreSQL: persists domain data
- Match API → Match subscription server: broadcasts match changes
- Commentary API → Match subscription server: broadcasts commentary
- Event API → Match subscription server: broadcasts incidents
- TheSportsDB → Fixture import and seed: fixtures and results
- Fixture import and seed → Drizzle database access: imports local matches