# sandesh-pg/sportz architecture

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

- Interactive diagram: https://gitdiagram.com/sandesh-pg/sportz
- Repository: https://github.com/sandesh-pg/sportz

## Overview

Sportz is a sports-match API with persistent match and commentary records, plus WebSocket updates for connected clients. The main workflow accepts match or commentary requests, validates them, stores them in PostgreSQL, and broadcasts successful creations. A seed process can populate the service through its REST API. The graph reflects visible route registration and calls; the README is empty, and the excerpts do not show every seed operation or database migration detail.

Main entry points: [`src/routes/matches.js`](https://github.com/sandesh-pg/sportz/blob/main/src/routes/matches.js) (Match Routes), [`src/routes/commantary.js`](https://github.com/sandesh-pg/sportz/blob/main/src/routes/commantary.js) (Commentary Routes), [`src/index.js`](https://github.com/sandesh-pg/sportz/blob/main/src/index.js) (HTTP Server), [`src/ws/server.js`](https://github.com/sandesh-pg/sportz/blob/main/src/ws/server.js) (WebSocket Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_entry["HTTP Server<br/>[index.js]"]
  node_matches["Match Routes<br/>[matches.js]"]
  node_commentary["Commentary Routes<br/>[commantary.js]"]
end

subgraph group_domain["Match Domain"]
  node_matchvalidation["Match Validation<br/>[matches.js]"]
  node_commentaryvalidation["Commentary Validation<br/>[commentary.js]"]
  node_status["Match Status<br/>[matches-status.js]"]
end

subgraph group_realtime["Live Updates"]
  node_websocket["WebSocket Service<br/>[server.js]"]
  node_security["Arcjet Security<br/>[arcjet.js]"]
end

subgraph group_persistence["Persistence and Seeding"]
  node_database[("PostgreSQL<br/>[db.js]")]
  node_schema["Match Data Schema<br/>[schema.js]"]
  node_seed["Seed Process<br/>[seed.js]"]
  node_seeddata["Seed Data<br/>[data.json]"]
end

node_client(("API Client"))

node_client -->|"sends requests"| node_entry
node_entry -->|"mounts routes"| node_matches
node_entry -->|"mounts routes"| node_commentary
node_entry -->|"attaches server"| node_websocket
node_matches -->|"validates input"| node_matchvalidation
node_matches -->|"derives status"| node_status
node_matches -->|"reads and writes"| node_database
node_matches -->|"queries matches"| node_schema
node_commentary -->|"validates match ID"| node_matchvalidation
node_commentary -->|"validates commentary"| node_commentaryvalidation
node_commentary -->|"reads and writes"| node_database
node_commentary -->|"queries commentary"| node_schema
node_matches -->|"broadcasts match creation"| node_websocket
node_commentary -->|"broadcasts commentary"| node_websocket
node_websocket -->|"protects connections"| node_security
node_seed -->|"loads seed input"| node_seeddata
node_seed -.->|"creates via REST"| node_matches
node_seed -->|"posts via REST"| node_commentary

click node_entry "https://github.com/sandesh-pg/sportz/blob/main/src/index.js"
click node_matches "https://github.com/sandesh-pg/sportz/blob/main/src/routes/matches.js"
click node_commentary "https://github.com/sandesh-pg/sportz/blob/main/src/routes/commantary.js"
click node_matchvalidation "https://github.com/sandesh-pg/sportz/blob/main/src/validation/matches.js"
click node_commentaryvalidation "https://github.com/sandesh-pg/sportz/blob/main/src/validation/commentary.js"
click node_status "https://github.com/sandesh-pg/sportz/blob/main/src/utils/matches-status.js"
click node_websocket "https://github.com/sandesh-pg/sportz/blob/main/src/ws/server.js"
click node_security "https://github.com/sandesh-pg/sportz/blob/main/src/arcjet.js"
click node_database "https://github.com/sandesh-pg/sportz/blob/main/src/db/db.js"
click node_schema "https://github.com/sandesh-pg/sportz/blob/main/src/db/schema.js"
click node_seed "https://github.com/sandesh-pg/sportz/blob/main/src/seed/seed.js"
click node_seeddata "https://github.com/sandesh-pg/sportz/blob/main/src/data/data.json"

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_entry,node_matches,node_commentary,node_client toneBlue
class node_matchvalidation,node_commentaryvalidation,node_status toneAmber
class node_websocket,node_security toneMint
class node_database,node_schema,node_seed,node_seeddata toneRose
```

## Components

### HTTP API

- [HTTP Server](https://github.com/sandesh-pg/sportz/blob/main/src/index.js): `src/index.js`
- [Match Routes](https://github.com/sandesh-pg/sportz/blob/main/src/routes/matches.js): `src/routes/matches.js`
- [Commentary Routes](https://github.com/sandesh-pg/sportz/blob/main/src/routes/commantary.js): `src/routes/commantary.js`

### Match Domain

- [Match Validation](https://github.com/sandesh-pg/sportz/blob/main/src/validation/matches.js): `src/validation/matches.js`
- [Commentary Validation](https://github.com/sandesh-pg/sportz/blob/main/src/validation/commentary.js): `src/validation/commentary.js`
- [Match Status](https://github.com/sandesh-pg/sportz/blob/main/src/utils/matches-status.js): `src/utils/matches-status.js`

### Live Updates

- [WebSocket Service](https://github.com/sandesh-pg/sportz/blob/main/src/ws/server.js): `src/ws/server.js`
- [Arcjet Security](https://github.com/sandesh-pg/sportz/blob/main/src/arcjet.js): `src/arcjet.js`

### Persistence and Seeding

- [PostgreSQL](https://github.com/sandesh-pg/sportz/blob/main/src/db/db.js): `src/db/db.js`
- [Match Data Schema](https://github.com/sandesh-pg/sportz/blob/main/src/db/schema.js): `src/db/schema.js`
- [Seed Process](https://github.com/sandesh-pg/sportz/blob/main/src/seed/seed.js): `src/seed/seed.js`
- [Seed Data](https://github.com/sandesh-pg/sportz/blob/main/src/data/data.json): `src/data/data.json`

### Other components

- **API Client**

## Connections

- API Client → HTTP Server: sends requests (evidence: `src/index.js`)
- HTTP Server → Match Routes: mounts routes (evidence: `src/index.js`)
- HTTP Server → Commentary Routes: mounts routes (evidence: `src/index.js`)
- HTTP Server → WebSocket Service: attaches server (evidence: `src/index.js`)
- Match Routes → Match Validation: validates input (evidence: `src/routes/matches.js`)
- Match Routes → Match Status: derives status (evidence: `src/routes/matches.js`)
- Match Routes → PostgreSQL: reads and writes (evidence: `src/routes/matches.js`)
- Match Routes → Match Data Schema: queries matches (evidence: `src/routes/matches.js`)
- Commentary Routes → Match Validation: validates match ID (evidence: `src/routes/commantary.js`)
- Commentary Routes → Commentary Validation: validates commentary (evidence: `src/routes/commantary.js`)
- Commentary Routes → PostgreSQL: reads and writes (evidence: `src/routes/commantary.js`)
- Commentary Routes → Match Data Schema: queries commentary (evidence: `src/routes/commantary.js`)
- Match Routes → WebSocket Service: broadcasts match creation (evidence: `src/routes/matches.js`)
- Commentary Routes → WebSocket Service: broadcasts commentary (evidence: `src/routes/commantary.js`)
- WebSocket Service → Arcjet Security: protects connections (evidence: `src/ws/server.js`)
- Seed Process → Seed Data: loads seed input (evidence: `src/seed/seed.js`)
- Seed Process → Match Routes: creates via REST
- Seed Process → Commentary Routes: posts via REST (evidence: `src/seed/seed.js`)
