# yaongmeow/sse-test-for-fe architecture

> Architecture diagram of the GitHub repository yaongmeow/sse-test-for-fe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaongmeow/sse-test-for-fe
- Repository: https://github.com/yaongmeow/sse-test-for-fe

## Overview

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: [`src/App.tsx`](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/App.tsx) (App), [`src/utils/sse.ts`](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/utils/sse.ts) (SSE Parser), [`src/main.tsx`](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/main.tsx) (main.tsx), [`src/components/MermaidPreview.tsx`](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/components/MermaidPreview.tsx) (MermaidPreview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser_ui["Browser UI"]
  node_index_html["index.html<br/>entry page<br/>[index.html]"]
  node_main_tsx["main.tsx<br/>bootstrap<br/>[main.tsx]"]
  node_app_tsx["App<br/>ui coordinator<br/>[App.tsx]"]
  node_styles_css["styles.css<br/>global styles<br/>[styles.css]"]
  node_live_explanation["Explanation<br/>stream view"]
  node_graph_preview["Graph JSON<br/>stream view"]
  node_final_payload["Final Response<br/>result view"]
  node_tech_stacks["Tech Stacks<br/>result view"]
  node_mermaid_preview["MermaidPreview<br/>diagram component<br/>[MermaidPreview.tsx]"]
end

subgraph group_stream_pipeline["Stream Pipeline"]
  node_generate_api{{"Generate API<br/>backend endpoint"}}
  node_fetch_request["Fetch Stream<br/>network request"]
  node_abort_ctrl(("AbortController<br/>cancellation"))
  node_sse_parser["SSE Parser<br/>stream adapter<br/>[sse.ts]"]
  node_chunk_buffer["Chunk Buffer<br/>parser state"]
  node_parser_tests["Parser Tests<br/>unit test<br/>[sse.test.ts]"]
end

subgraph group_diagram_rendering["Diagram Rendering"]
  node_mermaid_runtime["Mermaid<br/>rendering library"]
end

node_index_html -->|"loads"| node_main_tsx
node_main_tsx -->|"mounts"| node_app_tsx
node_app_tsx -->|"uses"| node_styles_css
node_app_tsx -->|"starts"| node_fetch_request
node_fetch_request -->|"POST /generate/stream"| node_generate_api
node_app_tsx -->|"cancels"| node_abort_ctrl
node_abort_ctrl -.->|"aborts"| node_fetch_request
node_fetch_request -->|"chunks"| node_sse_parser
node_sse_parser -->|"buffers"| node_chunk_buffer
node_sse_parser -->|"explanation_chunk"| node_live_explanation
node_sse_parser -->|"graph"| node_graph_preview
node_sse_parser -->|"complete"| node_final_payload
node_sse_parser -->|"tech_stacks"| node_tech_stacks
node_app_tsx -->|"renders"| node_live_explanation
node_app_tsx -->|"renders"| node_graph_preview
node_app_tsx -->|"renders"| node_final_payload
node_app_tsx -->|"renders"| node_tech_stacks
node_app_tsx -->|"passes diagram"| node_mermaid_preview
node_mermaid_preview -->|"renders with"| node_mermaid_runtime
node_parser_tests -.->|"verifies"| node_sse_parser

click node_index_html "https://github.com/yaongmeow/sse-test-for-fe/blob/main/index.html"
click node_main_tsx "https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/main.tsx"
click node_app_tsx "https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/App.tsx"
click node_styles_css "https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/styles.css"
click node_sse_parser "https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/utils/sse.ts"
click node_parser_tests "https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/utils/sse.test.ts"
click node_mermaid_preview "https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/components/MermaidPreview.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_html,node_main_tsx,node_app_tsx,node_styles_css,node_live_explanation,node_graph_preview,node_final_payload,node_tech_stacks,node_mermaid_preview toneBlue
class node_generate_api,node_fetch_request,node_abort_ctrl,node_sse_parser,node_chunk_buffer,node_parser_tests toneAmber
class node_mermaid_runtime toneMint
```

## Components

### Browser UI

Vite-mounted React dashboard running in the browser.

- [index.html](https://github.com/yaongmeow/sse-test-for-fe/blob/main/index.html): entry page · Vite entry document that boots the frontend. · `index.html`
- [main.tsx](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/main.tsx): bootstrap · Mounts the React app into the page. · `src/main.tsx`
- [App](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/App.tsx): ui coordinator · Top-level stateful coordinator for requests, streaming state, and final results. · `src/App.tsx`
- [styles.css](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/styles.css): global styles · Global dashboard layout and presentation styles. · `src/styles.css`
- **Explanation**: stream view · Incremental explanation text shown while the stream is active.
- **Graph JSON**: stream view · Live JSON preview of the graph payload while generation is in progress.
- **Final Response**: result view · Completed response state for the final diagram and associated data.
- **Tech Stacks**: result view · Rendered list of stack metadata from the completed payload.
- [MermaidPreview](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/components/MermaidPreview.tsx): diagram component · 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 endpoint · Backend POST /generate/stream endpoint consumed by the dashboard.
- **Fetch Stream**: network request · Browser fetch call that opens the streaming response.
- **AbortController**: cancellation · Cancels an in-flight generation stream from the UI.
- [SSE Parser](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/utils/sse.ts): stream adapter · Buffers chunks and splits SSE-style messages into discrete events. · `src/utils/sse.ts`
- **Chunk Buffer**: parser state · Internal buffering for partial stream frames before dispatch.
- [Parser Tests](https://github.com/yaongmeow/sse-test-for-fe/blob/main/src/utils/sse.test.ts): unit test · Validates stream parsing behavior and message framing. · `src/utils/sse.test.ts`

### Diagram Rendering

Final diagram presentation via Mermaid.

- **Mermaid**: rendering library · Third-party Mermaid renderer used to visualize the final diagram.

## Connections

- 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.
