How yaongmeow/sse-test-for-fe works
1. What this repo is
- This is a browser-based React + TypeScript dashboard built with Vite.
- Its job is to call a backend “generate” endpoint, consume SSE-like streaming output, and show the progress of a GitHub repository generation job.
2. Runtime boundary
- Everything in src/ runs in the browser.
- The only external runtime dependency is a backend API reached through VITE_API_BASE_URL, specifically POST /generate/stream.
3. Application bootstrap
- index.html is the Vite entry page.
- src/main.tsx mounts the React app.
- src/App.tsx is the top-level coordinator for UI state, request lifecycle, and result presentation.
- src/styles.css holds the global styling for the dashboard layout.
4. Primary orchestration layer: App.tsx
- App is the central stateful component that likely owns:
- request start/cancel controls,
- streaming progress text,
- parsed graph payloads,
- final response state,
- tech stack metadata,
- render-state transitions from “streaming” to “complete” or error.
- In architecture terms, it is the composition root for the UI.
5. Network + streaming data flow
- The app sends a fetch() request to POST /generate/stream.
- Instead of waiting for a full response, it reads the response body through a ReadableStream reader.
- Stream chunks are buffered and parsed into discrete SSE-style messages, so the UI can update incrementally as data arrives.
6. Streaming parser boundary: src/utils/sse.ts
- This utility is the key protocol adapter between the backend stream and the React state model.
- It maintains a chunk buffer and splits incoming data on \n\n or \r\n\r\n.
- This isolates protocol handling from UI code, which is important for diagramming: backend stream format → parser → UI events/state.
- src/utils/sse.test.ts validates this parser behavior.
7. Message types and UI semantics
- The README indicates three important stream payload categories:
- explanation_chunk → appended to the explanation area as incremental text,
- graph → shown as JSON preview while streaming,
- complete → final payload that replaces/sets the finished diagram, explanation, and graph.
- The complete event also exposes tech_stacks or techStacks, which are rendered as a separate list.
8. Visualization component boundary: MermaidPreview.tsx
- src/components/MermaidPreview.tsx is the diagram renderer.
- It uses the mermaid package to convert the final diagram definition into a visual diagram.
- This component is likely a pure presentation boundary: it receives diagram text and renders it, rather than owning business logic.
9. User interaction and cancellation
- The dashboard supports request cancellation via AbortController.
- That means the UI can stop an in-flight generation stream without waiting for the backend to finish.
- In an architecture diagram, this is a control path from user action → abort signal → fetch cancellation.
10. State presentation areas
- The UI is organized around multiple output regions:
- streaming explanation text,
- graph JSON preview during generation,
- final diagram preview,
- final response JSON view,
- tech stack list.
- This is a progress dashboard, not a one-shot form: the main distinction is live stream state versus final result state.
11. Tooling and build/test pipeline
- The project uses TypeScript, Vite, and npm.
- npm run dev runs the local frontend server.
- npm run build produces the production bundle.
- npm run test validates the stream parser logic, which is the most critical non-visual subsystem.
12. How to draw the architecture
- A useful diagram would show:
- Browser/UI shell (index.html → main.tsx → App.tsx)
- UI controls and state in App
- Outbound HTTP/SSE request to backend /generate/stream
- Streaming parser in utils/sse.ts
- Incremental render paths for explanation, graph preview, and final response
- Mermaid rendering as a separate visualization component
- AbortController as a cancellation/control edge
- Tests covering the parser boundary
Main entry points: App.tsx App · sse.ts SSE Parser · main.tsx main.tsx · MermaidPreview.tsx MermaidPreview
Components 16
Browser UI
Vite-mounted React dashboard running in the browser.
- index.html · Vite entry document that boots the frontend.
index.html - main.tsx · Mounts the React app into the page.
src/main.tsx - App · Top-level stateful coordinator for requests, streaming state, and final results.
src/App.tsx - styles.css · Global dashboard layout and presentation styles.
src/styles.css - Explanation · Incremental explanation text shown while the stream is active.
- Graph JSON · Live JSON preview of the graph payload while generation is in progress.
- Final Response · Completed response state for the final diagram and associated data.
- Tech Stacks · Rendered list of stack metadata from the completed payload.
- MermaidPreview · Presentation boundary that turns final diagram text into a rendered diagram.
src/components/MermaidPreview.tsx
Stream Pipeline
HTTP request, cancellation, parsing, and test coverage for the SSE-like backend stream.
- Generate API · Backend POST /generate/stream endpoint consumed by the dashboard.
- Fetch Stream · Browser fetch call that opens the streaming response.
- AbortController · Cancels an in-flight generation stream from the UI.
- SSE Parser · Buffers chunks and splits SSE-style messages into discrete events.
src/utils/sse.ts - Chunk Buffer · Internal buffering for partial stream frames before dispatch.
- Parser Tests · Validates stream parsing behavior and message framing.
src/utils/sse.test.ts
Diagram Rendering
Final diagram presentation via Mermaid.
- Mermaid · Third-party Mermaid renderer used to visualize the final diagram.
Connections 20
- index.html → main.tsx: loads · The Vite entry document starts the React application.
- main.tsx → App: mounts · Bootstraps the dashboard component tree.
- App → styles.css: uses · Applies global dashboard styling.
- App → Fetch Stream: starts · Creates the streaming request when generation begins.
- Fetch Stream → Generate API: POST /generate/stream · Sends the generation request to the backend stream endpoint.
- App → AbortController: cancels · Uses an abort signal to stop an in-flight request.
- AbortController → Fetch Stream: aborts · Terminates the active fetch stream.
- Fetch Stream → SSE Parser: chunks · Streams response body chunks into the parser.
- SSE Parser → Chunk Buffer: buffers · Accumulates partial frames until a full message boundary is found.
- SSE Parser → Explanation: explanation_chunk · Appends incremental explanation text to the UI.
- SSE Parser → Graph JSON: graph · Updates the live JSON graph preview during streaming.
- SSE Parser → Final Response: complete · Replaces interim state with the finished payload.
- SSE Parser → Tech Stacks: tech_stacks · Feeds the completed tech stack metadata into the UI.
- App → Explanation: renders · Coordinates presentation of the active explanation stream.
- App → Graph JSON: renders · Coordinates the streaming graph preview state.
- App → Final Response: renders · Shows the completed response state after streaming ends.
- App → Tech Stacks: renders · Displays the final tech stack list.
- App → MermaidPreview: passes diagram · Supplies the final diagram definition to the visualizer.
- MermaidPreview → Mermaid: renders with · Delegates diagram drawing to the Mermaid library.
- Parser Tests → SSE Parser: verifies · Confirms the stream parser behavior and framing rules.