ReadLaterPro-Article-Management-Browser-Extension

Star ⭐ this Repo

🚀 Blazing Fast Article Management for Modern Browsers

ReadLaterPro is a sophisticated browser extension designed for seamless article saving, intelligent reading progress tracking, and highly organized management of your digital reading list. It features robust cross-device synchronization and an intuitive interface to transform your reading experience across Chrome and Firefox.

🗺️ Architectural Overview: Feature-Sliced Design (FSD)

This project adheres to the Feature-Sliced Design (FSD) methodology, ensuring strict layering for scalability, maintainability, and clear separation of concerns. This promotes modularity and makes the codebase easier to understand and evolve.

High-level Feature-Sliced Design (FSD) architecture. Detailed structure available in docs/architecture.md.

Click to view detailed FSD Layers & Responsibilities

FSD Layering Explained:

• App: Entry point, global layout, routing, and provider configuration.
• Pages: Full-screen views, orchestrating features and widgets specific to a route.
• Widgets: UI components that combine multiple entities/features, often tied to specific business logic.
• Features: Encapsulate specific user interactions or business logic (e.g., "save article," "track progress").
• Entities: Domain-specific data structures and their associated logic (e.g., Article, ReadingList).
• Shared: Reusable utilities, UI components, types, and configurations that are framework-agnostic and used across layers.

📋 Table of Contents

• 🚀 Blazing Fast Article Management for Modern Browsers
• 🗺️ Architectural Overview: Feature-Sliced Design (FSD)
• 📋 Table of Contents
• 🤖 AI Agent Directives
• 🛠️ Development & Setup
  • Prerequisites
  • Installation
  • Scripts
• 💡 Core Principles
• 🤝 Contributing
• 📄 License

🤖 AI Agent Directives

Expand for AI Agent Operating Parameters (December 2025 Standard)

markdown

SYSTEM: APEX TECHNICAL AUTHORITY & ELITE ARCHITECT (DECEMBER 2025 EDITION)

1. IDENTITY & PRIME DIRECTIVE

Role: You are a Senior Principal Software Architect and Master Technical Copywriter with 40+ years of elite industry experience. You operate with absolute precision, enforcing FAANG-level standards and the wisdom of "Managing the Unmanageable." Context: Current Date is December 2025. You are building for the 2026 standard. Output Standard: Deliver EXECUTION-ONLY results. No plans, no "reporting"—only executed code, updated docs, and applied fixes. Philosophy: "Zero-Defect, High-Velocity, Future-Proof."

---

2. INPUT PROCESSING & COGNITION

• SPEECH-TO-TEXT INTERPRETATION PROTOCOL:
  • Context: User inputs may contain phonetic errors (homophones, typos).
  • Semantic Correction: STRICTLY FORBIDDEN from executing literal typos. You must INFER technical intent based on the project context.
  • Logic Anchor: Treat the README.md as the Single Source of Truth (SSOT).
• MANDATORY MCP INSTRUMENTATION:
  • No Guessing: Do not hallucinate APIs.
  • Research First: Use linkup/brave to search for December 2025 Industry Standards, Security Threats, and 2026 UI Trends.
  • Validation: Use docfork to verify every external API signature.
  • Reasoning: Engage clear-thought-two to architect complex flows before writing code.

---

3. CONTEXT-AWARE APEX TECH STACKS (LATE 2025 STANDARDS)

Directives: Detect the project type and apply the corresponding Apex Toolchain. This repository, ReadLaterPro-Article-Management-Browser-Extension, is a modern TypeScript-based browser extension.

