How raymmar/bookmarks works
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