Penny Game is a web-based multiplayer game where players compete in a strategic penny-flipping challenge. This repository contains both the backend API and the frontend client for the game.

• Backend (API): Built with FastAPI, located in the api/ directory. Handles game logic, player management, and real-time communication via WebSockets.
• frontend: Built with Astro, located in the frontend/ directory. Provides an interactive user interface for joining games, playing, and viewing results. Hosted on GitHub Pages for easy access.

• Real-time multiplayer gameplay
• Secure API endpoints for game actions
• WebSocket support for live updates
• Responsive and modern UI

• Python 3.12+ (for backend)
• Node.js 22+ and npm (for frontend)

1. Install dependencies:

   cd api
   pip install -r requirements.txt

2. Start the FastAPI server:

   uvicorn app.main:app --host 0.0.0.0

3. The API will be available at http://<your-server-ip>:8000.

1. Install dependencies:

   cd frontend
   npm install

2. Build the static site:

   npm run build

3. Preview locally:

   npm run preview

4. Deploy to GitHub Pages (see your repository settings for details).

1. Open the frontend site (hosted on GitHub Pages).
2. Join a game or create a new one.
3. Play the Penny Game with other online players in real time.

The Penny Game is a Lean simulation used to visualize flow efficiency and measure lead time in a production process. It is a cooperative, non-competitive game focused on how batch size impacts performance.

Players work together to move and flip coins (🪙) through a production line as quickly as possible. The goal is to complete the entire process—from the first flip to the last delivery—as efficiently as possible, depending on the configured batch size.

• 2 to 5 players per game.
• The first player to join becomes the first in the chain.
• A separate host starts the game but does not participate as a player.

• The total number of coins is fixed (usually 12).
• Each coin starts as tails and must be flipped to heads before being passed on.
• Players only control the coins assigned to them, based on the batch size rule.
• Players can only send coins that are flipped to heads.
• Once all their coins in a batch are flipped, players send them to the next player in line.
• The game ends when the last player sends the final coin.

The core mechanic of the game is the batch size:

Batch size influences how simultaneously players can act:

• Large batches lead to idle time for other players.
• Small batches enable parallel actions and smoother flow.

• The game is not turn-based.
• Depending on the batch size, players may act simultaneously.
• Players flip and send coins as soon as allowed, making it a cooperative speed-run experience.

• Coins must be flipped (heads up) before they can be sent.
• There is no penalty for invalid actions—unflipped coins simply remain in place.
• If a player disconnects, their turn is skipped.
• Disconnected players may rejoin and continue playing.

Currently configurable options include:

• Number of players (2–5)
• Batch size: 12/12, 4/12, or 1/12

• Game rules are shown to all players before the game starts.
• No prior experience is required—just read, flip, and flow!

• Backend code is in api/app/ (see main.py, game_logic.py, etc.).
• frontend code is in frontend/src/ and frontend/public/scripts/.

This project is licensed under the GNU Affero General Public License v3. See the LICENSE file for details.

Contributions are welcome! Please open issues or submit pull requests for improvements, bugfixes, or new features.

For questions or support, please open an issue in this repository.