# sachin210506/sportsrealtime architecture

> Architecture diagram of the GitHub repository sachin210506/sportsrealtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sachin210506/sportsrealtime
- Repository: https://github.com/sachin210506/sportsrealtime

## Overview

#### 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: [`src/index.js`](https://github.com/sachin210506/sportsrealtime/blob/main/src/index.js) (Express API), [`src/routes/matches.js`](https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/matches.js) (Match API), [`src/db/db.js`](https://github.com/sachin210506/sportsrealtime/blob/main/src/db/db.js) (Drizzle database access), [`src/routes/commentary.js`](https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/commentary.js) (Commentary API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_app["Application shell<br/>React application<br/>[App.jsx]"]
  node_client_api["REST API client<br/>HTTP client<br/>[api.js]"]
  node_auth_context["Auth state<br/>React context<br/>[AuthContext.jsx]"]
  node_ws_context["Socket state<br/>React context<br/>[WsContext.jsx]"]
  node_product_views["Match and notification views<br/>React pages<br/>[MatchDetail.jsx]"]
end

subgraph group_api["Node API"]
  node_api_server{{"Express API<br/>Node entry point<br/>[index.js]"}}
  node_auth_middleware["JWT and role guard<br/>Express middleware<br/>[auth.js]"]
  node_match_routes["Match API<br/>route module<br/>[matches.js]"]
  node_commentary_routes["Commentary API<br/>route module<br/>[commentary.js]"]
  node_event_routes["Event API<br/>route module<br/>[events.js]"]
  node_validation["Request schemas<br/>Zod validation<br/>[matches.js]"]
end

subgraph group_live["Live updates"]
  node_ws_server{{"Match subscription server<br/>WebSocket server<br/>[server.js]"}}
end

subgraph group_data["Data and integrations"]
  node_database[("PostgreSQL<br/>system of record<br/>[schema.js]")]
  node_db_access["Drizzle database access<br/>pg and Drizzle<br/>[db.js]"]
  node_seed_import["Fixture import and seed<br/>seed workflow<br/>[seed.js]"]
  node_sportsdb["TheSportsDB<br/>external sports data<br/>[sportsdb.js]"]
  node_status_rules["Match status rules<br/>domain utility<br/>[match-status.js]"]
end

node_app -->|"reads session"| node_auth_context
node_app -->|"uses live state"| node_ws_context
node_app -->|"renders"| node_product_views
node_product_views -->|"initial queries and mutations"| node_client_api
node_product_views -->|"live changes"| node_ws_context
node_client_api -->|"REST"| node_api_server
node_ws_context -->|"WebSocket /ws"| node_ws_server
node_api_server -->|"protects requests"| node_auth_middleware
node_api_server -->|"routes"| node_match_routes
node_api_server -->|"routes"| node_commentary_routes
node_api_server -->|"routes"| node_event_routes
node_match_routes -->|"validates payloads"| node_validation
node_commentary_routes -->|"validates payloads"| node_validation
node_event_routes -->|"validates payloads"| node_validation
node_match_routes -->|"reads and writes matches"| node_db_access
node_commentary_routes -->|"writes commentary"| node_db_access
node_event_routes -->|"writes incidents"| node_db_access
node_match_routes -->|"interprets status"| node_status_rules
node_db_access -->|"persists domain data"| node_database
node_match_routes -->|"broadcasts match changes"| node_ws_server
node_commentary_routes -->|"broadcasts commentary"| node_ws_server
node_event_routes -->|"broadcasts incidents"| node_ws_server
node_sportsdb -->|"fixtures and results"| node_seed_import
node_seed_import -->|"imports local matches"| node_db_access

