51 lines
4 KiB
Markdown
51 lines
4 KiB
Markdown
# Repository Guidelines
|
|
|
|
This is a Companion App for an IRL Board Game. The board game is called Negopoly, a Monopoly parody that runs in a city called NegoCity. The app is built using Bun runtime and TypeScript. The App serves as a fake banking system for players to manage their in-game finances.
|
|
|
|
When a user reaches the app, they are greeted with a home page about the game. They can then go to /play, where they can create or join a game session. Each game session has a unique code that players can use to join. When a player creates a game session, they become the banker (sort of the session admin) and can start the game once all players have joined. When the banker is on the lobby screen, it also displays a QR code that other players can scan to join the game session easily (/play/:sessionID).
|
|
|
|
Using the app, players can see their current balance, transaction history, and transfer money to other players. They can also chat with other players in the session, and create chat groups for private conversations with multiple players.
|
|
|
|
The Banker has complete control over the game session. They can force transfers between players, add or remove money from players, see all chats, and end the game. They can also block all functionality for a set time (there are special cards in the game that cause a complete blackout).
|
|
|
|
The Banker can also create "dummy" players for IRL participants who don't have access to the app, allowing them to manage their finances through the Banker. If a user disconnects, their profile becomes a dummy player that the Banker can control. If a user connects mid-game, they can take over a dummy player (the Banker needs to approve).
|
|
|
|
The frontend is built with react and TSX files, while the backend uses Bun's built-in server capabilities. The play part of the frontend needs to look like a banking app, with a clean and simple UI, and needs to be mobile-first (for the players, the Banker will probably use a computer most of the time). The home page can be more playful and colorful to match the game's theme. The app will store game sessions in memory, so no database is required. The app should be optimized for performance and low latency, as multiple players will be interacting with it simultaneously. It will need to handle updates in real-time, so consider using WebSockets (using Bun's built in WebSocket server) or similar technologies for communication between the frontend and backend.
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
- `index.ts` is the current entry point (Bun runtime).
|
|
- `front/` exists but is currently empty; place frontend assets or HTML/TSX here if you add a UI.
|
|
- `README.md` documents basic Bun usage.
|
|
- `node_modules/` is generated by `bun install` and should not be edited directly.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
- `bun install` — install dependencies.
|
|
- `bun run index.ts` — run the app (from `README.md`).
|
|
- `bun --hot ./index.ts` — optional hot-reload workflow if you add server routes or frontend assets.
|
|
- `bun test` — run tests when they exist (see testing section).
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
- Use TypeScript in ESM mode (`"type": "module"`).
|
|
- Prefer Bun APIs from `CLAUDE.md` (e.g., `Bun.serve`, `Bun.file`, `bun:sqlite`) instead of Node/Express equivalents.
|
|
- Indentation: 2 spaces in JSON; use your editor defaults for TS but keep it consistent.
|
|
- Name files by role (e.g., `index.ts`, `frontend.tsx`, `*.test.ts`).
|
|
|
|
## Testing Guidelines
|
|
|
|
- Testing framework: `bun:test` (see `CLAUDE.md` example).
|
|
- Test file naming: `*.test.ts` alongside the code or under a future `tests/` directory.
|
|
- Run tests with `bun test`.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
- This directory is not a Git repository, so commit conventions are not defined yet.
|
|
- If you initialize Git, prefer concise, present-tense messages (e.g., `Add api route for users`).
|
|
- PRs (if used): include a short description, steps to verify, and screenshots for UI changes.
|
|
|
|
## Configuration & Security Notes
|
|
|
|
- Bun auto-loads `.env`; do not add dotenv loaders unless required.
|
|
- Keep secrets out of the repo; use `.env.local` or CI secrets where available.
|