# klmcorp/pokerplanning architecture

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

- Interactive diagram: https://gitdiagram.com/klmcorp/pokerplanning
- Repository: https://github.com/klmcorp/pokerplanning

## Overview

Planning Poker is a real-time planning poker application: participants join a room, estimate backlog items through a hidden-vote/reveal cycle, and see shared results. The Next.js client connects over Socket.IO to the server handlers, which own room operations and delegate transient room state and persistent account data to separate stores. Accounts, backlog, room customization, administration, localization, and PO timeboxing are distinct product capabilities. The README documents capabilities whose detailed handlers were not sampled; their links are shown only where the tree or sampled calls support them.

Main entry points: [`src/contexts/SocketContext.tsx`](https://github.com/klmcorp/pokerplanning/blob/main/src/contexts/SocketContext.tsx) (Socket client state), [`server/socket/handlers.ts`](https://github.com/klmcorp/pokerplanning/blob/main/server/socket/handlers.ts) (Socket handlers), [`src/contexts/AuthContext.tsx`](https://github.com/klmcorp/pokerplanning/blob/main/src/contexts/AuthContext.tsx) (Authentication state), [`src/components/ClientProviders.tsx`](https://github.com/klmcorp/pokerplanning/blob/main/src/components/ClientProviders.tsx) (Client providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_home["Room entry<br/>[page.tsx]"]
  node_roompage["Planning room<br/>[page.tsx]"]
  node_backlogpage["Backlog page<br/>[page.tsx]"]
  node_accountpage["Account settings<br/>[page.tsx]"]
  node_profilepage["Profile<br/>[page.tsx]"]
  node_adminpage["Admin dashboard<br/>[page.tsx]"]
end

subgraph group_realtime["Realtime rooms"]
  node_socketctx["Socket client state<br/>[SocketContext.tsx]"]
  node_roomhook["Room actions and views<br/>[useRoom.ts]"]
  node_handlers["Socket handlers<br/>[handlers.ts]"]
  node_roomstore["Room state<br/>[roomStore.ts]"]
end

subgraph group_identity["Accounts and backlog"]
  node_authctx["Authentication state<br/>[AuthContext.tsx]"]
  node_authmodal["Sign in and reset<br/>[AuthModal.tsx]"]
  node_userstore["Account and backlog data<br/>[userStore.ts]"]
end

subgraph group_persistence["Persistence and email"]
  node_database[("SQLite<br/>[userStore.ts]")]
  node_mailer["Password reset mail<br/>[mailer.ts]"]
end

subgraph group_platform["Shared platform"]
  node_server["HTTP and Socket.IO<br/>[index.ts]"]
  node_localization["French and English<br/>[config.ts]"]
  node_providers["Client providers"]
end

node_participant(("Participant"))
node_smtp(("SMTP service"))

node_participant -->|"opens app"| node_home
node_participant -->|"joins room"| node_roompage
node_home -->|"requests room"| node_socketctx
node_roompage -->|"uses room actions"| node_roomhook
node_roomhook -->|"emits actions"| node_socketctx
node_socketctx -->|"Socket.IO events"| node_server
node_server -->|"registers handlers"| node_handlers
node_handlers -->|"reads and updates"| node_roomstore
node_roomstore -->|"returns room state"| node_handlers
node_handlers -->|"broadcasts room updates"| node_socketctx
node_socketctx -->|"provides room state"| node_roomhook
node_participant -->|"submits credentials"| node_authmodal
node_authmodal -->|"calls auth actions"| node_authctx
node_authctx -->|"uses socket"| node_socketctx
node_authctx -->|"requests account actions"| node_userstore
node_handlers -->|"handles account and backlog events"| node_userstore
node_userstore -->|"reads and writes"| node_database
node_handlers -->|"sends reset email"| node_mailer
node_mailer -.->|"sends mail"| node_smtp
node_backlogpage -->|"manages backlog"| node_socketctx
node_accountpage -->|"updates settings"| node_authctx
node_profilepage -->|"uses account"| node_authctx
node_adminpage -->|"requests admin data"| node_socketctx
node_providers -->|"provides client state"| node_socketctx
node_providers -->|"provides client state"| node_authctx
node_providers -->|"provides locale"| node_localization
node_home -->|"displays translations"| node_localization
node_roompage -->|"displays translations"| node_localization

click node_home "https://github.com/klmcorp/pokerplanning/blob/main/src/app/page.tsx"
click node_roompage "https://github.com/klmcorp/pokerplanning/blob/main/src/app/room/%5BroomId%5D/page.tsx"
click node_backlogpage "https://github.com/klmcorp/pokerplanning/blob/main/src/app/backlog/page.tsx"
click node_accountpage "https://github.com/klmcorp/pokerplanning/blob/main/src/app/account/page.tsx"
click node_profilepage "https://github.com/klmcorp/pokerplanning/blob/main/src/app/profile/page.tsx"
click node_adminpage "https://github.com/klmcorp/pokerplanning/blob/main/src/app/admin/page.tsx"
click node_socketctx "https://github.com/klmcorp/pokerplanning/blob/main/src/contexts/SocketContext.tsx"
click node_roomhook "https://github.com/klmcorp/pokerplanning/blob/main/src/hooks/useRoom.ts"
click node_handlers "https://github.com/klmcorp/pokerplanning/blob/main/server/socket/handlers.ts"
click node_roomstore "https://github.com/klmcorp/pokerplanning/blob/main/server/store/roomStore.ts"
click node_authctx "https://github.com/klmcorp/pokerplanning/blob/main/src/contexts/AuthContext.tsx"
click node_authmodal "https://github.com/klmcorp/pokerplanning/blob/main/src/components/AuthModal.tsx"
click node_userstore "https://github.com/klmcorp/pokerplanning/blob/main/server/store/userStore.ts"
click node_server "https://github.com/klmcorp/pokerplanning/blob/main/server/index.ts"
click node_database "https://github.com/klmcorp/pokerplanning/blob/main/server/store/userStore.ts"
click node_mailer "https://github.com/klmcorp/pokerplanning/blob/main/server/utils/mailer.ts"
click node_localization "https://github.com/klmcorp/pokerplanning/blob/main/src/i18n/config.ts"
click node_providers "https://github.com/klmcorp/pokerplanning/blob/main/src/components/ClientProviders.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_home,node_roompage,node_backlogpage,node_accountpage,node_profilepage,node_adminpage toneBlue
class node_socketctx,node_roomhook,node_handlers,node_roomstore toneAmber
class node_authctx,node_authmodal,node_userstore toneMint
class node_database,node_mailer toneRose
class node_server,node_localization,node_providers,node_participant,node_smtp toneIndigo
```

## Components

### Client experience

- [Room entry](https://github.com/klmcorp/pokerplanning/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Planning room](https://github.com/klmcorp/pokerplanning/blob/main/src/app/room/%5BroomId%5D/page.tsx): `src/app/room/[roomId]/page.tsx`
- [Backlog page](https://github.com/klmcorp/pokerplanning/blob/main/src/app/backlog/page.tsx): `src/app/backlog/page.tsx`
- [Account settings](https://github.com/klmcorp/pokerplanning/blob/main/src/app/account/page.tsx): `src/app/account/page.tsx`
- [Profile](https://github.com/klmcorp/pokerplanning/blob/main/src/app/profile/page.tsx): `src/app/profile/page.tsx`
- [Admin dashboard](https://github.com/klmcorp/pokerplanning/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`

### Realtime rooms

- [Socket client state](https://github.com/klmcorp/pokerplanning/blob/main/src/contexts/SocketContext.tsx): `src/contexts/SocketContext.tsx`
- [Room actions and views](https://github.com/klmcorp/pokerplanning/blob/main/src/hooks/useRoom.ts): `src/hooks/useRoom.ts`
- [Socket handlers](https://github.com/klmcorp/pokerplanning/blob/main/server/socket/handlers.ts): `server/socket/handlers.ts`
- [Room state](https://github.com/klmcorp/pokerplanning/blob/main/server/store/roomStore.ts): `server/store/roomStore.ts`

### Accounts and backlog

- [Authentication state](https://github.com/klmcorp/pokerplanning/blob/main/src/contexts/AuthContext.tsx): `src/contexts/AuthContext.tsx`
- [Sign in and reset](https://github.com/klmcorp/pokerplanning/blob/main/src/components/AuthModal.tsx): `src/components/AuthModal.tsx`
- [Account and backlog data](https://github.com/klmcorp/pokerplanning/blob/main/server/store/userStore.ts): `server/store/userStore.ts`

### Persistence and email

- [SQLite](https://github.com/klmcorp/pokerplanning/blob/main/server/store/userStore.ts): `server/store/userStore.ts`
- [Password reset mail](https://github.com/klmcorp/pokerplanning/blob/main/server/utils/mailer.ts): `server/utils/mailer.ts`

### Shared platform

- [HTTP and Socket.IO](https://github.com/klmcorp/pokerplanning/blob/main/server/index.ts): `server/index.ts`
- [French and English](https://github.com/klmcorp/pokerplanning/blob/main/src/i18n/config.ts): `src/i18n/config.ts`
- [Client providers](https://github.com/klmcorp/pokerplanning/blob/main/src/components/ClientProviders.tsx): `src/components/ClientProviders.tsx`

### Other components

- **Participant**
- **SMTP service**

## Connections

- Participant → Room entry: opens app
- Participant → Planning room: joins room
- Room entry → Socket client state: requests room
- Planning room → Room actions and views: uses room actions
- Room actions and views → Socket client state: emits actions
- Socket client state → HTTP and Socket.IO: Socket.IO events
- HTTP and Socket.IO → Socket handlers: registers handlers
- Socket handlers → Room state: reads and updates
- Room state → Socket handlers: returns room state
- Socket handlers → Socket client state: broadcasts room updates
- Socket client state → Room actions and views: provides room state
- Participant → Sign in and reset: submits credentials
- Sign in and reset → Authentication state: calls auth actions
- Authentication state → Socket client state: uses socket
- Authentication state → Account and backlog data: requests account actions
- Socket handlers → Account and backlog data: handles account and backlog events
- Account and backlog data → SQLite: reads and writes
- Socket handlers → Password reset mail: sends reset email
- Password reset mail → SMTP service: sends mail
- Backlog page → Socket client state: manages backlog
- Account settings → Authentication state: updates settings
- Profile → Authentication state: uses account
- Admin dashboard → Socket client state: requests admin data
- Client providers → Socket client state: provides client state
- Client providers → Authentication state: provides client state
- Client providers → French and English: provides locale
- Room entry → French and English: displays translations
- Planning room → French and English: displays translations