click node_app "https://github.com/sachin210506/sportsrealtime/blob/main/client/src/App.jsx"
click node_client_api "https://github.com/sachin210506/sportsrealtime/blob/main/client/src/api.js"
click node_auth_context "https://github.com/sachin210506/sportsrealtime/blob/main/client/src/contexts/AuthContext.jsx"
click node_ws_context "https://github.com/sachin210506/sportsrealtime/blob/main/client/src/contexts/WsContext.jsx"
click node_product_views "https://github.com/sachin210506/sportsrealtime/blob/main/client/src/pages/MatchDetail.jsx"
click node_api_server "https://github.com/sachin210506/sportsrealtime/blob/main/src/index.js"
click node_auth_middleware "https://github.com/sachin210506/sportsrealtime/blob/main/src/middleware/auth.js"
click node_match_routes "https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/matches.js"
click node_commentary_routes "https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/commentary.js"
click node_event_routes "https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/events.js"
click node_validation "https://github.com/sachin210506/sportsrealtime/blob/main/src/validation/matches.js"
click node_ws_server "https://github.com/sachin210506/sportsrealtime/blob/main/src/ws/server.js"
click node_database "https://github.com/sachin210506/sportsrealtime/blob/main/src/db/schema.js"
click node_db_access "https://github.com/sachin210506/sportsrealtime/blob/main/src/db/db.js"
click node_seed_import "https://github.com/sachin210506/sportsrealtime/blob/main/src/seed/seed.js"
click node_sportsdb "https://github.com/sachin210506/sportsrealtime/blob/main/src/services/sportsdb.js"
click node_status_rules "https://github.com/sachin210506/sportsrealtime/blob/main/src/utils/match-status.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_client_api,node_auth_context,node_ws_context,node_product_views toneBlue
class node_api_server,node_auth_middleware,node_match_routes,node_commentary_routes,node_event_routes,node_validation toneAmber
class node_ws_server toneMint
class node_database,node_db_access,node_seed_import,node_sportsdb,node_status_rules toneRose
```

## Components

### React client

- [Application shell](https://github.com/sachin210506/sportsrealtime/blob/main/client/src/App.jsx): React application · `client/src/App.jsx`
- [REST API client](https://github.com/sachin210506/sportsrealtime/blob/main/client/src/api.js): HTTP client · `client/src/api.js`
- [Auth state](https://github.com/sachin210506/sportsrealtime/blob/main/client/src/contexts/AuthContext.jsx): React context · Owns authenticated user and session state. · `client/src/contexts/AuthContext.jsx`
- [Socket state](https://github.com/sachin210506/sportsrealtime/blob/main/client/src/contexts/WsContext.jsx): React context · Maintains the live connection and distributes updates. · `client/src/contexts/WsContext.jsx`
- [Match and notification views](https://github.com/sachin210506/sportsrealtime/blob/main/client/src/pages/MatchDetail.jsx): React pages · Combines initial HTTP data with live changes. · `client/src/pages/MatchDetail.jsx`

### Node API

- [Express API](https://github.com/sachin210506/sportsrealtime/blob/main/src/index.js): Node entry point · Hosts REST endpoints and attaches WebSocket transport. · `src/index.js`
- [JWT and role guard](https://github.com/sachin210506/sportsrealtime/blob/main/src/middleware/auth.js): Express middleware · Enforces viewer, commentator, and admin access. · `src/middleware/auth.js`
- [Match API](https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/matches.js): route module · Handles match views, creation, scores, and status. · `src/routes/matches.js`
- [Commentary API](https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/commentary.js): route module · Handles commentary writes. · `src/routes/commentary.js`
- [Event API](https://github.com/sachin210506/sportsrealtime/blob/main/src/routes/events.js): route module · Handles structured match incidents. · `src/routes/events.js`
- [Request schemas](https://github.com/sachin210506/sportsrealtime/blob/main/src/validation/matches.js): Zod validation · `src/validation/matches.js`

### Live updates

- [Match subscription server](https://github.com/sachin210506/sportsrealtime/blob/main/src/ws/server.js): WebSocket server · Manages authenticated connections and per-match subscriptions at /ws. · `src/ws/server.js`

### Data and integrations

- [PostgreSQL](https://github.com/sachin210506/sportsrealtime/blob/main/src/db/schema.js): system of record · Stores users, matches, commentary, subscriptions, events, and notifications. · `src/db/schema.js`
- [Drizzle database access](https://github.com/sachin210506/sportsrealtime/blob/main/src/db/db.js): pg and Drizzle · `src/db/db.js`
- [Fixture import and seed](https://github.com/sachin210506/sportsrealtime/blob/main/src/seed/seed.js): seed workflow · Maps external events to local matches and can simulate live play. · `src/seed/seed.js`
- [TheSportsDB](https://github.com/sachin210506/sportsrealtime/blob/main/src/services/sportsdb.js): external sports data · Provides fixture and result data. · `src/services/sportsdb.js`
- [Match status rules](https://github.com/sachin210506/sportsrealtime/blob/main/src/utils/match-status.js): domain utility · Centralizes status interpretation. · `src/utils/match-status.js`

## Connections

- 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