# fenilkaneria/ipl-auction-assistant architecture

> Architecture diagram of the GitHub repository fenilkaneria/ipl-auction-assistant, 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/fenilkaneria/ipl-auction-assistant
- Repository: https://github.com/fenilkaneria/ipl-auction-assistant

## Overview

IPL Auction Assistant lets a user sign in or play as a guest, choose a franchise, and manage it in a live auction against nine bot teams. The WebSocket-driven server advances one opponent per user action, enforces auction rules, and returns state and events; the advisor combines player valuation, budget limits, and opportunity cost to guide bids. Major supporting capabilities include fixed auction ordering, squad and purse views, account verification, and resumable saved games. The README and sampled entry points support the main flow; unsampled module wiring is omitted where uncertain.

Main entry points: [`backend/app/api/ws.py`](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/ws.py) (WebSocket handler), [`backend/app/api/routes.py`](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/routes.py) (REST routes), [`backend/app/advisor/recommend.py`](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/recommend.py) (Advice policy), [`backend/app/api/game.py`](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/game.py) (Game setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_auth_ui["Auth context<br/>[auth.jsx]"]
  node_team_select["Team selection<br/>[TeamSelect.jsx]"]
  node_room["Auction room<br/>[AuctionRoom.jsx]"]
  node_socket_hook["Socket client"]
  node_auction_views["Auction views"]
end

subgraph group_auction["Auction runtime"]
  node_ws["WebSocket handler<br/>[ws.py]"]
  node_game["Game setup<br/>[game.py]"]
  node_engine["Auction engine<br/>[engine.py]"]
  node_bots["Bot bidders<br/>[bots.py]"]
  node_ordering["Queue ordering<br/>[ordering.py]"]
  node_round_order["Round definitions<br/>[round_order.py]"]
end

subgraph group_advice["Decision advisor"]
  node_recommend["Advice policy<br/>[recommend.py]"]
  node_valuation["Player valuation<br/>[valuation.py]"]
  node_budget["Budget advice<br/>[budget.py]"]
  node_alternatives["Alternatives<br/>[alternatives.py]"]
end

subgraph group_accounts["Accounts and persistence"]
  node_api_routes["REST routes<br/>[routes.py]"]
  node_persist["Session persistence<br/>[persist.py]"]
  node_db["Database models<br/>[models.py]"]
  node_email["Email transport<br/>[email_service.py]"]
end

node_user(("Player"))
node_postgres[("PostgreSQL")]

node_user -->|"navigates"| node_app
node_app -->|"provides auth"| node_auth_ui
node_auth_ui -->|"auth requests"| node_api_routes
node_api_routes -->|"sends links"| node_email
node_user -->|"chooses franchise"| node_team_select
node_team_select -->|"starts game"| node_api_routes
node_api_routes -->|"creates session"| node_game
node_game -->|"builds queue"| node_ordering
node_ordering -->|"uses rounds"| node_round_order
node_game -->|"initializes auction"| node_engine
node_room -->|"opens session socket"| node_socket_hook
node_socket_hook -->|"sends actions"| node_ws
node_ws -->|"advances auction"| node_engine
node_ws -->|"dispatches bot turns"| node_bots
node_bots -->|"uses price signal"| node_valuation
node_ws -->|"requests advice"| node_recommend
node_recommend -->|"estimates value"| node_valuation
node_recommend -->|"checks affordability"| node_budget
node_recommend -->|"weighs later options"| node_alternatives
node_ws -->|"saves state"| node_persist
node_api_routes -->|"loads saved game"| node_persist
node_persist -->|"maps records"| node_db
node_db -->|"reads and writes"| node_postgres
node_ws -->|"returns snapshots"| node_socket_hook
node_room -->|"renders auction"| node_auction_views
node_auction_views -->|"shows live status"| node_user

click node_app "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/App.jsx"
click node_auth_ui "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/lib/auth.jsx"
click node_team_select "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/pages/TeamSelect.jsx"
click node_room "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/pages/AuctionRoom.jsx"
click node_socket_hook "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/lib/useAuctionSocket.js"
click node_auction_views "https://github.com/fenilkaneria/ipl-auction-assistant/tree/master/frontend/src/components"
click node_api_routes "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/routes.py"
click node_ws "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/ws.py"
click node_game "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/game.py"
click node_engine "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/engine.py"
click node_bots "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/bots.py"
click node_ordering "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/ordering.py"
click node_round_order "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/round_order.py"
click node_recommend "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/recommend.py"
click node_valuation "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/valuation.py"
click node_budget "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/budget.py"
click node_alternatives "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/alternatives.py"
click node_persist "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/persist.py"
click node_db "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/models.py"
click node_email "https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/email_service.py"

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_app,node_auth_ui,node_team_select,node_room,node_socket_hook,node_auction_views toneBlue
class node_ws,node_game,node_engine,node_bots,node_ordering,node_round_order,node_postgres toneAmber
class node_recommend,node_valuation,node_budget,node_alternatives toneMint
class node_api_routes,node_persist,node_db,node_email toneRose
class node_user toneIndigo
```

## Components

### Frontend experience

- [App routes](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth context](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/lib/auth.jsx): `frontend/src/lib/auth.jsx`
- [Team selection](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/pages/TeamSelect.jsx): `frontend/src/pages/TeamSelect.jsx`
- [Auction room](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/pages/AuctionRoom.jsx): `frontend/src/pages/AuctionRoom.jsx`
- [Socket client](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/frontend/src/lib/useAuctionSocket.js): `frontend/src/lib/useAuctionSocket.js`
- [Auction views](https://github.com/fenilkaneria/ipl-auction-assistant/tree/master/frontend/src/components): `frontend/src/components`

### Auction runtime

- [WebSocket handler](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/ws.py): `backend/app/api/ws.py`
- [Game setup](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/game.py): `backend/app/api/game.py`
- [Auction engine](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/engine.py): `backend/app/auction/engine.py`
- [Bot bidders](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/bots.py): `backend/app/auction/bots.py`
- [Queue ordering](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/ordering.py): `backend/app/auction/ordering.py`
- [Round definitions](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/auction/round_order.py): `backend/app/auction/round_order.py`

### Decision advisor

- [Advice policy](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/recommend.py): `backend/app/advisor/recommend.py`
- [Player valuation](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/valuation.py): `backend/app/advisor/valuation.py`
- [Budget advice](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/budget.py): `backend/app/advisor/budget.py`
- [Alternatives](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/advisor/alternatives.py): `backend/app/advisor/alternatives.py`

### Accounts and persistence

- [REST routes](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Session persistence](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/api/persist.py): `backend/app/api/persist.py`
- [Database models](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/models.py): `backend/app/models.py`
- [Email transport](https://github.com/fenilkaneria/ipl-auction-assistant/blob/master/backend/app/email_service.py): `backend/app/email_service.py`

### Other components

- **Player**
- **PostgreSQL**

## Connections

- Player → App routes: navigates
- App routes → Auth context: provides auth
- Auth context → REST routes: auth requests
- REST routes → Email transport: sends links
- Player → Team selection: chooses franchise
- Team selection → REST routes: starts game
- REST routes → Game setup: creates session
- Game setup → Queue ordering: builds queue
- Queue ordering → Round definitions: uses rounds
- Game setup → Auction engine: initializes auction
- Auction room → Socket client: opens session socket
- Socket client → WebSocket handler: sends actions
- WebSocket handler → Auction engine: advances auction
- WebSocket handler → Bot bidders: dispatches bot turns
- Bot bidders → Player valuation: uses price signal
- WebSocket handler → Advice policy: requests advice
- Advice policy → Player valuation: estimates value
- Advice policy → Budget advice: checks affordability
- Advice policy → Alternatives: weighs later options
- WebSocket handler → Session persistence: saves state
- REST routes → Session persistence: loads saved game
- Session persistence → Database models: maps records
- Database models → PostgreSQL: reads and writes
- WebSocket handler → Socket client: returns snapshots
- Auction room → Auction views: renders auction
- Auction views → Player: shows live status