# kinsara007/mafia-frontend-main architecture

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

- Interactive diagram: https://gitdiagram.com/kinsara007/mafia-frontend-main
- Repository: https://github.com/kinsara007/mafia-frontend-main

## Overview

Mafia is a real-time multiplayer party game. Players authenticate, create or join a room, wait in its lobby, then play alternating night-action and day-discussion/voting phases until a winner is shown. `GameApp` coordinates screen state, API operations, persisted session/room data, and game updates. The README is only the default Next.js template; feature names and wiring here come from the supplied tree and sampled source. Several screens and the page entry are unsampled, so their internal behavior and exact event wiring are not inferred.

Main entry points: [`src/lib/game-app.tsx`](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/game-app.tsx) (Game coordinator), [`src/screens/LobbyScreen.tsx`](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/LobbyScreen.tsx) (Room lobby), [`src/screens/DayPhaseScreen.tsx`](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/DayPhaseScreen.tsx) (Day discussion and vote), [`src/components/ActionPanel.tsx`](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ActionPanel.tsx) (Night action selector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Game experience"]
  node_page["App page<br/>[page.tsx]"]
  node_auth["Sign in / register<br/>[AuthScreen.tsx]"]
  node_home["Home and room entry<br/>[HomeScreen.tsx]"]
  node_lobby["Room lobby<br/>[LobbyScreen.tsx]"]
  node_role["Role reveal"]
  node_night["Night actions"]
  node_nightresult["Night outcome"]
  node_day["Day discussion and vote<br/>[DayPhaseScreen.tsx]"]
  node_dayresult["Day outcome"]
  node_gameover["Winner and role reveal<br/>[GameOverScreen.tsx]"]
end

subgraph group_coordination["Client coordination"]
  node_app["Game coordinator<br/>[game-app.tsx]"]
  node_types["Game and domain types<br/>[types.ts]"]
end

subgraph group_services["Persistence and services"]
  node_api["HTTP API client<br/>[api.ts]"]
  node_storage["Session and room storage<br/>[storage.ts]"]
end

subgraph group_shared["Shared interface"]
  node_actionpanel["Night action selector<br/>[ActionPanel.tsx]"]
  node_chat["Discussion chat<br/>[ChatPanel.tsx]"]
  node_tally["Vote tally<br/>[VoteTally.tsx]"]
  node_playercard["Player card<br/>[PlayerCard.tsx]"]
  node_navbar["Navigation bar<br/>[NavBar.tsx]"]
  node_phaseheader["Phase header<br/>[PhaseHeader.tsx]"]
  node_connection["Connection status"]
  node_icons["Icons<br/>[icons.tsx]"]
end

node_player(("Player"))
node_backend["Game backend"]
node_browserstore[("Browser local storage")]

node_player -->|"opens game"| node_page
node_page -->|"renders"| node_app
node_app -->|"shows auth"| node_auth
node_app -->|"shows home"| node_home
node_app -->|"shows lobby"| node_lobby
node_app -->|"shows role"| node_role
node_app -->|"shows night"| node_night
node_app -->|"shows outcome"| node_nightresult
node_app -->|"shows day"| node_day
node_app -->|"shows outcome"| node_dayresult
node_app -->|"shows winner"| node_gameover
node_auth -->|"submits credentials"| node_app
node_lobby -->|"invokes lobby actions"| node_app
node_night -->|"renders selector"| node_actionpanel
node_actionpanel -->|"submits target"| node_app
node_day -->|"renders discussion"| node_chat
node_day -->|"renders votes"| node_tally
node_chat -->|"sends message"| node_app
node_app -->|"requests game operations"| node_api
node_api -->|"sends HTTP requests"| node_backend
node_backend -->|"returns responses"| node_api
node_app -.->|"exchanges game updates"| node_backend
node_app -->|"loads and persists state"| node_storage
node_storage -->|"reads and writes"| node_browserstore
node_app -->|"uses domain definitions"| node_types
node_app -->|"renders navigation"| node_navbar
node_app -->|"renders phase status"| node_phaseheader
node_app -->|"renders connection state"| node_connection
node_lobby -->|"renders players"| node_playercard
node_actionpanel -->|"uses icons"| node_icons
node_chat -->|"uses icons"| node_icons

click node_page "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/app/page.tsx"
click node_auth "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/AuthScreen.tsx"
click node_home "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/HomeScreen.tsx"
click node_lobby "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/LobbyScreen.tsx"
click node_role "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/RoleRevealScreen.tsx"
click node_night "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/NightPhaseScreen.tsx"
click node_nightresult "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/NightResultScreen.tsx"
click node_day "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/DayPhaseScreen.tsx"
click node_dayresult "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/DayResultScreen.tsx"
click node_gameover "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/GameOverScreen.tsx"
click node_app "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/game-app.tsx"
click node_types "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/types.ts"
click node_api "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/api.ts"
click node_storage "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/storage.ts"
click node_actionpanel "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ActionPanel.tsx"
click node_chat "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ChatPanel.tsx"
click node_tally "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/VoteTally.tsx"
click node_playercard "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/PlayerCard.tsx"
click node_navbar "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/NavBar.tsx"
click node_phaseheader "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/PhaseHeader.tsx"
click node_connection "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ConnectionBadge.tsx"
click node_icons "https://github.com/kinsara007/mafia-frontend-main/blob/main/src/icons.tsx"

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_page,node_auth,node_home,node_lobby,node_role,node_night,node_nightresult,node_day,node_dayresult,node_gameover toneBlue
class node_app,node_types,node_browserstore toneAmber
class node_api,node_storage toneMint
class node_actionpanel,node_chat,node_tally,node_playercard,node_navbar,node_phaseheader,node_connection,node_icons toneRose
class node_player,node_backend toneIndigo
```

## Components

### Game experience

- [App page](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Sign in / register](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/AuthScreen.tsx): `src/screens/AuthScreen.tsx`
- [Home and room entry](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/HomeScreen.tsx): `src/screens/HomeScreen.tsx`
- [Room lobby](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/LobbyScreen.tsx): `src/screens/LobbyScreen.tsx`
- [Role reveal](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/RoleRevealScreen.tsx): `src/screens/RoleRevealScreen.tsx`
- [Night actions](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/NightPhaseScreen.tsx): `src/screens/NightPhaseScreen.tsx`
- [Night outcome](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/NightResultScreen.tsx): `src/screens/NightResultScreen.tsx`
- [Day discussion and vote](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/DayPhaseScreen.tsx): `src/screens/DayPhaseScreen.tsx`
- [Day outcome](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/DayResultScreen.tsx): `src/screens/DayResultScreen.tsx`
- [Winner and role reveal](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/screens/GameOverScreen.tsx): `src/screens/GameOverScreen.tsx`

### Client coordination

- [Game coordinator](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/game-app.tsx): `src/lib/game-app.tsx`
- [Game and domain types](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/types.ts): `src/lib/types.ts`

### Persistence and services

- [HTTP API client](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/api.ts): `src/lib/api.ts`
- [Session and room storage](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/lib/storage.ts): `src/lib/storage.ts`

### Shared interface

- [Night action selector](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ActionPanel.tsx): `src/components/ActionPanel.tsx`
- [Discussion chat](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ChatPanel.tsx): `src/components/ChatPanel.tsx`
- [Vote tally](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/VoteTally.tsx): `src/components/VoteTally.tsx`
- [Player card](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/PlayerCard.tsx): `src/components/PlayerCard.tsx`
- [Navigation bar](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/NavBar.tsx): `src/components/NavBar.tsx`
- [Phase header](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/PhaseHeader.tsx): `src/components/PhaseHeader.tsx`
- [Connection status](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/components/ConnectionBadge.tsx): `src/components/ConnectionBadge.tsx`
- [Icons](https://github.com/kinsara007/mafia-frontend-main/blob/main/src/icons.tsx): `src/icons.tsx`

### Other components

- **Player**
- **Game backend**
- **Browser local storage**

## Connections

- Player → App page: opens game
- App page → Game coordinator: renders
- Game coordinator → Sign in / register: shows auth
- Game coordinator → Home and room entry: shows home
- Game coordinator → Room lobby: shows lobby
- Game coordinator → Role reveal: shows role
- Game coordinator → Night actions: shows night
- Game coordinator → Night outcome: shows outcome
- Game coordinator → Day discussion and vote: shows day
- Game coordinator → Day outcome: shows outcome
- Game coordinator → Winner and role reveal: shows winner
- Sign in / register → Game coordinator: submits credentials
- Room lobby → Game coordinator: invokes lobby actions
- Night actions → Night action selector: renders selector
- Night action selector → Game coordinator: submits target
- Day discussion and vote → Discussion chat: renders discussion
- Day discussion and vote → Vote tally: renders votes
- Discussion chat → Game coordinator: sends message
- Game coordinator → HTTP API client: requests game operations
- HTTP API client → Game backend: sends HTTP requests
- Game backend → HTTP API client: returns responses
- Game coordinator → Game backend: exchanges game updates
- Game coordinator → Session and room storage: loads and persists state
- Session and room storage → Browser local storage: reads and writes
- Game coordinator → Game and domain types: uses domain definitions
- Game coordinator → Navigation bar: renders navigation
- Game coordinator → Phase header: renders phase status
- Game coordinator → Connection status: renders connection state
- Room lobby → Player card: renders players
- Night action selector → Icons: uses icons
- Discussion chat → Icons: uses icons