# The Next.js Interface & Diagrams

> Architecture of the frontend application, focusing on real-time updates via WebSockets and automated Mermaid diagram rendering for repository visualization.

- Repository: AsyncFuncAI/deepwiki-open
- GitHub: https://github.com/AsyncFuncAI/deepwiki-open
- Human wiki: https://grok-wiki.com/public/wiki/asyncfuncai-deepwiki-open-4d1f22320747
- Complete Markdown: https://grok-wiki.com/public/wiki/asyncfuncai-deepwiki-open-4d1f22320747/llms-full.txt

## Source Files

- `src/app/page.tsx`
- `src/components/Mermaid.tsx`
- `src/components/WikiTreeView.tsx`
- `src/components/ConfigurationModal.tsx`
- `src/app/globals.css`
- `src/app/layout.tsx`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:
- [src/app/page.tsx](src/app/page.tsx)
- [src/app/[owner]/[repo]/page.tsx](src/app/[owner]/[repo]/page.tsx)
- [src/components/Mermaid.tsx](src/components/Mermaid.tsx)
- [src/components/Markdown.tsx](src/components/Markdown.tsx)
- [src/components/WikiTreeView.tsx](src/components/WikiTreeView.tsx)
- [src/utils/websocketClient.ts](src/utils/websocketClient.ts)
- [src/app/globals.css](src/app/globals.css)
</details>

# The Next.js Interface & Diagrams

The **deepwiki-open** frontend is a high-performance Next.js application that provides a rich, interactive environment for exploring repository documentation. It features a unique Japanese-inspired aesthetic ("Wabi-sabi") characterized by warm paper textures, soft color palettes, and minimalist design. The interface is built for real-time engagement, utilizing WebSockets for streaming content generation and automated Mermaid diagram rendering to visualize complex codebase structures.

This architectural approach ensures that users can see the wiki take shape in real-time while providing deep insights into repository logic through dynamically generated visualizations.

## Frontend Architecture Overview

The application is structured using the Next.js App Router, with a clear separation between landing pages, repository-specific views, and shared components.

### Core Component Hierarchy

The interface is composed of several high-order components that manage state and rendering:

| Component | Responsibility |
| :--- | :--- |
| `RepoWikiPage` | The primary container for repository visualization, managing the wiki structure and page content state. |
| `WikiTreeView` | A hierarchical navigation sidebar that reflects the logical structure of the repository. |
| `Markdown` | The rendering engine for wiki pages, supporting GFM, math, and embedded diagrams. |
| `Mermaid` | A specialized component for rendering and interacting with Mermaid.js diagrams. |
| `Ask` | An AI-powered chat interface for querying the repository directly. |

Sources: [src/app/[owner]/[repo]/page.tsx:177-240](), [src/components/Markdown.tsx:16-196]()

## Real-time Communication via WebSockets

To provide a responsive "streaming" experience, the frontend utilizes WebSockets for communication with the backend agent. This replaces traditional polling or long-lived HTTP requests, allowing for instantaneous UI updates as the AI generates content.

### WebSocket Integration Pattern

The application uses a centralized `websocketClient` utility to manage connections. In `RepoWikiPage`, WebSockets are used for two primary tasks:
1.  **Structure Determination**: Analyzing the repository file tree and README to build the initial wiki hierarchy.
2.  **Content Generation**: Streaming the Markdown content for individual wiki pages.

```mermaid
sequenceDiagram
    participant UI as RepoWikiPage
    participant WS as WebSocketClient
    participant BE as Backend Agent
    
    UI->>WS: createChatWebSocket(request)
    WS->>BE: Open Connection (ws://.../ws/chat)
    BE-->>WS: Connection Established
    WS->>BE: Send JSON Request
    loop Streaming Content
        BE-->>WS: Message Chunk
        WS-->>UI: onMessage(data)
        UI->>UI: Update State (Live Preview)
    end
    BE-->>WS: Close Connection
    WS-->>UI: onClose()
```
Sources: [src/utils/websocketClient.ts:43-75](), [src/app/[owner]/[repo]/page.tsx:542-602]()

## Automated Mermaid Diagram Rendering

One of the standout features of deepwiki-open is its ability to automatically generate and render Mermaid diagrams. These diagrams are extracted from Markdown code blocks and rendered using a custom `Mermaid` component.

### Visualization Features

*   **Dynamic Theming**: Diagrams automatically switch between light and dark modes based on the application's global theme (e.g., using `--fuji` purple and `--washi` paper colors).
*   **Interactive Zooming**: Utilizing `svg-pan-zoom` and a custom `FullScreenModal`, users can inspect complex diagrams in detail.
*   **Japanese Aesthetic**: The `Mermaid` component injects custom CSS to ensure diagrams match the "Wabi-sabi" design system.

### Mermaid Component Logic

The `Mermaid` component handles the lifecycle of diagram rendering, from initialization to error handling.

```mermaid
stateDiagram-v2
    [*] --> Initializing: Chart Prop Received
    Initializing --> Rendering: mermaid.render()
    Rendering --> Success: SVG Generated
    Rendering --> Error: Syntax Error
    Success --> PanZoom: zoomingEnabled=true
    Success --> Clickable: zoomingEnabled=false
    Clickable --> FullScreen: On Click
    Error --> [*]
```
Sources: [src/components/Mermaid.tsx:6-170](), [src/components/Markdown.tsx:129-139]()

## Design System & Aesthetics

The interface adheres to a strict "Japanese Aesthetic" defined in `globals.css`. This system uses semantic CSS variables to maintain consistency across the application.

### Key Visual Tokens

| Token | Light Mode (`--washi`) | Dark Mode (`--charcoal`) |
| :--- | :--- | :--- |
| `--background` | `#f8f4e6` (Warm Paper) | `#1a1a1a` (Deep Charcoal) |
| `--accent-primary` | `#9b7cb9` (Fuji Purple) | `#9370db` (Soft Lavender) |
| `--border-color` | `#e0d8c8` (Soft Beige) | `#2c2c2c` (Dark Grey) |

Sources: [src/app/globals.css:6-32]()

The interface uses modern typography (Noto Sans JP and Geist Mono) and subtle paper textures to create a premium, calm reading experience that encourages deep exploration of code architecture.

Sources: [src/app/globals.css:39-68]()

## Summary

The **deepwiki-open** interface is a sophisticated Next.js application that leverages WebSockets for real-time reactivity and Mermaid.js for automated architectural visualization. By combining a unique Japanese design philosophy with robust engineering patterns, it transforms raw repository data into a beautiful, interactive knowledge base.

Sources: [src/app/[owner]/[repo]/page.tsx:177-280](), [src/components/Mermaid.tsx:306-487]()