# raymmar/bookmarks architecture

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

- Interactive diagram: https://gitdiagram.com/raymmar/bookmarks
- Repository: https://github.com/raymmar/bookmarks

## Overview

##### Project type and purpose
- This is a full-stack web application with an accompanying browser extension.
- Purpose: A bookmark manager (“BookmarkDB”) that integrates with X.com (formerly Twitter) for importing bookmarks, auto-summarizes and auto-tags them using OpenAI, and visualizes them via lists, grids, and interactive force-directed graphs.

##### High-level file-structure analysis
- Top-level directories:
- client/ – React+TypeScript Vite app (UI)
- server/ – Node.js/TypeScript Express API, controllers, services
- extension/ – Browser extension assets (popup, background, content scripts)
- shared/ – Shared type definitions and DB schema (Drizzle ORM)
- scripts/ – One-off or batch data-migration and maintenance scripts
- Configuration:
- drizzle.config.ts, tsconfig.json, vite.config.ts, tailwind.config.js
- package.json / package-lock.json
- External integrations:
- X.com API (import bookmarks)
- OpenAI API (summaries, tags)

##### Key README insights
- Import from X.com or add manually
- Summaries and images sent to OpenAI
- Visual exploration via graph page

##### Main architectural components
a. UI Layer
- Web Frontend – React+Vite app (client/src/pages & components)
- Browser Extension – extension/popup.js, background.js, content.js
b. API Layer
- Express Server – server/index.ts, server/routes.ts
- Controllers – email-auth, reports, etc.
- Services / Lib – bookmark-service, report-service, ai-processor-service, tag-normalizer, scheduler
c. Data Layer
- Drizzle ORM – shared/schema.ts, server/db.ts
- Database – Postgres (or SQLite as per drizzle.config.ts)
- Scripts – batch migrations & maintenance (scripts/*.ts)
d. External Services
- X.com API – bookmark import endpoints
- OpenAI API – summarization & tag generation
- Email Service – signup / verification (server/services/email.ts)

##### Component interactions
1) User / Extension UI triggers HTTP requests (via fetch/Axios) to the Express API.
2) API auth middleware (server/auth.ts) validates JWT / sessions.
3) Controllers route requests to Services / Lib modules.
4) Services perform business logic:
- Bookmark creation → metadata-extractor → openai-tag-test / ai-processor-service → report-service
- Scheduler (server/lib/scheduler.ts) enqueues recurring tasks (e.g., re-tagging, summaries).
5) Services read/write via Drizzle ORM into Database.
6) Batch scripts connect directly to Drizzle ORM for offline migrations.
7) Frontend uses React Query (client/src/lib/queryClient.ts) to cache & fetch API data.

##### Architectural patterns and design principles
- Separation of concerns: UI / API / Data / Background services
- Modular services: each core feature implemented in its own service/lib file
- Shared types and schema to keep client and server in sync
- Background scheduling for asynchronous processing
- Extensibility: scripts folder for one-off maintenance tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "Client (Web Frontend)"
        direction TB
        ReactFrontend["React Frontend"]:::ui
        ClientOpenAI["OpenAI Integration"]:::api
        QueryClient["React Query Client"]:::api
    end
    subgraph "Browser Extension"
        direction TB
        Extension["Extension UI"]:::ui
    end

    %% API Layer
    subgraph "Server (API Layer)" 
        direction TB
        ExpressAPI["Express API Server"]:::api
        AuthMiddleware["Auth Middleware"]:::api
        subgraph "Controllers"
            EmailAuth["Email Auth Controller"]:::api
            ReportsController["Reports Controller"]:::api
        end
        subgraph "Services / Lib"
            BookmarkService["Bookmark Service"]:::api
            MetadataExtractor["Metadata Extractor"]:::api
            AIProcessor["AI Processor Service"]:::api
            OpenAITagTest["OpenAI Tag/Test Service"]:::api
            OpenAIInsightsTest["OpenAI Insights/Test Service"]:::api
            ReportService["Report Service"]:::api
            TagNormalizer["Tag Normalizer"]:::api
            XService["X.com Integration Service"]:::api
            EmailService["Email Service"]:::api
            Storage["Storage Abstraction"]:::api
        end
        DBSetup["ORM Database Setup"]:::db
    end

    %% Shared Layer
    subgraph "Shared"
        direction TB
        Schema["Schema & Types"]:::db
        Types["Types"]:::db
        URLService["URL Utilities"]:::api
    end

    %% External Services
    subgraph "External Services"
        direction TB
        XAPI["X.com API"]:::ext
        OpenAIAPI["OpenAI API"]:::ext
    end

    %% Background / Scripts
    subgraph "Background Tasks & Scripts"
        direction TB
        Scheduler["Scheduler"]:::bg
        Scripts["Maintenance Scripts"]:::bg
    end

    %% Database
    Database[(Database)]:::db

    %% Connections
    ReactFrontend -->|"GET/POST API"| ExpressAPI
    Extension -->|"GET/POST API"| ExpressAPI
    ExpressAPI -->|uses| AuthMiddleware
    ExpressAPI -->|routes to| EmailAuth
    ExpressAPI -->|routes to| ReportsController
    EmailAuth -->|calls| EmailService
    ReportsController -->|calls| ReportService
    ReportsController -->|calls| BookmarkService
    BookmarkService -->|uses| MetadataExtractor
    MetadataExtractor -->|calls| OpenAIAPI
    BookmarkService -->|calls| AIProcessor
    AIProcessor -->|calls| OpenAIAPI
    BookmarkService -->|calls| OpenAITagTest
    OpenAITagTest -->|calls| OpenAIAPI
    BookmarkService -->|calls| OpenAIInsightsTest
    OpenAIInsightsTest -->|calls| OpenAIAPI
    BookmarkService -->|uses| TagNormalizer
    BookmarkService -->|writes| Database
    ReportService -->|reads/writes| Database
    XService -->|calls| XAPI
    Scheduler -->|triggers| BookmarkService
    Scheduler -->|triggers| ReportService
    Scripts -->|connects| Database
    ExpressAPI -->|uses| Storage
    ExpressAPI -->|uses| DBSetup
    ReactFrontend -->|imports types| Schema
    ReactFrontend -->|imports types| Types
    ExpressAPI -->|imports schema| Schema
    ExpressAPI -->|imports types| Types
    ReactFrontend -->|uses| URLService
    ExpressAPI -->|uses| URLService
    ClientOpenAI -->|calls| OpenAIAPI
    QueryClient -->|caches| ReactFrontend

    %% Database connection
    DBSetup -->|configures| Database

    %% Click Events
    click ReactFrontend "https://github.com/raymmar/bookmarks/tree/main/client/src"
    click ClientOpenAI "https://github.com/raymmar/bookmarks/blob/main/client/src/lib/openai.ts"
    click QueryClient "https://github.com/raymmar/bookmarks/blob/main/client/src/lib/queryClient.ts"
    click Extension "https://github.com/raymmar/bookmarks/tree/main/extension/"
    click ExpressAPI "https://github.com/raymmar/bookmarks/blob/main/server/index.ts"
    click AuthMiddleware "https://github.com/raymmar/bookmarks/blob/main/server/auth.ts"
    click EmailAuth "https://github.com/raymmar/bookmarks/blob/main/server/controllers/email-auth.ts"
    click ReportsController "https://github.com/raymmar/bookmarks/blob/main/server/controllers/reports.ts"
    click BookmarkService "https://github.com/raymmar/bookmarks/blob/main/server/lib/bookmark-service.ts"
    click MetadataExtractor "https://github.com/raymmar/bookmarks/blob/main/server/lib/metadata-extractor.ts"
    click AIProcessor "https://github.com/raymmar/bookmarks/blob/main/server/lib/ai-processor-service.ts"
    click OpenAITagTest "https://github.com/raymmar/bookmarks/blob/main/server/lib/openai-tag-test.ts"
    click OpenAIInsightsTest "https://github.com/raymmar/bookmarks/blob/main/server/lib/openai-insights-test.ts"
    click ReportService "https://github.com/raymmar/bookmarks/blob/main/server/lib/report-service.ts"
    click TagNormalizer "https://github.com/raymmar/bookmarks/blob/main/server/lib/tag-normalizer.ts"
    click XService "https://github.com/raymmar/bookmarks/blob/main/server/lib/x-service.ts"
    click EmailService "https://github.com/raymmar/bookmarks/blob/main/server/services/email.ts"
    click Storage "https://github.com/raymmar/bookmarks/blob/main/server/storage.ts"
    click DBSetup "https://github.com/raymmar/bookmarks/blob/main/server/db.ts"
    click Schema "https://github.com/raymmar/bookmarks/blob/main/shared/schema.ts"
    click Types "https://github.com/raymmar/bookmarks/blob/main/shared/types.ts"
    click URLService "https://github.com/raymmar/bookmarks/blob/main/shared/url-service.ts"
    click Scheduler "https://github.com/raymmar/bookmarks/blob/main/server/lib/scheduler.ts"
    click Scripts "https://github.com/raymmar/bookmarks/tree/main/scripts/"

    %% Styles
    classDef ui fill:#add8e6,stroke:#333,stroke-width:1px
    classDef api fill:#90ee90,stroke:#333,stroke-width:1px
    classDef db fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef ext fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef bg fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