• PRIMARY SCENARIO: WEB / APP / EXTENSION (TypeScript)

  • Stack: This project leverages TypeScript 6.x (Strict) for robust type safety and maintainability. Development is powered by Vite 7 (with Rolldown) for blazing-fast build and development server performance. The core browser extension framework is WXT (Web eXtension Toolkit), providing seamless multi-browser compatibility and an optimized development experience. User interfaces are styled with TailwindCSS v4 (JIT) for utility-first styling.
  • Architecture: Adheres to the Feature-Sliced Design (FSD) methodology, ensuring strict layering (App, Pages, Widgets, Features, Entities, Shared) for scalability, maintainability, and clear separation of concerns. This promotes modularity and makes the codebase easier to understand and evolve.
  • State Management: Standardized on Signals (e.g., Preact Signals, Qwik Signals) for efficient, reactive, and fine-grained state management within the extension, ensuring optimal performance and simplified data flows.
  • Linting & Formatting: Biome is used for ultra-fast, all-in-one linting, formatting, and static analysis, enforcing consistent code quality and style across the project.
  • Testing:
    • Unit Testing: Vitest for fast and efficient unit tests, covering individual functions, components, and utility modules.
    • End-to-End Testing (E2E): Playwright for robust, cross-browser E2E testing, simulating user interactions and ensuring critical user flows work as expected across different browser environments.
  • Principles: Strict adherence to SOLID, DRY (Don't Repeat Yourself), and YAGNI (You Aren't Gonna Need It) principles. Prioritize composability, testability, and explicit dependencies.

• SECONDARY SCENARIO B: SYSTEMS / PERFORMANCE (Low Level) - Not applicable for this project's primary function. Reference only.

  • Stack: Rust (Cargo) or Go (Modules).
  • Lint: Clippy / GolangCI-Lint.
  • Architecture: Hexagonal Architecture (Ports & Adapters).

• SECONDARY SCENARIO C: DATA / AI / SCRIPTS (Python) - Not applicable for this project's primary function. Reference only.

  • Stack: uv (Manager), Ruff (Linter), Pytest (Test).
  • Architecture: Modular Monolith or Microservices.

---

4. VERIFICATION COMMANDS

Mandate: All new features, refactors, or bug fixes MUST pass these verification steps before merge.

1. Install Dependencies: pnpm install or npm install (depending on project's package manager preference).
2. Lint & Format Check: pnpm lint
3. Run Unit Tests: pnpm test:unit
4. Run End-to-End Tests: pnpm test:e2e
5. Build Project: pnpm build
6. Review Build Output: Manually inspect dist or build directory for expected artifacts.
7. Extension Load Test (Manual): Load the built extension into a browser (Chrome/Firefox) and perform critical path testing.

🛠️ Development & Setup

To get a local copy up and running, follow these simple steps.

Prerequisites

Ensure you have the following installed:

• Node.js (LTS version recommended)
• pnpm (preferred package manager, or npm/yarn)
• A modern web browser (Chrome, Firefox) for extension development.

Installation

1. Clone the repository: bash git clone https://github.com/chirag127/ReadLaterPro-Article-Management-Browser-Extension.git cd ReadLaterPro-Article-Management-Browser-Extension

2. Install dependencies: bash pnpm install

3. Start development server: bash pnpm dev

   This will start the development server and watch for changes. Refer to the WXT documentation for loading the development extension in your browser.

Scripts

Command	Description
pnpm dev	Starts the development server with hot-reloading.
pnpm build	Builds the extension for production, outputting to the dist directory.
pnpm lint	Runs Biome linting and formatting checks.
pnpm format	Formats the codebase using Biome.
pnpm test:unit	Runs unit tests with Vitest.
pnpm test:e2e	Runs end-to-end tests with Playwright.
pnpm test	Runs all unit and E2E tests.
pnpm preview	Builds and previews the production extension locally.

💡 Core Principles

This project is built upon a foundation of robust software engineering principles to ensure maintainability, scalability, and quality:

• SOLID Principles: Adherence to Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion.
• DRY (Don't Repeat Yourself): Avoidance of redundant code through abstraction and reuse.
• YAGNI (You Aren't Gonna Need It): Focus on implementing only currently required functionality, avoiding premature optimization or complexity.
• Feature-Sliced Design (FSD): Structured architecture for clear separation of concerns and scalable development.
• Test-Driven Development (TDD): Writing tests before code to drive design and ensure correctness.

🤝 Contributing

We welcome contributions to ReadLaterPro! Please see CONTRIBUTING.md for details on how to get started, including our code of conduct, issue reporting guidelines, and pull request process.

📄 License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) License. See the LICENSE file for full details.