Web Archive

Relevant source files

The following files were used as context for generating this wiki page: - [packages/web/package.json](https://github.com/hiing/web-archive/blob/main/packages/web/package.json) - [packages/web/index.html](https://github.com/hiing/web-archive/blob/main/packages/web/index.html) - [packages/web/src/pages/(layout)/page.[slug].tsx](https://github.com/hiing/web-archive/blob/main/packages/web/src/pages/%28layout)/page.[slug].tsx) - [packages/web/src/pages/showcase/page.[slug].tsx](https://github.com/hiing/web-archive/blob/main/packages/web/src/pages/showcase/page.%5Bslug%5D.tsx) - [packages/web/src/data/page.ts](https://github.com/hiing/web-archive/blob/main/packages/web/src/data/page.ts) - [packages/server/src/api/pages.ts](https://github.com/hiing/web-archive/blob/main/packages/server/src/api/pages.ts) - [packages/web/src/assets/locales/en/translation.json](https://github.com/hiing/web-archive/blob/main/packages/web/src/assets/locales/en/translation.json)

# Web Client Architecture The Web Client is a modern single-page application (SPA) built with React, serving as the primary user interface for viewing and interacting with archived web pages. It is responsible for fetching data from the server backend and presenting it to the user. The client supports features like folder-based organization, searching, and different viewing modes for archived content, including a sandboxed `iframe` mode and a simplified "readability" mode. The application is built using Vite and styled with Tailwind CSS. It communicates with a Hono-based server to retrieve page metadata and the archived HTML content. ## Core Technologies and Dependencies The web client is built on a modern frontend stack. The key libraries and their roles are defined in the `package.json` file. | Dependency | Role | Source - **React** | Core UI library for building the user interface. | `packages/web/package.json` - `@generouted/react-router` | File-based routing for React, simplifying route definitions. | `packages/web/package.json` - `react-router-dom` | Core routing components for the React application. | `packages/web/package.json` - `ahooks` | A library of React Hooks, used here for data fetching (`useRequest`). | `packages/web/src/pages/(layout)/page.[slug].tsx:2` - `@mozilla/readability` | Parses HTML to extract the main article content for "Read Mode". | `packages/web/package.json:7` - `i18next` / `react-i18next` | Framework for internationalization (i18n). | `packages/web/src/pages/(layout)/page.[slug].tsx:4` - `tailwindcss` | A utility-first CSS framework for styling. | `packages/web/package.json` *Sources: [packages/web/package.json](), [packages/web/src/pages/(layout)/page.[slug].tsx]()* ## Application Structure The web client is initialized from `packages/web/index.html`, which is a standard HTML5 document that mounts the React application into a `

`. ```html Web Archive

``` *Sources: [packages/web/index.html:1-11]()* ### Routing The application uses `@generouted/react-router` for file-based routing. This means the URL structure of the application mirrors the file system layout inside `packages/web/src/pages`. The diagram below illustrates the main routes and their corresponding page components. ```mermaid graph TD subgraph Routing Home["/"] --> Folder["/folder/:slug"] Folder --> Page["/page/:slug"] ShowcaseFolder["/showcase/folder"] --> ShowcasePage["/showcase/page/:slug"] end ``` *Sources: [packages/web/package.json](), [packages/web/src/pages/(layout)/page.[slug].tsx](), [packages/web/src/pages/showcase/page.[slug].tsx]()* - **`/page/:slug`**: The primary route for viewing a saved page. The `slug` corresponds to the page's unique ID. - **`/showcase/page/:slug`**: A public-facing route to view pages that have been marked for "showcase". Navigation and parameter access are handled by hooks like `useNavigate` and `useParams` provided by the router. *Sources: [packages/web/src/pages/(layout)/page.[slug].tsx:9-10]()* ## Data Flow and State Management ### Data Fetching Data fetching from the server API is managed by the `useRequest` hook from the `ahooks` library. This hook simplifies handling loading states, errors, and caching. Data-fetching logic is abstracted into functions within `packages/web/src/data/page.ts`. Key data fetching functions include: - `getPageDetail(id: string)`: Fetches metadata for a specific page. - `deletePage(page: Page)`: Deletes a page. - `getPageContent(pageId: string)`: Fetches the raw HTML content of an archived page. These functions make authenticated requests to the backend, attaching a JWT from `localStorage` to the `Authorization` header. *Sources: [packages/web/src/data/page.ts](), [packages/web/src/pages/(layout)/page.[slug].tsx:13-25]()* ### API Interaction for Page Rendering The following sequence diagram shows the process of fetching and rendering an archived page. ```mermaid sequenceDiagram participant User participant ReactComponent as "ArchivePage Component" participant DataLayer as "Data Layer (page.ts)" participant ServerAPI as "Server API" participant Browser as "Browser" User->>ReactComponent: Navigates to /page/:slug ReactComponent->>+DataLayer: useRequest(getPageDetail, slug) DataLayer->>+ServerAPI: GET /api/pages/detail?id={slug} ServerAPI-->>-DataLayer: Page Details (JSON) DataLayer-->>ReactComponent: Returns page details ReactComponent->>+DataLayer: useRequest(getPageContent, slug) DataLayer->>+ServerAPI: GET /api/pages/content?pageId={slug} ServerAPI-->>-DataLayer: Page Content (HTML) DataLayer-->>ReactComponent: Returns page HTML ReactComponent->>+Browser: useObjectURL(html) Browser-->>-ReactComponent: blob:http://... alt Read Mode is ON ReactComponent->>Browser: Renders ReadabilityPageContent else Read Mode is OFF ReactComponent->>Browser: Renders IframePageContent with blob URL end ``` *Sources: [packages/web/src/pages/(layout)/page.[slug].tsx](), [packages/server/src/api/pages.ts](), [packages/web/src/data/page.ts]()* ### Global State Global state, such as the `readMode` toggle, is managed via React's Context API. The `AppContext` provides this state to components throughout the application. *Sources: [packages/web/src/pages/(layout)/page.[slug].tsx:70]()* ## Page Rendering The web client offers two distinct modes for rendering archived content, controlled by the `readMode` application state. ### Iframe Mode This is the default mode. The raw HTML content of the archived page is fetched from the server and a local blob URL is created using `URL.createObjectURL()`. This URL is then used as the `src` for a sandboxed `