Add fundamentals track, scaling guide, flashcards, and a local AI stu… - #5
Conversation
…dy assistant Bring the conceptual on-ramp from the system-design-primer into the repo, in Grokking's pattern-based voice with original Mermaid diagrams, plus an optional offline study assistant. - fundamentals/: 13-page conceptual track (performance vs scalability, latency vs throughput, availability vs consistency, consistency/availability patterns with the "nines" table, DNS, reverse proxy vs load balancer, application layer, databases, asynchronism, communication, security), each with a diagram and links to the patterns that apply it. - guides/scaling-to-millions-of-users.md: an evolutionary walkthrough with a diagram per stage (single server -> LB -> replicas -> cache -> CDN -> shard -> async -> multi-region). - cheat-sheets/flashcards.md: a spaced-repetition Q&A deck. - tools/study-assistant/: a 100% offline RAG CLI over the repo's markdown via Ollama (semantic search + grounded answers with citations, plus a quiz mode), with graceful keyword-search fallback when no model is present. - Wiring: README (Fundamentals, Guides, Study assistant sections + contents), glossary terms, richer estimation tables (fuller powers-of-two, nines), and resources (engineering blogs + system-design-primer attribution). Ignore the generated index and Python artifacts. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Turn the CLI study assistant into a browsable app so learners can go through every resource one by one, chat with the local LLM about the page they're reading, and self-test — all still 100% local. - study_assistant.py: new `serve` command + a stdlib ThreadingHTTPServer with a dependency-free Markdown->HTML renderer (headings, tables, lists, code, blockquotes, mermaid, internal-link rewriting) and JSON/NDJSON APIs: /api/status, /api/toc, /api/page (with prev/next), /api/quiz, streaming /api/ask, /api/grade, /api/gen-question. Reuses the existing retrieval, Ollama, and flashcard code; binds to 127.0.0.1 only. - ui/index.html: single-file SPA (inline CSS/JS). Guided sidebar across fundamentals -> patterns -> guides -> questions -> cheat sheets -> deep dives with Previous/Next and a saved progress tracker; content pane with rendered Mermaid diagrams; "Ask the AI" panel with grounded, cited, streaming answers and quick chips; "Quiz me" panel that grades typed answers and can generate a question from the current page. Degrades gracefully with no model (keyword search) and offline (diagrams show as source). - READMEs: document `serve` and the three UI capabilities; note the one CDN fetch (the Mermaid library) while all study data stays local. Verified: endpoints via curl, and the UI in a browser (nav, prev/next, sequence + flowchart diagrams rendered, grounded answers with sources). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Turn the assistant from read+ask into practice+retain. - Interview Mode: the local LLM plays interviewer. New streaming /api/interview (opens on the current topic, asks one grounded question at a time, probes trade-offs) and /api/interview-score (grades the transcript against the framework: verdict, covered well, gaps, practice next). Retrieval-grounded; degrades to a "pull a model / self-drive with the framework" note when no model is present. - Spaced repetition: the quiz now schedules cards with an SM-2/Leitner-lite algorithm in localStorage. Rate each card Again/Hard/Good/Easy; "Review due" pulls everything due across all topics; a stats strip shows Due/Learned/New. - UI: third "Interview" tab, rating buttons, review-due flow, and a small markdown renderer for the scored feedback. Verified in-browser (no console errors; scheduling persists; graceful no-model fallback) and via curl. - READMEs updated for both features. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fill the LLD/OOD gap: the interview round about how classes fit together inside one service, complementing the system-design (HLD) questions. - low-level-design/: index (SOLID + the approach + patterns worth knowing), a _template, and six classic problems, each with a Mermaid class/state diagram, key methods/flow, the design patterns it exercises, and concurrency edge cases: parking lot, elevator system, LRU cache, rate limiter (code level), vending machine (FSM), and an in-memory key-value store. - Cross-links to the HLD counterparts (patterns/, questions/, deep-dives/). - Wiring: README section + contents, resources "in this repo", and the study UI TOC (new "Low-level design" section, 129 pages total). Verified: links + fences pass; classDiagram and stateDiagram-v2 render as SVG in the web UI; TOC + sidebar include the new section. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Richer visuals and a faster, fully-offline study UI. - Diagrams: every deep dive (14) and the 8 remaining patterns now open with a Mermaid diagram (architecture / data flow / sequence), each validated with mermaid.parse. Questions and fundamentals were already fully diagrammed. - Search: new /api/search over a lightweight in-memory index of titles + headings + body (works without `build`); header search box with a ranked dropdown, arrow-key selection, and `/` to focus. - Keyboard nav: `j` / `k` move to the next / previous page. - Offline: Mermaid is vendored in ui/vendor/ and served locally, so the web UI makes zero outbound requests (CDN kept only as a missing-file fallback). The server gained a safe /vendor/ static route. - READMEs: privacy note now states fully-offline (no CDN); browse section notes search + shortcuts. Verified: all 22 new diagrams parse; search + vendor asset + path-traversal guard tested via curl; UI reload confirms Mermaid loads from /vendor. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Protect the shipped tool code with tests and continuous integration. - tests/test_study_assistant.py: 16 tests covering the markdown->HTML renderer (headings, tables, code escaping, nested lists, internal-link rewriting, XSS escaping), the flashcard parser, keyword retrieval ranking, the resource TOC, search ranking, and a repo-wide structural validation of every Mermaid block (valid header + balanced subgraph/end). - Refactor: extracted a module-level search() from the HTTP handler so it can be unit-tested directly. - .github/workflows/tests.yml: runs pytest on push/PR/dispatch. - requirements-dev.txt + a Development section in the README; ignore .pytest_cache. All 16 tests pass locally. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Thank you for this, and I am sorry it sat so long without a reply. The delay was mine and it does not reflect on the work you put in. I have gone through all 59 files. Here is where I landed, and why. Taken: the flashcards. This is a genuinely good addition. It is now in #7, with you credited as co-author on the commit. I reworked it before opening that PR for two reasons. The deck linked to Please open a separate PR for the diagrams. The Mermaid diagrams you added to the existing pattern and deep-dive files are the strongest part of this submission and I would like to have them. They are bundled here with changes I cannot take, which is the main reason this PR was hard to act on. A PR containing only those 22 file changes is one I would review quickly. Not taking: Not taking:
I know that is most of a large PR declined, and I would rather say so plainly than leave it sitting for another month. The flashcards are in and credited. If you want to send the diagrams as their own PR, that is one I want. |
2 participants
…dy assistant
Bring the conceptual on-ramp from the system-design-primer into the repo, in Grokking's pattern-based voice with original Mermaid diagrams, plus an optional offline study assistant.