# jessthegpt/digital_archives architecture

> Architecture diagram of the GitHub repository jessthegpt/digital_archives, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jessthegpt/digital_archives
- Repository: https://github.com/jessthegpt/digital_archives

## Overview

##### Project Type & Purpose
- Full-stack collaborative editor built with Next.js (React), Lexical (rich-text), Liveblocks (real-time), Vercel AI SDK (AI toolbar).

##### Main Components
- Frontend (Next.js “app” folder): pages, React components, Lexical editor UI, custom hooks.
- Backend (Next.js API routes): serverless functions for chat, AI queries, screenshot, user search, Liveblocks auth.
- Real-time Service (Liveblocks): WebSocket sync of document state and cursors.
- AI Service (Vercel AI/Gemini): generates suggestions via API.
- Persistence (Liveblocks + optional DB): auto-save and state storage.

##### High‐Level Data Flow
1. User types in React/Lexical editor → local state update.
2. Edits sent over Liveblocks WebSocket → broadcast to other clients.
3. User triggers AI toolbar action → Next.js API route calls Vercel AI → response inserted into editor.
4. Collaborative state persisted by Liveblocks (and database if configured).
5. UI reflects real-time cursors, notifications, and AI-generated content.

##### Architectural Patterns
- Serverless functions (Next.js API routes) for backend logic.
- Real-time CRDT sync via Liveblocks.
- Plugin pattern in Lexical for draggable blocks, selection preservation.
- React hooks for local editor state and DOM events.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "UI Layer (Blue)"
        direction TB
        Pages["Next.js Pages & Layout"]:::ui
        click Pages "https://github.com/jessthegpt/digital_archives/blob/main/app/page.tsx"
        click Pages "https://github.com/jessthegpt/digital_archives/blob/main/app/layout.tsx"
        EditorComp["Lexical Editor UI"]:::ui
        click EditorComp "https://github.com/jessthegpt/digital_archives/blob/main/app/components/Editor.tsx"
        Hooks["Custom Hooks"]:::ui
        click Hooks "https://github.com/jessthegpt/digital_archives/blob/main/app/hooks/useActiveBlock.ts"
        click Hooks "https://github.com/jessthegpt/digital_archives/blob/main/app/hooks/useMouseListener.ts"
        click Hooks "https://github.com/jessthegpt/digital_archives/blob/main/app/hooks/useRange.ts"
        click Hooks "https://github.com/jessthegpt/digital_archives/blob/main/app/hooks/useSelection.ts"
        click Hooks "https://github.com/jessthegpt/digital_archives/blob/main/app/hooks/usePageLinks.ts"
        Plugins["Lexical Plugins"]:::ui
        click Plugins "https://github.com/jessthegpt/digital_archives/blob/main/app/plugins/DraggableBlockPlugin.tsx"
        click Plugins "https://github.com/jessthegpt/digital_archives/blob/main/app/plugins/PreserveSelectionPlugin.tsx"
    end

    subgraph "API Layer (Green)"
        direction TB
        ChatAPI["Chat API Route"]:::api
        click ChatAPI "https://github.com/jessthegpt/digital_archives/blob/main/app/api/chat/route.ts"
        GeminiAPI["AI Query Route"]:::api
        click GeminiAPI "https://github.com/jessthegpt/digital_archives/blob/main/app/api/gemini-computer-use-api.ts"
        LiveAuth["Liveblocks Auth Route"]:::api
        click LiveAuth "https://github.com/jessthegpt/digital_archives/blob/main/app/api/liveblocks-auth/route.ts"
        ScreenshotAPI["Screenshot API Route"]:::api
        click ScreenshotAPI "https://github.com/jessthegpt/digital_archives/blob/main/app/api/screenshot-api-route.ts"
        UserSearch["User Search Route"]:::api
        click UserSearch "https://github.com/jessthegpt/digital_archives/blob/main/app/api/users/search/route.ts"
    end

    subgraph "External Services (Orange)"
        direction TB
        LiveblocksSvc["Liveblocks Service (WebSocket)"]:::external
        AIService["Vercel AI / Gemini"]:::external
        Database["Persistence / DB"]:::external
        click Database "https://github.com/jessthegpt/digital_archives/blob/main/app/database.ts"
    end

    %% Data Flows
    EditorComp -->|"HTTP REST"| GeminiAPI
    GeminiAPI -->|"API Call"| AIService
    EditorComp -->|"WebSocket"| LiveblocksSvc
    LiveAuth -->|"Auth Token"| LiveblocksSvc
    LiveblocksSvc -->|"Persist State"| Database
    EditorComp -->|"HTTP REST"| ChatAPI
    EditorComp -->|"HTTP REST"| ScreenshotAPI
    EditorComp -->|"HTTP REST"| UserSearch

    %% Styles
    classDef ui fill:#D0E6FF,stroke:#0366d6;
    classDef api fill:#D0FFD0,stroke:#228B22;
    classDef external fill:#FFE0B2,stroke:#FF8C00;
```
