# mahmoudjd/mjd-footballscout architecture

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

- Interactive diagram: https://gitdiagram.com/mahmoudjd/mjd-footballscout
- Repository: https://github.com/mahmoudjd/mjd-footballscout

## Overview

MJD Football Scout is a cross-platform football scouting and recruitment workspace. Scouts discover and inspect players, compare candidates, organize watchlists and scouting reports, then plan squads and advance recruitment decisions. The Next.js and Expo clients use a shared Express API; the API persists user and scouting data in MongoDB and can collect player data from public sources. The graph preserves README-documented premium and account capabilities, but sampled evidence for internal wiring is limited, so uncertain connections are omitted.

Main entry points: [`web-app/src/app/page.tsx`](https://github.com/mahmoudjd/mjd-footballscout/blob/main/web-app/src/app/page.tsx) (Web workspace), [`server/src/modules/players/player.model.ts`](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/player.model.ts) (Player database), [`server/src/index.ts`](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/index.ts) (Express REST API), [`server/src/modules/shadow-teams/shadow-teams.controller.ts`](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-teams.controller.ts) (Shadow teams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Scout clients"]
  node_web["Web workspace<br/>[page.tsx]"]
  node_mobile["Mobile workspace<br/>[apiServices.ts]"]
end

subgraph group_identity["Accounts and security"]
  node_auth["Authentication<br/>[auth.router.ts]"]
  node_user_data[("User accounts<br/>[user.model.ts]")]
  node_email["Email notifications<br/>[email.service.ts]"]
end

subgraph group_intelligence["Player intelligence"]
  node_player_data[("Player database<br/>[player.model.ts]")]
  node_player_ops["Player discovery"]
  node_player_queries["Filters and similarity"]
  node_scraping["Public-source extraction<br/>[scrapingData.ts]"]
  node_reports["Scouting reports"]
end

subgraph group_planning["Recruitment planning"]
  node_watchlists[("Watchlists")]
  node_shadow["Shadow teams"]
  node_formations["Formation planning"]
  node_team_analytics["Squad analytics"]
  node_recruitment["Recruitment workspace"]
end

subgraph group_platform["API and persistence"]
  node_api["Express REST API<br/>[index.ts]"]
  node_mongo[("MongoDB")]
  node_sources["Public player sources"]
  node_stripe["Stripe premium"]
end

node_scout(("Scout"))

node_scout -->|"uses"| node_web
node_scout -->|"uses"| node_mobile
node_web -->|"requests"| node_api
node_mobile -->|"requests"| node_api
node_api -->|"persists data"| node_mongo
node_api -->|"collects data"| node_sources
node_api -.->|"billing integration"| node_stripe
node_auth -->|"reads and writes"| node_user_data
node_auth -->|"sends notices"| node_email
node_player_ops -->|"reads and writes"| node_player_data
node_player_ops -->|"extracts players"| node_scraping
node_player_queries -->|"uses price parsing"| node_player_ops
node_player_queries -.->|"queries players"| node_player_data
node_reports -.->|"records reports"| node_player_data
node_watchlists -->|"loads players"| node_player_data
node_shadow -->|"loads players"| node_player_data
node_shadow -->|"gets slots"| node_formations
node_shadow -->|"analyzes squad"| node_team_analytics
node_recruitment -->|"checks players"| node_player_data
node_web -.->|"shortlists"| node_watchlists
node_web -.->|"evaluates players"| node_reports
node_web -.->|"plans squads"| node_shadow
node_web -.->|"manages pipeline"| node_recruitment

click node_web "https://github.com/mahmoudjd/mjd-footballscout/blob/main/web-app/src/app/page.tsx"
click node_mobile "https://github.com/mahmoudjd/mjd-footballscout/blob/main/mobile-app/src/apiServices.ts"
click node_auth "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/auth/auth.router.ts"
click node_user_data "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/auth/user.model.ts"
click node_email "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/notifications/email.service.ts"
click node_player_data "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/player.model.ts"
click node_player_ops "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/players.controller.ts"
click node_player_queries "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/player-query.controller.ts"
click node_scraping "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/scraper/scrapingData.ts"
click node_reports "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/scouting.controller.ts"
click node_watchlists "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/watchlists/watchlists.controller.ts"
click node_shadow "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-teams.controller.ts"
click node_formations "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-team-formations.ts"
click node_team_analytics "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-team-analytics.ts"
click node_recruitment "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/recruitment/recruitment.controller.ts"
click node_api "https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/index.ts"

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_web,node_mobile toneBlue
class node_auth,node_user_data,node_email toneAmber
class node_player_data,node_player_ops,node_player_queries,node_scraping,node_reports toneMint
class node_watchlists,node_shadow,node_formations,node_team_analytics,node_recruitment toneRose
class node_api,node_mongo,node_sources,node_stripe,node_scout toneIndigo
```

## Components

### Scout clients

- [Web workspace](https://github.com/mahmoudjd/mjd-footballscout/blob/main/web-app/src/app/page.tsx): `web-app/src/app/page.tsx`
- [Mobile workspace](https://github.com/mahmoudjd/mjd-footballscout/blob/main/mobile-app/src/apiServices.ts): `mobile-app/src/apiServices.ts`

### Accounts and security

- [Authentication](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/auth/auth.router.ts): `server/src/modules/auth/auth.router.ts`
- [User accounts](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/auth/user.model.ts): `server/src/modules/auth/user.model.ts`
- [Email notifications](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/notifications/email.service.ts): `server/src/modules/notifications/email.service.ts`

### Player intelligence

- [Player database](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/player.model.ts): `server/src/modules/players/player.model.ts`
- [Player discovery](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/players.controller.ts): `server/src/modules/players/players.controller.ts`
- [Filters and similarity](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/player-query.controller.ts): `server/src/modules/players/player-query.controller.ts`
- [Public-source extraction](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/scraper/scrapingData.ts): `server/src/scraper/scrapingData.ts`
- [Scouting reports](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/players/scouting.controller.ts): `server/src/modules/players/scouting.controller.ts`

### Recruitment planning

- [Watchlists](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/watchlists/watchlists.controller.ts): `server/src/modules/watchlists/watchlists.controller.ts`
- [Shadow teams](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-teams.controller.ts): `server/src/modules/shadow-teams/shadow-teams.controller.ts`
- [Formation planning](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-team-formations.ts): `server/src/modules/shadow-teams/shadow-team-formations.ts`
- [Squad analytics](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/shadow-teams/shadow-team-analytics.ts): `server/src/modules/shadow-teams/shadow-team-analytics.ts`
- [Recruitment workspace](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/modules/recruitment/recruitment.controller.ts): `server/src/modules/recruitment/recruitment.controller.ts`

### API and persistence

- [Express REST API](https://github.com/mahmoudjd/mjd-footballscout/blob/main/server/src/index.ts): `server/src/index.ts`
- **MongoDB**
- **Public player sources**
- **Stripe premium**

### Other components

- **Scout**

## Connections

- Scout → Web workspace: uses (evidence: `README.md`)
- Scout → Mobile workspace: uses (evidence: `README.md`)
- Web workspace → Express REST API: requests (evidence: `README.md`)
- Mobile workspace → Express REST API: requests (evidence: `README.md`)
- Express REST API → MongoDB: persists data (evidence: `README.md`)
- Express REST API → Public player sources: collects data (evidence: `README.md`)
- Express REST API → Stripe premium: billing integration (evidence: `README.md`)
- Authentication → User accounts: reads and writes (evidence: `server/src/modules/auth/auth.router.ts`)
- Authentication → Email notifications: sends notices (evidence: `server/src/modules/auth/auth.router.ts`)
- Player discovery → Player database: reads and writes (evidence: `server/src/modules/players/players.controller.ts`)
- Player discovery → Public-source extraction: extracts players (evidence: `server/src/modules/players/players.controller.ts`)
- Filters and similarity → Player discovery: uses price parsing (evidence: `server/src/modules/players/player-query.controller.ts`)
- Filters and similarity → Player database: queries players
- Scouting reports → Player database: records reports
- Watchlists → Player database: loads players (evidence: `server/src/modules/watchlists/watchlists.controller.ts`)
- Shadow teams → Player database: loads players (evidence: `server/src/modules/shadow-teams/shadow-teams.controller.ts`)
- Shadow teams → Formation planning: gets slots (evidence: `server/src/modules/shadow-teams/shadow-teams.controller.ts`)
- Shadow teams → Squad analytics: analyzes squad (evidence: `server/src/modules/shadow-teams/shadow-teams.controller.ts`)
- Recruitment workspace → Player database: checks players (evidence: `server/src/modules/recruitment/recruitment.controller.ts`)
- Web workspace → Watchlists: shortlists
- Web workspace → Scouting reports: evaluates players
- Web workspace → Shadow teams: plans squads
- Web workspace → Recruitment workspace: manages pipeline
