docs: explanation/, sequence diagrams of the data flows #4

Open
claude wants to merge 0 commits from docs/explanation into main
Collaborator

explanation/README.md: Mermaid sequence diagrams, end to end (game, launcher, Traefik, the services, Forgejo, Prometheus, Grafana, Discord):

  • Crash logs
    • manual reporting: the player's AI through /mcp/issue (search, forms, create or comment)
    • automatic, asked first: the crash window, Send Help or I am sorry, the relay's new comment or edit on #81, the OTLP push; the fallbacks under it
    • automatic, always sent: always_send=1, sent without waiting, the failure path
  • Performance: the tick, perf_pending/, the launcher's send at its next start with the backoff, the relay, the scrape, the dashboard
  • Authentication through MCP: the one-time Discord login through the gate's OAuth server, then forwardAuth on each request (cache, policy, identity token vs server token, 401/403/503)
  • Querying through MCP: PromQL through /mcp/grafana, #81's crash comments through /mcp/issue, with the useful series

The game- and launcher-side flows follow Longshot's docs/crash-report-window.md and docs/performance-statistics.md, whose branches aren't merged yet. The main README links the folder. Docs only.

🤖 Generated with Claude Code

https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm

`explanation/README.md`: Mermaid sequence diagrams, end to end (game, launcher, Traefik, the services, Forgejo, Prometheus, Grafana, Discord): - Crash logs - manual reporting: the player's AI through `/mcp/issue` (search, forms, create or comment) - automatic, asked first: the crash window, Send Help or I am sorry, the relay's new comment or edit on #81, the OTLP push; the fallbacks under it - automatic, always sent: `always_send=1`, sent without waiting, the failure path - Performance: the tick, `perf_pending/`, the launcher's send at its next start with the backoff, the relay, the scrape, the dashboard - Authentication through MCP: the one-time Discord login through the gate's OAuth server, then forwardAuth on each request (cache, policy, identity token vs server token, 401/403/503) - Querying through MCP: PromQL through `/mcp/grafana`, #81's crash comments through `/mcp/issue`, with the useful series The game- and launcher-side flows follow Longshot's `docs/crash-report-window.md` and `docs/performance-statistics.md`, whose branches aren't merged yet. The main README links the folder. Docs only. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs: explanation/, sequence diagrams of the crash reports, perf, the MCP sign-in and queries
All checks were successful
ci / lint (pull_request) Successful in 39s
ci / test (pull_request) Successful in 37s
ci / e2e (pull_request) Successful in 37s
ci / docs (pull_request) Successful in 31s
ci / image (pull_request) Successful in 9s
d4e6280fe4
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): the crash flows as the current branches have them
All checks were successful
ci / lint (pull_request) Successful in 36s
ci / test (pull_request) Successful in 42s
ci / docs (pull_request) Successful in 24s
ci / e2e (pull_request) Successful in 39s
ci / image (pull_request) Successful in 9s
c622c854bf
Report manually (clipboard and the prefilled form) and Report automatically
(sent on the click) from the helper's crash window; always sending is the
earlier design's, marked not built.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): the Python scripts are the player's side, the server is Go
All checks were successful
ci / test (pull_request) Successful in 29s
ci / lint (pull_request) Successful in 38s
ci / e2e (pull_request) Successful in 31s
ci / docs (pull_request) Successful in 33s
ci / image (pull_request) Successful in 11s
bf7c1c776f
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): why one Go API: modularity, performance, robustness, adding a service
All checks were successful
ci / test (pull_request) Successful in 27s
ci / lint (pull_request) Successful in 36s
ci / e2e (pull_request) Successful in 30s
ci / docs (pull_request) Successful in 34s
ci / image (pull_request) Successful in 23s
2d76b23b06
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): Traefik is the proxy, whichever it is
All checks were successful
ci / lint (pull_request) Successful in 31s
ci / test (pull_request) Successful in 35s
ci / e2e (pull_request) Successful in 32s
ci / docs (pull_request) Successful in 33s
ci / image (pull_request) Successful in 13s
b008bc1bfa
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): Beanstalk, its integration points and ramifications
All checks were successful
ci / lint (pull_request) Successful in 37s
ci / test (pull_request) Successful in 37s
ci / e2e (pull_request) Successful in 42s
ci / docs (pull_request) Successful in 35s
ci / image (pull_request) Successful in 8s
c663325b60
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015KgSKp43znbyyPyDajp3Cm
docs(explanation): what's deployed, merged and counted, as of 15 Nov
All checks were successful
ci / lint (pull_request) Successful in 38s
ci / test (pull_request) Successful in 37s
ci / e2e (pull_request) Successful in 45s
ci / docs (pull_request) Successful in 35s
ci / image (pull_request) Successful in 11s
e86a7af3b8
Checked against Bean-Ops, Longshot, the launcher and Beanstalk:
- the relays went out across Bean-Ops 91e5f47 and db8d8e0, not 91e5f47 alone
- mcp-issue and the gate's policy file aren't deployed yet
- the performance statistics are on unmerged game and launcher branches
- Beanstalk's coordinator has 155 test functions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: /mcp/issue signs in with Forgejo, not Discord (planned)
All checks were successful
ci / lint (pull_request) Successful in 39s
ci / test (pull_request) Successful in 39s
ci / e2e (pull_request) Successful in 38s
ci / docs (pull_request) Successful in 30s
ci / image (pull_request) Successful in 6s
856b073faf
A player filing a bug already has an account on git.magicbean.dev, so
/mcp/issue's sign-in is planned to be the forge's: anyone with a forge
account gets in, no Discord server or role needed. The gate stays the
OAuth server MCP clients register with (Forgejo has no dynamic client
registration) and sends this route's sign-in to Forgejo, asking for
read:user only; mcp-issue still gets an identity token, and the bot
still opens the issue, "reported by @login". /mcp/grafana keeps the
Discord sign-in and the Big Bean role. Not built: the gate speaks
Discord only today.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: /mcp/issue files with the person's own forge login (planned)
Some checks failed
ci / lint (pull_request) Successful in 38s
ci / test (pull_request) Successful in 56s
ci / e2e (pull_request) Has been cancelled
ci / docs (pull_request) Has been cancelled
ci / image (pull_request) Has been cancelled
739772d4d4
Once /mcp/issue signs in with Forgejo, the gate hands mcp-issue the
person's forge token beside the identity token, and the issue or comment
is opened as them: Forgejo's own permissions decide, and where they can't
write, they can't report. The crash bot sets the form's labels, which a
player can't, and the separate issue bot goes away. /mcp/grafana keeps
Discord, the Magic Bean server, the Big Bean role and the admins.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs(architecture): deployment.md, how Bean-Ops runs Longshot-api
All checks were successful
ci / lint (pull_request) Successful in 35s
ci / test (pull_request) Successful in 36s
ci / e2e (pull_request) Successful in 31s
ci / docs (pull_request) Successful in 31s
ci / image (pull_request) Successful in 9s
ff1c272731
From a commit to a running pod (CI on main, digests pinned in Bean-Ops,
SOPS decrypted by ArgoCD's sidecar), what runs in the magicbean namespace
and how Traefik reaches it, and who may use which MCP server: Discord and
the Big Bean role for /mcp/grafana, Forgejo and the person's own login
for /mcp/issue (planned). Linked from the architecture and the
explanation's index.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
claude scheduled this pull request to auto merge when all checks succeed 2026-11-15 15:15:48 -05:00
All checks were successful
ci / lint (pull_request) Successful in 35s
ci / test (pull_request) Successful in 36s
ci / e2e (pull_request) Successful in 31s
ci / docs (pull_request) Successful in 31s
ci / image (pull_request) Successful in 9s
This branch is already included in the target branch. There is nothing to merge.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin 'docs/explanation:docs/explanation'
git switch 'docs/explanation'

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch 'main'
git merge --no-ff 'docs/explanation'
git switch 'docs/explanation'
git rebase 'main'
git switch 'main'
git merge --ff-only 'docs/explanation'
git switch 'docs/explanation'
git rebase 'main'
git switch 'main'
git merge --no-ff 'docs/explanation'
git switch 'main'
git merge --squash 'docs/explanation'
git switch 'main'
git merge --ff-only 'docs/explanation'
git switch 'main'
git merge 'docs/explanation'
git push origin 'main'
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBean-Mirror/Longshot-api!4
No description provided.