{"id":20500090,"url":"https://github.com/zevaverbach/kindchess","last_synced_at":"2025-09-10T16:32:01.349Z","repository":{"id":180664501,"uuid":"607373300","full_name":"zevaverbach/kindchess","owner":"zevaverbach","description":"Yet another chess server! But only for kind users.","archived":false,"fork":false,"pushed_at":"2023-07-25T17:05:10.000Z","size":2714,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-09-01T12:09:44.719Z","etag":null,"topics":["chess"],"latest_commit_sha":null,"homepage":"https://kindchess.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zevaverbach.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-27T21:13:43.000Z","updated_at":"2024-11-08T15:04:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"ce59896e-1400-43ef-a170-9cd003301299","html_url":"https://github.com/zevaverbach/kindchess","commit_stats":null,"previous_names":["zevaverbach/kindchess"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zevaverbach/kindchess","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevaverbach%2Fkindchess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevaverbach%2Fkindchess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevaverbach%2Fkindchess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevaverbach%2Fkindchess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zevaverbach","download_url":"https://codeload.github.com/zevaverbach/kindchess/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zevaverbach%2Fkindchess/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274487231,"owners_count":25294480,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-10T02:00:12.551Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess"],"created_at":"2024-11-15T18:19:46.064Z","updated_at":"2025-09-10T16:32:01.305Z","avatar_url":"https://github.com/zevaverbach.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Purpose\nA chess server built from scratch (except the board itself). It supports playing via web browser, \nand later it will be playable via command line/TUI or messaging.\n\nI'm interested in this because a) I like chess and b) I want to learn more about system design and\nrelated topics.\n\n# Requirements\n\n## Production\n- a Redis server \n- a Postgres instance (with a database called \"games\")\n- Python 3.11\n- `./requirements.txt`\n\n## Development \n- all of the above, substituting `requirements-dev.txt` for `requirements.txt`.\n- For testing the websocket server, use `websocat` or another websocket client (`\u003e brew install websocat`)\n  - for testing: `\u003e websocat localhost:8001`\n\n## Environment Variables\n- DB_USER\n- DB_PASS\n- DB_NAME\n- DB_HOSTNAME\n- REDIS_NAME\n- REDIS_URL\n- KINDCHESS_ENVIRONMENT (\"prod\"/\"local\")\n\n# Local Dev Environment\n1) start a local Redis server using default port (`$ redis-server`)\n1) activate the virtual environment (`cd kindchess \u0026\u0026 source env/bin/activate`)\n1) first time: `$ python init_db.py`\n1) run tests: `$ python -m pytest`\n1) `$ flask run`\n1) open another tab, activate the venv and `$ python ws_server.py`\n\n# Deployment\n\n## New Service/Infra\n- create the service in render.com dashboard\n  - associate the `zevchess` env group\n  - use the default `pip install -r requirements.txt`\n  - for web API, `gunicorn -w 2 \u003cor however many\u003e app:application`\n  - for websocket server, `python ws_server.py`\n  - run `python init_db.py`\n    - this could be run locally if you tell it the appropriate DB to connect to\n\n## Code Updates\n- simply push to the monorepo, then either wait 1-10 mins to mirror to Github or manually sync (https://code.averba.ch/Zev/zevchess/settings)\n\n### Schema Changes\n- if there's a change to `zevchess.GameState.to_db_dict()`'s keys, make sure to re-initialize the DB in order to add those fields. However, once the server is truly in 'production' with more than a few users, it'd be better to a) use DB migrations and b) make sure not to break ongoing games.\n\n- since the ongoing games' states are stored in Redis (schema-less/NoSQL), there aren't any changes needed for attribute changes on `GameState` which don't appear in `to_db_dict()`'s output. Nevertheless, it will be important not to break ongoing games with such changes.\n\n# Testing\n- load testing (TODO as of March 3 2023)\n- unit testing (see `tests/`)\n\n# Cost\n- $382/year as of feb 27 2023\n  - domain $10\n  - postgres $84 (dev $0)\n  - redis $120 (dev $0)\n  - websocket server $84 (dev $0)\n  - web API server $84 (dev $0)\n\n# Roadmap\nOnce there's a functional, not-too-buggy web API and web client, I'll load test and profile it \nto see what might be optimized. When nearing the \"end of the road\" of optimizations in Python, \nI'll explore porting to another language.\n\nMy initial thought has been to port it to Go, but it looks like for websockets there are some \nbetter-performing choices:\n\nNode, [Bun](https://twitter.com/jarredsumner/status/1562121275945803776?lang=en) or even \n[socketify](https://raw.githubusercontent.com/cirospaciari/socketify.py/main/misc/ws-bar-graph.png) \nseem like great choices as they're able to send hundreds of thousands of messages per second.\n\nI'm excited about writing it in a language other than Python, though, and I'm wondering if \nthe gains in websocket performance will be offset by the slowness of the engine. \n\nThe point here is \"the journey\", as I want to learn to measure and improve performance, \nincluding strategies beyond code.\n\n# Possible Directions\n\nCollaborative chess-playing? For example, if you have the functionality described below where \nyou can save possible moves for the current position, you could give the option for a game's watchers\nto present possible moves, including possibly some annotation/speech about why it might be a good idea.\n\n## UX\n- super low-friction to jumping into a game with people you know, or maybe who are part of a trusted group\n- friendliness, zero tolerance for jerks\n\n## UI \n- super minimal, fewer widgets than chess.com/lichess\n- emphasis on socializing, including voice\n- thoughtful chess playing, possibly including an optional \"minimum time to move\"\n- ability to jump ahead and imagine moves by both sides while a) waiting for opponent to move or b) figuring out how to move.\n  - store moves in a list and choose from them when ready\n    - only for the very next move at first, not multiple\n- optional subtle, playful animations\n\n# Resources Used\n- [generate FEN from board](http://www.netreal.de/Forsyth-Edwards-Notation/index.php)\n- [generate board from FEN](http://www.ee.unb.ca/cgi-bin/tervo/fen.pl)\n- [the board](https://github.com/shaack/cm-chessboard)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevaverbach%2Fkindchess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzevaverbach%2Fkindchess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzevaverbach%2Fkindchess/lists"}