# jeniltank/box-cricket architecture

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

- Interactive diagram: https://gitdiagram.com/jeniltank/box-cricket
- Repository: https://github.com/jeniltank/box-cricket

## Overview

Box Cricket is a live scoring and tournament-management application. An operator configures teams and a match, records ball-by-ball results, and synchronizes match state to a broadcast display; team and player rosters can also be managed separately. The repository contains both root-level browser clients and a Next.js client under extra/client. The README documents the live-sync flow, while sampled server code confirms PostgreSQL persistence and team APIs; some client wiring is documented rather than directly sampled.

Main entry points: [`server.js`](https://github.com/jeniltank/box-cricket/blob/main/server.js) (HTTP and Socket Server), [`extra/client/src/app/admin/page.js`](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/app/admin/page.js) (Admin Page), [`extra/client/src/context/SocketContext.js`](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/context/SocketContext.js) (Socket Provider), [`extra/client/src/app/teams/page.js`](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/app/teams/page.js) (Teams Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scoring["Match Scoring"]
  node_admin["Scoring Dashboard<br/>[admin.js]"]
  node_matchstate["Scoring State<br/>[useMatchState.js]"]
  node_validation["Input Validation<br/>[useValidation.js]"]
  node_adminpage["Admin Page<br/>[page.js]"]
end

subgraph group_broadcast["Broadcast Display"]
  node_broadcastview["Broadcast Renderer<br/>[broadcast.js]"]
  node_broadcastcomponents["Broadcast Overlays"]
end

subgraph group_teams["Team Management"]
  node_teams["Roster Management<br/>[teams.js]"]
  node_teamspage["Teams Page<br/>[page.js]"]
end

subgraph group_backend["Backend and Persistence"]
  node_server["HTTP and Socket Server<br/>[server.js]"]
  node_database[("PostgreSQL")]
end

subgraph group_client["Next Client"]
  node_socketcontext["Socket Provider<br/>[SocketContext.js]"]
end

node_operator(("Match Operator"))
node_viewer(("TV Viewer"))
node_teammanager(("Team Manager"))

node_operator -->|"scores match"| node_admin
node_admin -->|"sends state"| node_server
node_server -->|"broadcasts updates"| node_admin
node_server -->|"persists state"| node_database
node_server -->|"broadcasts state"| node_broadcastview
node_broadcastview -->|"renders graphics"| node_viewer
node_viewer -->|"views overlays"| node_broadcastcomponents
node_teammanager -->|"manages rosters"| node_teams
node_teammanager -->|"manages rosters"| node_teamspage
node_teamspage -->|"calls team APIs"| node_server
node_server -->|"stores rosters"| node_database
node_operator -->|"configures match"| node_adminpage
node_adminpage -->|"uses scoring state"| node_matchstate
node_adminpage -->|"validates inputs"| node_validation
node_adminpage -->|"renders overlays"| node_broadcastcomponents
node_matchstate -->|"uses socket"| node_socketcontext
node_teamspage -->|"uses socket"| node_socketcontext
node_socketcontext -.->|"connects by Socket.IO"| node_server
node_adminpage -->|"uses socket"| node_socketcontext

click node_admin "https://github.com/jeniltank/box-cricket/blob/main/admin.js"
click node_matchstate "https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/hooks/useMatchState.js"
click node_validation "https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/hooks/useValidation.js"
click node_adminpage "https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/app/admin/page.js"
click node_broadcastview "https://github.com/jeniltank/box-cricket/blob/main/broadcast.js"
click node_broadcastcomponents "https://github.com/jeniltank/box-cricket/tree/main/extra/client/src/components/broadcast"
click node_teams "https://github.com/jeniltank/box-cricket/blob/main/teams.js"
click node_teamspage "https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/app/teams/page.js"
click node_socketcontext "https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/context/SocketContext.js"
click node_server "https://github.com/jeniltank/box-cricket/blob/main/server.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_admin,node_matchstate,node_validation,node_adminpage,node_viewer toneBlue
class node_broadcastview,node_broadcastcomponents toneAmber
class node_teams,node_teamspage toneMint
class node_server,node_database toneRose
class node_socketcontext,node_operator,node_teammanager toneIndigo
```

## Components

### Match Scoring

- [Scoring Dashboard](https://github.com/jeniltank/box-cricket/blob/main/admin.js): `admin.js`
- [Scoring State](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/hooks/useMatchState.js): `extra/client/src/hooks/useMatchState.js`
- [Input Validation](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/hooks/useValidation.js): `extra/client/src/hooks/useValidation.js`
- [Admin Page](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/app/admin/page.js): `extra/client/src/app/admin/page.js`

### Broadcast Display

- [Broadcast Renderer](https://github.com/jeniltank/box-cricket/blob/main/broadcast.js): `broadcast.js`
- [Broadcast Overlays](https://github.com/jeniltank/box-cricket/tree/main/extra/client/src/components/broadcast): `extra/client/src/components/broadcast`

### Team Management

- [Roster Management](https://github.com/jeniltank/box-cricket/blob/main/teams.js): `teams.js`
- [Teams Page](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/app/teams/page.js): `extra/client/src/app/teams/page.js`

### Backend and Persistence

- [HTTP and Socket Server](https://github.com/jeniltank/box-cricket/blob/main/server.js): `server.js`
- **PostgreSQL**

### Next Client

- [Socket Provider](https://github.com/jeniltank/box-cricket/blob/main/extra/client/src/context/SocketContext.js): `extra/client/src/context/SocketContext.js`

### Other components

- **Match Operator**
- **TV Viewer**
- **Team Manager**

## Connections

- Match Operator → Scoring Dashboard: scores match (evidence: `README.md`)
- Scoring Dashboard → HTTP and Socket Server: sends state (evidence: `README.md`)
- HTTP and Socket Server → Scoring Dashboard: broadcasts updates (evidence: `README.md`)
- HTTP and Socket Server → PostgreSQL: persists state (evidence: `server.js`)
- HTTP and Socket Server → Broadcast Renderer: broadcasts state (evidence: `README.md`)
- Broadcast Renderer → TV Viewer: renders graphics (evidence: `README.md`)
- TV Viewer → Broadcast Overlays: views overlays (evidence: `README.md`)
- Team Manager → Roster Management: manages rosters (evidence: `README.md`)
- Team Manager → Teams Page: manages rosters (evidence: `README.md`)
- Teams Page → HTTP and Socket Server: calls team APIs (evidence: `extra/client/src/app/teams/page.js`)
- HTTP and Socket Server → PostgreSQL: stores rosters (evidence: `server.js`)
- Match Operator → Admin Page: configures match (evidence: `README.md`)
- Admin Page → Scoring State: uses scoring state (evidence: `extra/client/src/app/admin/page.js`)
- Admin Page → Input Validation: validates inputs (evidence: `extra/client/src/app/admin/page.js`)
- Admin Page → Broadcast Overlays: renders overlays (evidence: `extra/client/src/app/admin/page.js`)
- Scoring State → Socket Provider: uses socket (evidence: `extra/client/src/hooks/useMatchState.js`)
- Teams Page → Socket Provider: uses socket (evidence: `extra/client/src/app/teams/page.js`)
- Socket Provider → HTTP and Socket Server: connects by Socket.IO
- Admin Page → Socket Provider: uses socket (evidence: `extra/client/src/app/admin/page.js`)
