# therageon/goalytics architecture

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

- Interactive diagram: https://gitdiagram.com/therageon/goalytics
- Repository: https://github.com/therageon/goalytics

## Overview

Goalytics lets users register, browse World Cup fixtures, submit score predictions, earn points when matches finish, and compete on a leaderboard; admins manage fixtures, users, and withdrawals. The frontend is a Next.js app and the backend exposes Express APIs backed by MongoDB models. The graph follows documented routes and sampled service calls. Frontend-to-API wiring and several unsampled page interactions are not shown, so those links are omitted.

Main entry points: [`backend/server.js`](https://github.com/therageon/goalytics/blob/main/backend/server.js) (Express server), [`backend/middleware/authMiddleware.js`](https://github.com/therageon/goalytics/blob/main/backend/middleware/authMiddleware.js) (JWT guard), [`backend/model/User.js`](https://github.com/therageon/goalytics/blob/main/backend/model/User.js) (User records), [`backend/controllers/statsController.js`](https://github.com/therageon/goalytics/blob/main/backend/controllers/statsController.js) (Dashboard stats)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_user_ui["Player pages"]
  node_admin_ui["Admin pages"]
  node_auth_ui["Sign-in pages<br/>[page.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_server["Express server<br/>[server.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_match_routes["Match routes<br/>[matchRoutes.js]"]
  node_prediction_routes["Prediction routes"]
  node_stats_routes["Stats routes<br/>[statsRoutes.js]"]
  node_user_routes["User routes<br/>[userRoutes.js]"]
  node_withdraw_routes["Withdrawal routes<br/>[withdrawRoutes.js]"]
  node_auth_guard["JWT guard<br/>[authMiddleware.js]"]
  node_admin_guard["Admin guard<br/>[adminMiddleware.js]"]
end

subgraph group_domain["Prediction domain"]
  node_match_logic["Fixture management<br/>[matchController.js]"]
  node_prediction_logic["Prediction scoring"]
  node_match_service["Match service<br/>[matchService.js]"]
  node_stats_logic["Dashboard stats<br/>[statsController.js]"]
end

subgraph group_account["Accounts and payouts"]
  node_auth_logic["Authentication<br/>[authService.js]"]
  node_withdraw_logic["Withdrawals<br/>[withdrawService.js]"]
  node_user_logic["User management<br/>[userService.js]"]
end

subgraph group_storage["Persistent data"]
  node_user_model[("User records<br/>[User.js]")]
  node_match_model[("Match records<br/>[Match.js]")]
  node_prediction_model[("Prediction records<br/>[Prediction.js]")]
  node_withdraw_model[("Withdrawal records<br/>[Withdraw.js]")]
end

node_user(("Players"))
node_admin(("Administrators"))
node_mongo[("MongoDB")]

node_user -->|"uses"| node_user_ui
node_admin -->|"manages"| node_admin_ui
node_user -->|"registers"| node_auth_ui
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_match_routes
node_server -->|"mounts"| node_prediction_routes
node_server -->|"mounts"| node_stats_routes
node_server -->|"mounts"| node_user_routes
node_server -->|"mounts"| node_withdraw_routes
node_auth_routes -->|"protects password change"| node_auth_guard
node_auth_routes -->|"routes to"| node_auth_logic
node_match_routes -->|"routes to"| node_match_logic
node_match_routes -->|"protects admin actions"| node_auth_guard
node_match_routes -->|"guards admin actions"| node_admin_guard
node_prediction_routes -->|"protects routes"| node_auth_guard
node_prediction_routes -->|"routes to"| node_prediction_logic
node_stats_routes -->|"routes to"| node_stats_logic
node_stats_routes -->|"protects routes"| node_auth_guard
node_stats_routes -->|"guards admin stats"| node_admin_guard
node_withdraw_routes -->|"routes to"| node_withdraw_logic
node_withdraw_routes -->|"protects user routes"| node_auth_guard
node_withdraw_routes -->|"guards admin routes"| node_admin_guard
node_user_routes -->|"routes to"| node_user_logic
node_auth_guard -->|"loads user"| node_user_model
node_match_logic -->|"manages fixtures through"| node_match_service
node_match_logic -->|"evaluates finished matches"| node_prediction_logic
node_match_service -->|"queries"| node_match_model
node_match_service -->|"deletes related predictions"| node_prediction_model
node_prediction_logic -->|"checks match state"| node_match_model
node_prediction_logic -->|"creates and scores"| node_prediction_model
node_prediction_logic -->|"updates points"| node_user_model
node_stats_logic -->|"queries"| node_user_model
node_stats_logic -->|"queries"| node_match_model
node_stats_logic -->|"queries"| node_prediction_model
node_stats_logic -->|"counts pending requests"| node_withdraw_model
node_auth_logic -->|"authenticates and stores"| node_user_model
node_withdraw_logic -->|"reads and updates"| node_user_model
node_withdraw_logic -->|"manages requests"| node_withdraw_model
node_user_logic -->|"queries"| node_user_model
node_user_logic -->|"queries predictions"| node_prediction_model

click node_user_ui "https://github.com/therageon/goalytics/tree/main/frontend/app/user"
click node_admin_ui "https://github.com/therageon/goalytics/tree/main/frontend/app/admin"
click node_auth_ui "https://github.com/therageon/goalytics/blob/main/frontend/app/login/page.jsx"
click node_api_client "https://github.com/therageon/goalytics/blob/main/frontend/lib/api.js"
click node_server "https://github.com/therageon/goalytics/blob/main/backend/server.js"
click node_auth_routes "https://github.com/therageon/goalytics/blob/main/backend/routes/authRoutes.js"
click node_match_routes "https://github.com/therageon/goalytics/blob/main/backend/routes/matchRoutes.js"
click node_prediction_routes "https://github.com/therageon/goalytics/blob/main/backend/routes/predictionRoutes.js"
click node_stats_routes "https://github.com/therageon/goalytics/blob/main/backend/routes/statsRoutes.js"
click node_user_routes "https://github.com/therageon/goalytics/blob/main/backend/routes/userRoutes.js"
click node_withdraw_routes "https://github.com/therageon/goalytics/blob/main/backend/routes/withdrawRoutes.js"
click node_auth_guard "https://github.com/therageon/goalytics/blob/main/backend/middleware/authMiddleware.js"
click node_admin_guard "https://github.com/therageon/goalytics/blob/main/backend/middleware/adminMiddleware.js"
click node_match_logic "https://github.com/therageon/goalytics/blob/main/backend/controllers/matchController.js"
click node_prediction_logic "https://github.com/therageon/goalytics/blob/main/backend/services/predictionService.js"
click node_match_service "https://github.com/therageon/goalytics/blob/main/backend/services/matchService.js"
click node_stats_logic "https://github.com/therageon/goalytics/blob/main/backend/controllers/statsController.js"
click node_auth_logic "https://github.com/therageon/goalytics/blob/main/backend/services/authService.js"
click node_withdraw_logic "https://github.com/therageon/goalytics/blob/main/backend/services/withdrawService.js"
click node_user_logic "https://github.com/therageon/goalytics/blob/main/backend/services/userService.js"
click node_user_model "https://github.com/therageon/goalytics/blob/main/backend/model/User.js"
click node_match_model "https://github.com/therageon/goalytics/blob/main/backend/model/Match.js"
click node_prediction_model "https://github.com/therageon/goalytics/blob/main/backend/model/Prediction.js"
click node_withdraw_model "https://github.com/therageon/goalytics/blob/main/backend/model/Withdraw.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_user_ui,node_admin_ui,node_auth_ui,node_api_client toneBlue
class node_server,node_auth_routes,node_match_routes,node_prediction_routes,node_stats_routes,node_user_routes,node_withdraw_routes,node_auth_guard,node_admin_guard,node_mongo toneAmber
class node_match_logic,node_prediction_logic,node_match_service,node_stats_logic toneMint
class node_auth_logic,node_withdraw_logic,node_user_logic toneRose
class node_user_model,node_match_model,node_prediction_model,node_withdraw_model,node_user,node_admin toneIndigo
```

## Components

### Web experience

- [Player pages](https://github.com/therageon/goalytics/tree/main/frontend/app/user): `frontend/app/user`
- [Admin pages](https://github.com/therageon/goalytics/tree/main/frontend/app/admin): `frontend/app/admin`
- [Sign-in pages](https://github.com/therageon/goalytics/blob/main/frontend/app/login/page.jsx): `frontend/app/login/page.jsx`
- [API client](https://github.com/therageon/goalytics/blob/main/frontend/lib/api.js): `frontend/lib/api.js`

### API and access

- [Express server](https://github.com/therageon/goalytics/blob/main/backend/server.js): `backend/server.js`
- [Auth routes](https://github.com/therageon/goalytics/blob/main/backend/routes/authRoutes.js): `backend/routes/authRoutes.js`
- [Match routes](https://github.com/therageon/goalytics/blob/main/backend/routes/matchRoutes.js): `backend/routes/matchRoutes.js`
- [Prediction routes](https://github.com/therageon/goalytics/blob/main/backend/routes/predictionRoutes.js): `backend/routes/predictionRoutes.js`
- [Stats routes](https://github.com/therageon/goalytics/blob/main/backend/routes/statsRoutes.js): `backend/routes/statsRoutes.js`
- [User routes](https://github.com/therageon/goalytics/blob/main/backend/routes/userRoutes.js): `backend/routes/userRoutes.js`
- [Withdrawal routes](https://github.com/therageon/goalytics/blob/main/backend/routes/withdrawRoutes.js): `backend/routes/withdrawRoutes.js`
- [JWT guard](https://github.com/therageon/goalytics/blob/main/backend/middleware/authMiddleware.js): `backend/middleware/authMiddleware.js`
- [Admin guard](https://github.com/therageon/goalytics/blob/main/backend/middleware/adminMiddleware.js): `backend/middleware/adminMiddleware.js`

### Prediction domain

- [Fixture management](https://github.com/therageon/goalytics/blob/main/backend/controllers/matchController.js): `backend/controllers/matchController.js`
- [Prediction scoring](https://github.com/therageon/goalytics/blob/main/backend/services/predictionService.js): `backend/services/predictionService.js`
- [Match service](https://github.com/therageon/goalytics/blob/main/backend/services/matchService.js): `backend/services/matchService.js`
- [Dashboard stats](https://github.com/therageon/goalytics/blob/main/backend/controllers/statsController.js): `backend/controllers/statsController.js`

### Accounts and payouts

- [Authentication](https://github.com/therageon/goalytics/blob/main/backend/services/authService.js): `backend/services/authService.js`
- [Withdrawals](https://github.com/therageon/goalytics/blob/main/backend/services/withdrawService.js): `backend/services/withdrawService.js`
- [User management](https://github.com/therageon/goalytics/blob/main/backend/services/userService.js): `backend/services/userService.js`

### Persistent data

- [User records](https://github.com/therageon/goalytics/blob/main/backend/model/User.js): `backend/model/User.js`
- [Match records](https://github.com/therageon/goalytics/blob/main/backend/model/Match.js): `backend/model/Match.js`
- [Prediction records](https://github.com/therageon/goalytics/blob/main/backend/model/Prediction.js): `backend/model/Prediction.js`
- [Withdrawal records](https://github.com/therageon/goalytics/blob/main/backend/model/Withdraw.js): `backend/model/Withdraw.js`

### Other components

- **Players**
- **Administrators**
- **MongoDB**

## Connections

- Players → Player pages: uses
- Administrators → Admin pages: manages
- Players → Sign-in pages: registers
- Express server → Auth routes: mounts (evidence: `backend/server.js`)
- Express server → Match routes: mounts (evidence: `backend/server.js`)
- Express server → Prediction routes: mounts (evidence: `backend/server.js`)
- Express server → Stats routes: mounts (evidence: `backend/server.js`)
- Express server → User routes: mounts (evidence: `backend/server.js`)
- Express server → Withdrawal routes: mounts (evidence: `backend/server.js`)
- Auth routes → JWT guard: protects password change (evidence: `backend/routes/authRoutes.js`)
- Auth routes → Authentication: routes to (evidence: `backend/routes/authRoutes.js`)
- Match routes → Fixture management: routes to (evidence: `backend/routes/matchRoutes.js`)
- Match routes → JWT guard: protects admin actions (evidence: `backend/routes/matchRoutes.js`)
- Match routes → Admin guard: guards admin actions (evidence: `backend/routes/matchRoutes.js`)
- Prediction routes → JWT guard: protects routes (evidence: `backend/routes/predictionRoutes.js`)
- Prediction routes → Prediction scoring: routes to (evidence: `backend/routes/predictionRoutes.js`)
- Stats routes → Dashboard stats: routes to (evidence: `backend/routes/statsRoutes.js`)
- Stats routes → JWT guard: protects routes (evidence: `backend/routes/statsRoutes.js`)
- Stats routes → Admin guard: guards admin stats (evidence: `backend/routes/statsRoutes.js`)
- Withdrawal routes → Withdrawals: routes to (evidence: `backend/routes/withdrawRoutes.js`)
- Withdrawal routes → JWT guard: protects user routes (evidence: `backend/routes/withdrawRoutes.js`)
- Withdrawal routes → Admin guard: guards admin routes (evidence: `backend/routes/withdrawRoutes.js`)
- User routes → User management: routes to (evidence: `backend/routes/userRoutes.js`)
- JWT guard → User records: loads user (evidence: `backend/middleware/authMiddleware.js`)
- Fixture management → Match service: manages fixtures through (evidence: `backend/controllers/matchController.js`)
- Fixture management → Prediction scoring: evaluates finished matches (evidence: `backend/controllers/matchController.js`)
- Match service → Match records: queries (evidence: `backend/services/matchService.js`)
- Match service → Prediction records: deletes related predictions (evidence: `backend/services/matchService.js`)
- Prediction scoring → Match records: checks match state (evidence: `backend/services/predictionService.js`)
- Prediction scoring → Prediction records: creates and scores (evidence: `backend/services/predictionService.js`)
- Prediction scoring → User records: updates points (evidence: `backend/services/predictionService.js`)
- Dashboard stats → User records: queries (evidence: `backend/controllers/statsController.js`)
- Dashboard stats → Match records: queries (evidence: `backend/controllers/statsController.js`)
- Dashboard stats → Prediction records: queries (evidence: `backend/controllers/statsController.js`)
- Dashboard stats → Withdrawal records: counts pending requests (evidence: `backend/controllers/statsController.js`)
- Authentication → User records: authenticates and stores (evidence: `backend/services/authService.js`)
- Withdrawals → User records: reads and updates (evidence: `backend/services/withdrawService.js`)
- Withdrawals → Withdrawal records: manages requests (evidence: `backend/services/withdrawService.js`)
- User management → User records: queries (evidence: `backend/services/userService.js`)
- User management → Prediction records: queries predictions (evidence: `backend/services/userService.js`)
