| # Architecture |
|
|
| ## Overview |
|
|
| The collab-editor is a collaborative article editor built for Hugging Face Spaces. It runs as a single Docker container serving both the backend (Express + Hocuspocus) and the frontend (React + TipTap). |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────┐ |
| │ Docker Container (port 8080) │ |
| │ │ |
| │ ┌──────────────────┐ ┌────────────────────────────┐ │ |
| │ │ Express Server │ │ Hocuspocus (Y.js collab) │ │ |
| │ │ │ │ │ │ |
| │ │ /api/* │ │ /collab (WebSocket) │ │ |
| │ │ /published/* │ │ │ │ |
| │ │ /editor │ │ │ │ |
| │ │ / (published) │ │ │ │ |
| │ └──────────────────┘ └────────────────────────────┘ │ |
| │ │ |
| │ ┌──────────────────┐ ┌────────────────────────────┐ │ |
| │ │ Publisher │ │ Frontend (static) │ │ |
| │ │ (HTML renderer) │ │ /editor -> SPA │ │ |
| │ │ (PDF generator) │ │ React + TipTap │ │ |
| │ └──────────────────┘ └────────────────────────────┘ │ |
| └─────────────────────────────────────────────────────────┘ |
| ``` |
|
|
| ## Key directories |
|
|
| | Path | Description | |
| |------|-------------| |
| | `backend/src/server.ts` | Entry point: imports `createApp()`, starts listener, signal handlers | |
| | `backend/src/create-app.ts` | Express app factory: routes, Hocuspocus, WebSocket, middleware | |
| | `backend/src/publisher/` | HTML rendering, PDF generation, bibliography formatting | |
| | `backend/src/publisher/html-renderer.ts` | Converts TipTap JSON to static HTML page | |
| | `backend/src/publisher/extensions.ts` | Server-side TipTap extensions (mirrors frontend) | |
| | `backend/src/shared/component-defs.ts` | Shared component definitions (single source of truth) | |
| | `backend/src/utils.ts` | Shared utilities: `docPath()`, `sanitizeName()`, injectable `DATA_DIR` | |
| | `backend/src/auth.ts` | OAuth flow, token extraction, user resolution | |
| | `backend/src/hf-storage.ts` | HF dataset sync (push/pull documents and assets) | |
| | `frontend/src/editor/` | TipTap editor, toolbars, components | |
| | `frontend/src/editor/components/registry.ts` | Component registry (imports from shared defs) | |
| | `frontend/src/styles/` | All CSS files | |
|
|
| ## Styling architecture |
|
|
| ### CSS layers |
|
|
| The project uses five CSS layers, loaded in this order by `main.tsx`: |
|
|
| 1. **Template foundation** (`_variables.css`, `_reset.css`, `_base.css`, `_layout.css`, `_print.css`, `components/*`) |
| - Defines the article's visual identity (typography, grid, components) |
| - Uses CSS custom properties (`--text-color`, `--surface-bg`, `--primary-color`, etc.) |
| - Layout tokens centralize grid math (`--layout-toc-width`, `--layout-content-width`, `--layout-gap`, breakpoints) |
| - Shared between the editor preview and the published output |
|
|
| 2. **Editor chrome** (`_ui.css`) |
| - Styles the editor UI: top-bar, sidebars, dialogs, chat panel, embed studio |
| - Uses `--ed-*` custom properties for the dark editor theme |
| - Only loaded in the editor, never in published output |
|
|
| 3. **Design tokens** (`tokens.css`) |
| - Light/dark theming tokens for both editor and article |
| - Text, background, border, accent, code highlighting, danger, shadows |
| - Supports `data-theme` attribute and `prefers-color-scheme` media query |
| - Shared between editor and published output (injected by publisher) |
|
|
| 4. **Shared article styles** (`article.css`, `toc.css`) |
| - Article content styles shared between editor preview and published output |
| - `article.css` includes wrapper components (Note, Stack, Quote, Sidenote...), with editor-specific variants scoped by `.editor-app` |
|
|
| 5. **Editor-only styles** (`styles/editor/*.css`, 5 files) |
| - `_layout.css`: grid overrides (3-col symmetric, aligned with template), TOC drawer, responsive breakpoints (1100px collapse, 768px mobile) |
| - `_chrome.css`: ProseMirror editing visuals (placeholder, selection, cursors, comment marks, math editing) |
| - `_block-tools.css`: block handles (drag + add) and slash menu |
| - `_panels.css`: image upload card, footnote tooltip, citation panel |
| - `_hero-editable.css`: transparent click-to-edit inputs for FrontmatterHero |
|
|
| 6. **Publisher CSS** (`_publisher.css`) |
| - Styles specific to the published static HTML page |
| - Theme toggle animations, wide/fullWidth breakout, sidenote float, lightbox, PDF link |
| - Only injected by the HTML renderer (backend), never loaded in the editor |
|
|
| ### No CSS-in-JS |
|
|
| The project does not use MUI, Emotion, or any CSS-in-JS library. All styling is done via: |
| - CSS custom properties for theming |
| - Vanilla CSS files with BEM-like class naming |
| - `Floating UI` for tooltip positioning (lightweight, no CSS-in-JS) |
|
|
| ### Color theming |
|
|
| - The article area uses `data-theme="light"` / `data-theme="dark"` with CSS variable overrides |
| - The editor chrome is always dark, using `--ed-*` tokens |
| - The primary accent color is controlled via `--primary-color` (synced via Yjs settings) |
|
|
| ## HF Spaces constraints |
|
|
| ### Iframe embedding |
|
|
| When deployed as a HF Space, the app runs inside an iframe. This affects: |
|
|
| - **Viewport width**: the iframe is ~968px wide, not the full browser width |
| - **No `target="_top"` navigation**: links open within the iframe unless using `target="_blank"` |
| - **OAuth flow**: the OAuth callback URL must match the Space URL |
| - **CSP restrictions**: sandboxed iframes may restrict certain APIs |
| |
| ### Two-page architecture |
| |
| | URL | What it serves | |
| |-----|----------------| |
| | `/` | Published article (static HTML) or login prompt | |
| | `/editor` | The SPA editor (requires authentication) | |
| |
| This means: |
| - The published article is a completely standalone HTML file |
| - It does NOT load React or any JS framework |
| - The editor is a separate React SPA at `/editor` |
| |
| ### CSS cascade |
| |
| Because the published HTML is self-contained (all CSS inlined in `<style>`), there are no CSS conflicts with the HF Spaces iframe CSS. The editor uses Vite's CSS pipeline. |
| |
| ## Shared component registry |
| |
| Component definitions (name, kind, fields, defaults) are defined once in `backend/src/shared/component-defs.ts`. This file is the single source of truth. |
| |
| - **Backend** (`extensions.ts`): imports `SHARED_COMPONENT_DEFS` to generate TipTap server extensions for `generateHTML()` |
| - **Frontend** (`registry.ts`): imports `SHARED_COMPONENT_DEFS` via Vite alias `#shared` and decorates each entry with UI metadata (icon, label, description, placeholders) |
|
|
| Adding a new component: |
| 1. Add the entry to `shared/component-defs.ts` |
| 2. Add UI metadata to `frontend/src/editor/components/registry.ts` in `UI_META` |
| 3. Add CSS for the published view to `frontend/src/styles/_publisher.css` |
|
|
| ## Publisher pipeline |
|
|
| ``` |
| Y.Doc -> TiptapTransformer -> JSON -> generateHTML() -> postProcess() -> full HTML page |
| | |
| v |
| PDF (Playwright) |
| | |
| v |
| Upload to HF dataset |
| ``` |
|
|
| ### Post-processing (linkedom) |
|
|
| The `postProcess()` function uses `linkedom` for DOM manipulation instead of regex: |
| - Accordion `<div>` -> `<details>/<summary>` |
| - Citation `<span>` -> `<a>` links with bibliography anchors |
| - Bibliography placeholder -> formatted HTML with entry IDs |
| - Mermaid `<div>` -> `<pre class="mermaid">` |
| - HtmlEmbed `<div>` -> `<iframe>` |
| - Footnotes -> superscript links + appended section |
|
|
| ### Preview endpoint |
|
|
| `GET /api/preview/:docName` renders the HTML without saving or uploading. Useful for testing the publisher pipeline. |
|
|
| ## Auth and security |
|
|
| - AI chat routes (`/api/chat`, `/api/embed-chat`) are auth-guarded when OAuth is enabled |
| - The `requireEditor` middleware checks cookie token and verifies write access |
| - Published articles are served without auth (public) |
|
|
| ## Testing |
|
|
| Tests use Vitest + Supertest. Run with `npm test` from `backend/`. |
|
|
| | Test file | What it covers | |
| |-----------|----------------| |
| | `tests/publisher.test.ts` | Y.Doc extraction, HTML generation, post-processing, idempotency | |
| | `tests/html-renderer-snapshot.test.ts` | Snapshot tests for each postProcess transformation | |
| | `tests/security.test.ts` | XSS prevention in published HTML | |
| | `tests/css-resolution.test.ts` | @custom-media resolution | |
| | `tests/utils.test.ts` | Path sanitization utilities | |
| | `tests/auth.test.ts` | Token extraction, OAuth configuration | |
| | `tests/hf-storage.test.ts` | HF dataset storage configuration | |
| | `tests/persistence.test.ts` | Local file persistence, debounced save | |
| | `tests/api-routes.test.ts` | API route integration tests (publish, auth status) | |
|
|
