README: rewrite for new contributors; add Mermaid diagrams#662
Open
JobDoesburg wants to merge 6 commits into
Open
README: rewrite for new contributors; add Mermaid diagrams#662JobDoesburg wants to merge 6 commits into
JobDoesburg wants to merge 6 commits into
Conversation
The README had grown into a marketing-y feature list with thin
architecture, no diagrams, and the production-ops surface (Sentry,
SURFconext, Yivi server, Silvasoft, fridge client) mentioned only in
passing or not at all. Restructure for the reader who is actually
landing here for the first time.
- New "What it does" section that explains the user-facing surface in
plain language, replacing the "🚀 Features" bullet list that read
like a brochure.
- New "Architecture at a glance" section with two Mermaid diagrams that
render natively on GitHub:
- **App + external-service graph** showing the natural data-flow
relationships between the Django apps and the outside systems
they talk to. Helps a new contributor see at a glance which app
fits where and what depends on what.
- **Auth flow sequence diagram** covering SAML login → OAuth
consent → token → API/MCP request, plus the optional Yivi age-
verification side-quest for the beer fridge. This is the most
asked-about flow in the codebase and never had a picture.
- New "Operations & external services" table — Sentry (production
error tracking, with the org URL), SURFconext SAML federation
(where to manage the SP), Yivi, Spotify, Marietje, Silvasoft, the
TOSTI-fridge-client repo, and GitHub Actions. Each row says what
the service does and where to look on the TOSTI side.
- The OAuth/MCP section now leads with a "use authorization-code +
PKCE" line and points at the in-app docs (``/oauth/docs/``,
``/mcp/docs/``, ``/api/docs``) as the source of truth. Drops the
duplicated step-by-step MCP auth flow (the diagram covers it and
``/oauth/docs/`` has it in detail).
- The ``📁 Project structure`` tree gets updated descriptions for the
apps that grew (tampon, tosti now hosts OAuth + MCP infra), and
notes which apps will have their own README.
- Dropped the ``📁 Code Style`` subsection — duplicates
CONTRIBUTING.md/AGENTS.md and was drifting.
- Dropped the ``🔒 Security`` near-duplicate section — points at
SECURITY.md instead.
- Fixed the ``- -`` typo in the Acknowledgments list.
- Tightened the development-setup steps from a numbered list to a
single annotated shell block so newcomers can copy-paste through it.
No CI / setup commands actually changed — this is pure documentation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per review feedback: - Removing the ``subgraph "External services"`` box around the external nodes. The shape of the box was suggesting more grouping than was useful; the external services already read as external by not being inside the TOSTI box. - Removing the optional Yivi age-verification block from the auth sequence diagram. The diagram is about the SAML+OAuth chain that protects every route; Yivi is a separate one-shot disclosure flow that runs once on the age-verification page, not on every API call. It was distracting and slightly misleading. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- SURFconext: the right management URL is the SP dashboard at https://sp.surfconext.nl/ (with the entity id ``spd_ru_tosti``), managed through the welcome portal at https://welcome.surfconext.nl/ — not the IdP serviceregistry I'd listed. - Contact section: drop ``tartaruswebsite@science.ru.nl`` (legacy) and point everything at the canonical ``www-tosti@science.ru.nl``, the address SECURITY.md already uses. Same inbox; one address for everything keeps the project surface consistent.
The previous graph was a free-hand sketch; some edges (e.g. orders→transactions, borrel→users/transactions) didn't match the code, and real edges (age→users, fridges→venues, silvasoft→orders/venues, borrel→qualifications, *→associations) were missing. Also drop the "originally built for / now shared" framing in the intro — TOSTI was built for Tartarus, not inherited from elsewhere. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Make explicit that SpotifyPlayer implements the full control-plane API (request/search/start/pause/next/previous/volume/shuffle/repeat) while MarietjePlayer is read-only and the same methods are no-ops with can_control / can_request_song returning False. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The earlier diagrams were drawn from memory and got several things
wrong. Corrections:
orders/ add OrderVenue OneToOne→Venue, the Product.available_at M2M,
Shift.assignees M2M, Order.user_association FK, the
OrderBlacklistedUser OneToOne; replace the false
"queryable property" claim for Shift.is_active.
venues/ add Reservation→Association, user_updated FK, users_access
M2M, the tri-state `accepted`, `join_code`, `needs_music_keys`,
and the `active` queryable property. Drop the wrong claim
that rejected reservations get deleted.
borrel/ the big one: BorrelReservation owns its own start/end/title
plus a OneToOne to venues.Reservation (it does NOT live
on Venue directly). Add the three role users
(user_created/updated/submitted), users_access M2M,
tri-state accepted, queryable `active` and `submitted`.
ReservationItem snapshots product_name / price_per_unit.
thaliedje/ add SpotifyArtist, the SpotifyTrack.track_artists M2M,
the ThaliedjeControlEvent OneToOne to venues.Reservation
and its three permission tiers (association_* /
selected_users_* / everyone_*) plus the queryable
properties (start, end, active, player).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Restructures the README around the question "I'm a new contributor / new maintainer landing here for the first time — what do I need to know?" It had grown into a marketing-y feature list with thin architecture, no diagrams, and almost no mention of the external services (Sentry, SURFconext, etc.) you need to know about the moment something breaks.
Main additions
/oauth/docs/,/mcp/docs/,/api/docson a running deployment for everything else, instead of duplicating their content in the README.Tightening
📁 Code Stylesubsection — duplicates CONTRIBUTING.md/AGENTS.md and was drifting.🔒 Securitynear-duplicate section — points atSECURITY.mdinstead.- -typo in the Acknowledgments list.Not in scope here
Test plan
/oauth/docs/,/mcp/docs/,/api/docs,/explainers/#ai-assistant).tosti.sentry.io, SURFconext serviceregistry).