# accesswarrior/werewolf architecture

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

- Interactive diagram: https://gitdiagram.com/accesswarrior/werewolf
- Repository: https://github.com/accesswarrior/werewolf

## Overview

Werewolf is a classroom companion: people sign in on their phones, join a room, receive private roles, and use the app to coordinate game state while a human moderator runs the social play. Its main flow moves from room setup and role assignment through sequenced night actions and day voting to elimination, win checks, and rematches. Firebase Auth and Firestore provide identity and shared state; the roster is public while role and ability data stay private. README-documented capabilities are included, though some source connections are unverified because excerpts are partial.

Main entry points: [`js/games/werewolf/ui.js`](https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/ui.js) (Game screens), [`js/core/engine.js`](https://github.com/accesswarrior/werewolf/blob/main/js/core/engine.js) (Room lifecycle), [`js/core/lobby.js`](https://github.com/accesswarrior/werewolf/blob/main/js/core/lobby.js) (Waiting room), [`js/core/auth.js`](https://github.com/accesswarrior/werewolf/blob/main/js/core/auth.js) (Account access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and rooms"]
  node_auth["Account access<br/>[auth.js]"]
  node_routing["Room routing<br/>[main.js]"]
  node_room["Room lifecycle<br/>[engine.js]"]
  node_lobby["Waiting room<br/>[lobby.js]"]
end

subgraph group_gameplay["Game flow"]
  node_gameui["Game screens<br/>[ui.js]"]
  node_narrator["Moderator script<br/>[narrator.js]"]
  node_night["Night actions<br/>[night.js]"]
  node_voting["Day voting<br/>[voting.js]"]
end

subgraph group_rules["Rules and outcomes"]
  node_rules["Role and win rules<br/>[rules.js]"]
end

subgraph group_services["Firebase services"]
  node_firebaseconfig["Firebase setup<br/>[firebaseConfig.js]"]
  node_authservice["Firebase Auth"]
  node_firestore[("Firestore")]
end

node_player(("Players"))
node_moderator(("Moderator"))

node_player -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_authservice
node_firebaseconfig -->|"initializes"| node_authservice
node_firebaseconfig -->|"initializes"| node_firestore
node_auth -->|"writes profiles"| node_firestore
node_authservice -->|"signals sign-in"| node_routing
node_routing -->|"reads sessions"| node_firestore
node_player -->|"joins room"| node_room
node_moderator -->|"creates room"| node_room
node_room -->|"stores room state"| node_firestore
node_room -->|"sets up session"| node_lobby
node_player -->|"readies up"| node_lobby
node_moderator -->|"starts game"| node_lobby
node_lobby -->|"updates roster"| node_firestore
node_lobby -->|"assigns roles"| node_rules
node_moderator -->|"runs rounds"| node_gameui
node_player -->|"views private role"| node_gameui
node_gameui -->|"listens to game state"| node_firestore
node_gameui -->|"submits actions"| node_night
node_gameui -->|"casts and reveals votes"| node_voting
node_gameui -.->|"shows script"| node_narrator
node_night -->|"records actions"| node_firestore
node_night -->|"checks outcomes"| node_rules
node_voting -->|"records ballots"| node_firestore
node_voting -->|"checks outcomes"| node_rules
node_room -->|"resets rematch"| node_firestore

click node_auth "https://github.com/accesswarrior/werewolf/blob/main/js/core/auth.js"
click node_routing "https://github.com/accesswarrior/werewolf/blob/main/js/main.js"
click node_room "https://github.com/accesswarrior/werewolf/blob/main/js/core/engine.js"
click node_lobby "https://github.com/accesswarrior/werewolf/blob/main/js/core/lobby.js"
click node_gameui "https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/ui.js"
click node_narrator "https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/narrator.js"
click node_night "https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/night.js"
click node_voting "https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/voting.js"
click node_rules "https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/rules.js"
click node_firebaseconfig "https://github.com/accesswarrior/werewolf/blob/main/js/core/firebaseConfig.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_auth,node_routing,node_room,node_lobby toneBlue
class node_gameui,node_narrator,node_night,node_voting toneAmber
class node_rules toneMint
class node_firebaseconfig,node_authservice,node_firestore toneRose
class node_player,node_moderator toneIndigo
```

## Components

### Identity and rooms

- [Account access](https://github.com/accesswarrior/werewolf/blob/main/js/core/auth.js): `js/core/auth.js`
- [Room routing](https://github.com/accesswarrior/werewolf/blob/main/js/main.js): `js/main.js`
- [Room lifecycle](https://github.com/accesswarrior/werewolf/blob/main/js/core/engine.js): `js/core/engine.js`
- [Waiting room](https://github.com/accesswarrior/werewolf/blob/main/js/core/lobby.js): `js/core/lobby.js`

### Game flow

- [Game screens](https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/ui.js): `js/games/werewolf/ui.js`
- [Moderator script](https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/narrator.js): `js/games/werewolf/narrator.js`
- [Night actions](https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/night.js): `js/games/werewolf/night.js`
- [Day voting](https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/voting.js): `js/games/werewolf/voting.js`

### Rules and outcomes

- [Role and win rules](https://github.com/accesswarrior/werewolf/blob/main/js/games/werewolf/rules.js): `js/games/werewolf/rules.js`

### Firebase services

- [Firebase setup](https://github.com/accesswarrior/werewolf/blob/main/js/core/firebaseConfig.js): `js/core/firebaseConfig.js`
- **Firebase Auth**
- **Firestore**

### Other components

- **Players**
- **Moderator**

## Connections

- Players → Account access: signs in (evidence: `js/core/auth.js`)
- Account access → Firebase Auth: authenticates (evidence: `js/core/auth.js`)
- Firebase setup → Firebase Auth: initializes (evidence: `js/core/firebaseConfig.js`)
- Firebase setup → Firestore: initializes (evidence: `js/core/firebaseConfig.js`)
- Account access → Firestore: writes profiles (evidence: `js/core/auth.js`)
- Firebase Auth → Room routing: signals sign-in (evidence: `js/main.js`)
- Room routing → Firestore: reads sessions (evidence: `js/main.js`)
- Players → Room lifecycle: joins room (evidence: `README.md`)
- Moderator → Room lifecycle: creates room
- Room lifecycle → Firestore: stores room state (evidence: `js/core/engine.js`)
- Room lifecycle → Waiting room: sets up session (evidence: `README.md`)
- Players → Waiting room: readies up (evidence: `js/core/lobby.js`)
- Moderator → Waiting room: starts game (evidence: `js/core/lobby.js`)
- Waiting room → Firestore: updates roster (evidence: `js/core/lobby.js`)
- Waiting room → Role and win rules: assigns roles (evidence: `README.md`)
- Moderator → Game screens: runs rounds (evidence: `README.md`)
- Players → Game screens: views private role (evidence: `README.md`)
- Game screens → Firestore: listens to game state (evidence: `js/games/werewolf/ui.js`)
- Game screens → Night actions: submits actions (evidence: `js/games/werewolf/ui.js`)
- Game screens → Day voting: casts and reveals votes (evidence: `README.md`)
- Game screens → Moderator script: shows script
- Night actions → Firestore: records actions (evidence: `js/games/werewolf/night.js`)
- Night actions → Role and win rules: checks outcomes (evidence: `js/games/werewolf/night.js`)
- Day voting → Firestore: records ballots (evidence: `js/games/werewolf/voting.js`)
- Day voting → Role and win rules: checks outcomes (evidence: `README.md`)
- Room lifecycle → Firestore: resets rematch (evidence: `js/core/engine.js`)
