# japegomez/jugamus architecture

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

- Interactive diagram: https://gitdiagram.com/japegomez/jugamus
- Repository: https://github.com/japegomez/jugamus

## Overview

jugaMUS is a cross-platform mus community app for finding opponents and organizing matches, tournaments, and leagues; it does not implement the mus game itself. The main workflow is to discover or create an event, coordinate participation, record and validate results, and view standings or player statistics. Routes and React Query hooks form the client-facing layer; domain services use Supabase for backend operations. The README documents additional moderation, analytics, notifications, and guest scoreboard capabilities. Some feature modules were not sampled, so their internal wiring is left unspecified.

Main entry points: [`src/lib/supabase.ts`](https://github.com/japegomez/jugamus/blob/main/src/lib/supabase.ts) (Supabase backend), [`src/services/matches.service.ts`](https://github.com/japegomez/jugamus/blob/main/src/services/matches.service.ts) (Match coordination), [`src/app`](https://github.com/japegomez/jugamus/tree/main/src/app) (App routes), [`src/hooks/useAuth.ts`](https://github.com/japegomez/jugamus/blob/main/src/hooks/useAuth.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["App and identity"]
  node_routes["App routes"]
  node_auth["Authentication<br/>[useAuth.ts]"]
  node_authstore["Auth storage<br/>[authStorage.ts]"]
end

subgraph group_play["Matches and play"]
  node_explore["Discover events<br/>[index.tsx]"]
  node_matchstate["Match queries<br/>[useMatches.ts]"]
  node_matches["Match coordination<br/>[matches.service.ts]"]
  node_results["Result validation<br/>[results.service.ts]"]
  node_scoreboard["Live scoreboard"]
  node_scoreboardui["Scoreboard view"]
  node_guest["Guest scoreboard"]
end

subgraph group_community["Leagues and community"]
  node_tournaments["Tournament management"]
  node_leagues["League management<br/>[leagues.service.ts]"]
  node_friends["Friend connections<br/>[useFriends.ts]"]
  node_profiles["Profiles"]
  node_stats["Player statistics<br/>[stats.service.ts]"]
end

subgraph group_platform["Backend and insights"]
  node_admin["Moderation and reports<br/>[admin.service.ts]"]
  node_notifications["Push notifications<br/>[index.ts]"]
  node_analytics["Product analytics<br/>[analytics.ts]"]
  node_supabase[("Supabase backend<br/>[supabase.ts]")]
end

node_player(("Player"))

node_player -->|"uses"| node_routes
node_routes -.->|"authenticates"| node_auth
node_routes -->|"discovers"| node_explore
node_explore -->|"loads events"| node_matchstate
node_explore -->|"queries"| node_matches
node_matchstate -->|"calls"| node_matches
node_matches -->|"maps errors"| node_results
node_scoreboardui -->|"uses"| node_scoreboard
node_guest -.->|"offers access"| node_scoreboard
node_matches -->|"reads and writes"| node_supabase
node_results -->|"reads and writes"| node_supabase
node_tournaments -->|"reads and writes"| node_supabase
node_leagues -->|"reads and writes"| node_supabase
node_auth -->|"uses auth"| node_supabase
node_auth -.->|"persists session"| node_authstore
node_player -.->|"organizes tournaments"| node_tournaments
node_player -.->|"organizes leagues"| node_leagues
node_player -.->|"connects"| node_friends
node_player -.->|"views profiles"| node_profiles
node_player -.->|"views stats"| node_stats
node_player -.->|"reports issues"| node_admin
node_notifications -.->|"processes events"| node_supabase
node_matches -->|"tracks events"| node_analytics

click node_routes "https://github.com/japegomez/jugamus/tree/main/src/app"
click node_auth "https://github.com/japegomez/jugamus/blob/main/src/hooks/useAuth.ts"
click node_authstore "https://github.com/japegomez/jugamus/blob/main/src/lib/authStorage.ts"
click node_explore "https://github.com/japegomez/jugamus/blob/main/src/app/(tabs)/explore/index.tsx"
click node_matchstate "https://github.com/japegomez/jugamus/blob/main/src/hooks/useMatches.ts"
click node_matches "https://github.com/japegomez/jugamus/blob/main/src/services/matches.service.ts"
click node_results "https://github.com/japegomez/jugamus/blob/main/src/services/results.service.ts"
click node_scoreboard "https://github.com/japegomez/jugamus/blob/main/src/hooks/useLiveScoreboard.ts"
click node_scoreboardui "https://github.com/japegomez/jugamus/blob/main/src/components/matches/ScoreboardBoard.tsx"
click node_guest "https://github.com/japegomez/jugamus/tree/main/src/app/(auth)/guest-scoreboard"
click node_tournaments "https://github.com/japegomez/jugamus/blob/main/src/services/tournaments.service.ts"
click node_leagues "https://github.com/japegomez/jugamus/blob/main/src/services/leagues.service.ts"
click node_friends "https://github.com/japegomez/jugamus/blob/main/src/hooks/useFriends.ts"
click node_profiles "https://github.com/japegomez/jugamus/blob/main/src/services/profiles.service.ts"
click node_stats "https://github.com/japegomez/jugamus/blob/main/src/services/stats.service.ts"
click node_admin "https://github.com/japegomez/jugamus/blob/main/src/services/admin.service.ts"
click node_notifications "https://github.com/japegomez/jugamus/blob/main/supabase/functions/process-notifications/index.ts"
click node_analytics "https://github.com/japegomez/jugamus/blob/main/src/lib/analytics.ts"
click node_supabase "https://github.com/japegomez/jugamus/blob/main/src/lib/supabase.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_routes,node_auth,node_authstore toneBlue
class node_explore,node_matchstate,node_matches,node_results,node_scoreboard,node_scoreboardui,node_guest toneAmber
class node_tournaments,node_leagues,node_friends,node_profiles,node_stats toneMint
class node_admin,node_notifications,node_analytics,node_supabase toneRose
class node_player toneIndigo
```

## Components

### App and identity

- [App routes](https://github.com/japegomez/jugamus/tree/main/src/app): `src/app`
- [Authentication](https://github.com/japegomez/jugamus/blob/main/src/hooks/useAuth.ts): `src/hooks/useAuth.ts`
- [Auth storage](https://github.com/japegomez/jugamus/blob/main/src/lib/authStorage.ts): `src/lib/authStorage.ts`

### Matches and play

- [Discover events](https://github.com/japegomez/jugamus/blob/main/src/app/(tabs)/explore/index.tsx): `src/app/(tabs)/explore/index.tsx`
- [Match queries](https://github.com/japegomez/jugamus/blob/main/src/hooks/useMatches.ts): `src/hooks/useMatches.ts`
- [Match coordination](https://github.com/japegomez/jugamus/blob/main/src/services/matches.service.ts): `src/services/matches.service.ts`
- [Result validation](https://github.com/japegomez/jugamus/blob/main/src/services/results.service.ts): `src/services/results.service.ts`
- [Live scoreboard](https://github.com/japegomez/jugamus/blob/main/src/hooks/useLiveScoreboard.ts): `src/hooks/useLiveScoreboard.ts`
- [Scoreboard view](https://github.com/japegomez/jugamus/blob/main/src/components/matches/ScoreboardBoard.tsx): `src/components/matches/ScoreboardBoard.tsx`
- [Guest scoreboard](https://github.com/japegomez/jugamus/tree/main/src/app/(auth)/guest-scoreboard): `src/app/(auth)/guest-scoreboard`

### Leagues and community

- [Tournament management](https://github.com/japegomez/jugamus/blob/main/src/services/tournaments.service.ts): `src/services/tournaments.service.ts`
- [League management](https://github.com/japegomez/jugamus/blob/main/src/services/leagues.service.ts): `src/services/leagues.service.ts`
- [Friend connections](https://github.com/japegomez/jugamus/blob/main/src/hooks/useFriends.ts): `src/hooks/useFriends.ts`
- [Profiles](https://github.com/japegomez/jugamus/blob/main/src/services/profiles.service.ts): `src/services/profiles.service.ts`
- [Player statistics](https://github.com/japegomez/jugamus/blob/main/src/services/stats.service.ts): `src/services/stats.service.ts`

### Backend and insights

- [Moderation and reports](https://github.com/japegomez/jugamus/blob/main/src/services/admin.service.ts): `src/services/admin.service.ts`
- [Push notifications](https://github.com/japegomez/jugamus/blob/main/supabase/functions/process-notifications/index.ts): `supabase/functions/process-notifications/index.ts`
- [Product analytics](https://github.com/japegomez/jugamus/blob/main/src/lib/analytics.ts): `src/lib/analytics.ts`
- [Supabase backend](https://github.com/japegomez/jugamus/blob/main/src/lib/supabase.ts): `src/lib/supabase.ts`

### Other components

- **Player**

## Connections

- Player → App routes: uses (evidence: `README.md`)
- App routes → Authentication: authenticates (evidence: `README.md`)
- App routes → Discover events: discovers (evidence: `README.md`)
- Discover events → Match queries: loads events (evidence: `src/app/(tabs)/explore/index.tsx`)
- Discover events → Match coordination: queries (evidence: `src/app/(tabs)/explore/index.tsx`)
- Match queries → Match coordination: calls (evidence: `src/hooks/useMatches.ts`)
- Match coordination → Result validation: maps errors (evidence: `src/services/matches.service.ts`)
- Scoreboard view → Live scoreboard: uses (evidence: `src/components/matches/ScoreboardBoard.tsx`)
- Guest scoreboard → Live scoreboard: offers access
- Match coordination → Supabase backend: reads and writes (evidence: `src/services/matches.service.ts`)
- Result validation → Supabase backend: reads and writes (evidence: `src/services/results.service.ts`)
- Tournament management → Supabase backend: reads and writes (evidence: `src/services/tournaments.service.ts`)
- League management → Supabase backend: reads and writes (evidence: `src/services/leagues.service.ts`)
- Authentication → Supabase backend: uses auth (evidence: `src/hooks/useAuth.ts`)
- Authentication → Auth storage: persists session
- Player → Tournament management: organizes tournaments (evidence: `README.md`)
- Player → League management: organizes leagues (evidence: `README.md`)
- Player → Friend connections: connects (evidence: `README.md`)
- Player → Profiles: views profiles (evidence: `README.md`)
- Player → Player statistics: views stats (evidence: `README.md`)
- Player → Moderation and reports: reports issues (evidence: `README.md`)
- Push notifications → Supabase backend: processes events
- Match coordination → Product analytics: tracks events (evidence: `src/services/matches.service.ts`)