docs: bring READMEs, ARCHITECTURE, and wiki up to date

[hoangsonww]

Refreshes the core docs to match the current app + RL state. All edits were verified against the code (route greps, feedback_views/store/bandit, users/views, ResultsPage/Profile/feedback service).

What changed

Auth

• Sign in with username or email (case-insensitive email fallback).
• Cold-start transient DB errors are retried → 503 "waking up" (client auto-retries) instead of a misleading 401.

RL / track feedback

• Signals documented as like / unlike / open_deezer / clear.
• Set-vote semantics: a track's current vote is its only contribution — like↔unlike reverts-then-applies (no double-count), clear (un-vote) nets zero, re-send is idempotent.
• Revert subtracts the exact stored feature vector, clamped at the Beta(1,1) prior with events ≥ 0; a seq tiebreaker makes "latest vote" deterministic.
• New GET /api/feedback/tracks/ read-back endpoint that restores 👍/👎 button state across reloads / re-sorts / refetches.

Data / UX

• listening_history now stores full track dicts (legacy "Name - Artist" strings still read) → rich profile cards.
• Frontend README: persisted/un-votable feedback, rich listening cards, instant dark/light theme, username-or-email login.

Correctness fix

• ARCHITECTURE diagrams said Bcrypt; code uses Django's default PBKDF2 — corrected both references.

Files

README.md, ARCHITECTURE.md, backend/README.md, frontend/README.md, modal_inference/README.md, index.html

Notes

• Docs-only; no code changes. Code-fence/<details> balance verified; frontend/README.md run through the project prettier (root docs are outside the format script's scope by repo convention).
• Describes behavior that lands with PR feat(frontend): profile/results UX overhaul + persisted track feedback #60 (clear/un-vote + /api/feedback/tracks/); merge after/with feat(frontend): profile/results UX overhaul + persisted track feedback #60.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
moodify-emotion-music-app	Ignored		Jun 28, 2026 12:04pm

[netlify]

✅ Deploy Preview for moodify-emotion-music-app ready!

Name	Link
🔨 Latest commit	5bee5f7
🔍 Latest deploy log	https://app.netlify.com/projects/moodify-emotion-music-app/deploys/6a410de3447a0d000821e366
😎 Deploy Preview	https://deploy-preview-61--moodify-emotion-music-app.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[gemini-code-assist]

Code Review

This pull request introduces 'set-vote' feedback semantics (like, unlike, and clear/un-vote) to the reinforcement learning loop, allowing users to toggle or switch votes with precise posterior reconciliation. It adds a new endpoint GET /api/feedback/tracks/ to persist and restore vote states across reloads, updates the user profile to store rich listening history cards, and improves dark-mode styling for Material-UI inputs. The code review highlights two critical performance improvements: optimizing sequential database operations in feedback_views.py into a single roundtrip to prevent race conditions, and moving track_id into the MongoDB time-series meta sub-document in feedback_store.py to enable efficient compound indexing.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

When a user switches their vote (e.g., from like to unlike), this block performs two separate database reads and two separate database saves sequentially (one inside _revert_posterior and one inside _apply_posterior). This results in redundant database roundtrips and increases the risk of race conditions (lost updates) under concurrent requests.\n\nWe can optimize this into a single database roundtrip by loading the UserProfile once, applying both the revert and update operations to the taste_profile dictionary in memory, and then saving the document once.

        revert_active = prior_signal in ("like", "unlike") and prior_signal != signal
        apply_active = signal in ("like", "unlike") and signal != prior_signal
        if revert_active or apply_active:
            try:
                profile = UserProfile.objects(username=username).first()
                if profile is not None:
                    taste_profile = profile.taste_profile or {}
                    if revert_active and prior.get("features"):
                        taste_profile = bandit.revert_posterior(taste_profile, prior.get("features"), prior_signal)
                    if apply_active and new_features:
                        taste_profile = bandit.update_posterior(taste_profile, new_features, signal)
                    profile.taste_profile = taste_profile
                    profile.save()
            except Exception:  # noqa: BLE001
                logger.warning("taste_profile update failed for user=%s (silently skipping)", username)

[gemini-code-assist]

In MongoDB time-series collections, fields outside the metaField (like track_id and features) are treated as measurement fields. Secondary indexes on measurement fields are either unsupported (MongoDB < 6.0) or have significant performance and indexing restrictions.\n\nSince track_id is a stable identifier used as a primary query filter in get_active_vote and query_track_feedback, it should be placed inside the meta sub-document (e.g., meta.track_id). This allows creating a highly efficient compound index on [("meta.username", 1), ("meta.track_id", 1), ("ts", -1)] across all MongoDB versions, preventing costly collection scans as the feedback log grows.

Suggested change

	coll.insert_one({
	"ts": datetime.now(timezone.utc),
	"seq": time.time_ns(),
	"meta": {
	"username": username,
	"signal": signal,
	"context_emotion": context_emotion,
	},
	"track_id": track_id,
	"features": list(features) if features is not None else None,
	})
	coll.insert_one({
	"ts": datetime.now(timezone.utc),
	"seq": time.time_ns(),
	"meta": {
	"username": username,
	"signal": signal,
	"context_emotion": context_emotion,
	"track_id": track_id,
	},
	"features": list(features) if features is not None else None,
	})