Merge pull request #71 from Roznoshchik/preact-app-frontend

Tags Management & SQLAlchemy 2.0 Cleanup

  This PR adds a complete Tags management UI and modernizes the SQLAlchemy relationship patterns across the
  codebase.

  Features

  Tags Management UI
  - New Tags page with list view, filters, search, and pagination
  - TagCard component with color indicator and article/highlight counts
  - TagEditModal with rename, archive toggle, and delete functionality
  - Inline tag creation from Combobox dropdown in all modals

  Combobox Enhancements
  - onCreate prop for inline tag creation
  - "Create [query]" option appears when no exact match exists
  - Escape key closes dropdown only (not parent modal)
  - Fixed spacebar selecting instead of typing

  QuillEditor
  - Added markdown paste support
  - Added H1-H6 header formatting options

  Backend Improvements

  SQLAlchemy 2.0 Patterns
  - Removed lazy="dynamic" from Article.tags, Article.highlights, Highlight.tags, and Tag relationships
  - Added selectinload with archived tag filtering to eliminate N+1 queries
  - Standardized to_dict pattern: id = integer PK, uuid = string UUID

  Data Model Consolidation
  - Merged Topic into Tag with dual-write support
  - Added backfill migration to populate Tags from existing Topics
  - Standardized API routes to use UUID (articles, highlights, tags)

  Tags API
  - POST /tags now unarchives existing archived tags instead of failing
  - Improved query performance with proper eager loading

  Other Changes

  - Toggle switch CSS class for checkbox inputs
  - Icon component passes through onClick and other props
  - Removed legacy Topic-related tests
  - Code formatting with Biome

Author: Roznoshchik

CLAUDE.md

@@ -231,7 +231,7 @@ they shouldn't include random comments or the micro details of every file change
 ## Working state
 If I say status task - <TASK NAME>
 
-Explore the .local file for files of the following format
+Explore the .claude folder for files of the following format
 Check the task name or if no task name then the branch name
 then check
 claude-progress-<branch name>.md

app/api/articles.py

@@ -1,4 +1,5 @@
 import sqlalchemy as sa
+from sqlalchemy.orm import selectinload
 
 from app import db, CustomLogger
 from app.api import bp
@@ -12,7 +13,7 @@
     process_url_entry,
     process_file_upload,
 )
-from app.models import Article, Event
+from app.models import Article, Event, Tag
 from app.models.event import EventName
 from app.api.errors import bad_request, error_response
 from app.api.helpers.update_tags import update_tags
@@ -71,9 +72,17 @@ def get_articles():
 
         # Build main query with SQLAlchemy 2.0 select
         # Use .isnot(True) to include NULL processing values (old articles)
-        stmt = sa.select(Article).where(
-            Article.user_id == user.id,
-            Article.processing.isnot(True),
+        # Eager load tags and highlights to avoid N+1 queries
+        stmt = (
+            sa.select(Article)
+            .where(
+                Article.user_id == user.id,
+                Article.processing.isnot(True),
+            )
+            .options(
+                selectinload(Article.tags.and_(Tag.archived.is_(False))),
+                selectinload(Article.highlights),
+            )
         )
         stmt = aqm.filter_by_status(stmt, status)
         stmt = aqm.filter_by_tags(stmt, tag_ids)

app/api/helpers/article_query_maker.py

@@ -1,7 +1,8 @@
 import sqlalchemy as sa
+from sqlalchemy.orm import selectinload
 
 from app import db
-from app.models import Article, tags_articles
+from app.models import Article, Tag, tags_articles
 
 
 def filter_by_status(stmt: sa.Select, status: str) -> sa.Select:
@@ -134,6 +135,10 @@ def get_recent_articles(user_id: int, limit: int = 3) -> list[Article]:
             Article.archived.is_(False),
             Article.date_read.isnot(None),
         )
+        .options(
+            selectinload(Article.tags.and_(Tag.archived == False)),
+            selectinload(Article.highlights),
+        )
         .order_by(Article.date_read.desc())
         .limit(limit)
     )

app/api/helpers/query_maker.py

@@ -9,28 +9,32 @@ def get_total_count(stmt: sa.Select) -> int:
     return db.session.scalar(count_stmt)
 
 
-def apply_pagination(stmt: sa.Select, page: str = "1", per_page: str = "15") -> tuple[list, bool]:
-    """Apply pagination to a select statement.
-
-    Args:
-        stmt: SQLAlchemy select statement
-        page: page number as string e.g "1"
-        per_page: "all" or int string e.g "15" or "30"
-    Returns:
-        Tuple of (items list, has_next boolean)
-    """
+def apply_pagination(
+    stmt: sa.Select,
+    page: str = "1",
+    per_page: str = "15",
+    *,
+    scalars: bool = True,
+) -> tuple[list, bool]:
+
     page_num = int(page)
 
     if per_page == "all":
-        items = list(db.session.scalars(stmt))
+        if scalars:
+            items = list(db.session.scalars(stmt))
+        else:
+            items = list(db.session.execute(stmt))
         return items, False
 
     per_page_num = int(per_page)
     offset = (page_num - 1) * per_page_num
 
-    # Get one extra to check if there's a next page
     paginated_stmt = stmt.offset(offset).limit(per_page_num + 1)
-    items = list(db.session.scalars(paginated_stmt))
+
+    if scalars:
+        items = list(db.session.scalars(paginated_stmt))
+    else:
+        items = list(db.session.execute(paginated_stmt))
 
     has_next = len(items) > per_page_num
     if has_next:

app/api/highlights.py

@@ -1,4 +1,5 @@
 import sqlalchemy as sa
+from sqlalchemy.orm import selectinload
 
 from flask import request, jsonify, url_for
 import json
@@ -16,7 +17,7 @@
 )
 from app.api.helpers.query_maker import apply_pagination, get_total_count
 from app.api.helpers.update_tags import update_tags
-from app.models import Highlight, Event
+from app.models import Highlight, Event, Tag
 from app.models.event import EventName
 
 
@@ -63,7 +64,12 @@ def get_highlights():
         tag_ids = request.args.get("tag_ids", None)
 
         # Build query with SQLAlchemy 2.0 select
-        stmt = sa.select(Highlight).where(Highlight.user_id == user.id)
+        # Eager load non-archived tags to avoid N+1 queries
+        stmt = (
+            sa.select(Highlight)
+            .where(Highlight.user_id == user.id)
+            .options(selectinload(Highlight.tags.and_(Tag.archived.is_(False))))
+        )
 
         # Apply filters
         stmt = hqm.filter_by_status(stmt, status)
@@ -128,12 +134,12 @@ def create_highlight():
             return bad_request("Something went wrong")
 
 
-@bp.get("/highlights/<id>")
+@bp.get("/highlights/<uuid>")
 @token_auth.login_required
-def get_highlight(id):
+def get_highlight(uuid):
     try:
         user = token_auth.current_user()
-        highlight = db.session.get(Highlight, id)
+        highlight = db.session.scalars(db.select(Highlight).where(Highlight.uuid == uuid)).first()
         if not highlight or highlight.user_id != user.id:
             return error_response(404, "Resource not found")
 
@@ -147,12 +153,12 @@ def get_highlight(id):
             return bad_request("Something went wrong")
 
 
-@bp.patch("/highlights/<id>")
+@bp.patch("/highlights/<uuid>")
 @token_auth.login_required
-def update_highlight(id):
+def update_highlight(uuid):
     try:
         user = token_auth.current_user()
-        highlight = db.session.get(Highlight, id)
+        highlight = db.session.scalars(db.select(Highlight).where(Highlight.uuid == uuid)).first()
         data = json.loads(request.data)
 
         if not highlight or highlight.user_id != user.id:
@@ -182,12 +188,12 @@ def update_highlight(id):
             return bad_request("Something went wrong")
 
 
-@bp.delete("/highlights/<id>")
+@bp.delete("/highlights/<uuid>")
 @token_auth.login_required
-def delete_highlight(id):
+def delete_highlight(uuid):
     try:
         user = token_auth.current_user()
-        highlight = db.session.get(Highlight, id)
+        highlight = db.session.scalars(db.select(Highlight).where(Highlight.uuid == uuid)).first()
         if not highlight or highlight.user_id != user.id:
             return error_response(404, "Resource not found")
 

app/api/tags.py

@@ -7,8 +7,9 @@
 from app.api import bp
 from app.api.auth import token_auth
 from app.api.errors import bad_request, LurnbyValueError, error_response
-from app.api.helpers.query_maker import apply_pagination
+from app.api.helpers.query_maker import apply_pagination, get_total_count
 from app.models import Event, Tag
+from app.models.associations import tags_highlights, tags_articles
 from app.models.event import EventName
 
 
@@ -22,23 +23,58 @@ def get_tags():
         page = request.args.get("page", "1")
         per_page = request.args.get("per_page", "150")
         status = request.args.get("status", "unarchived")  # all / archived / unarchived
+        search = request.args.get("q", "").strip()
 
         user = token_auth.current_user()
 
-        # Build query with SQLAlchemy 2.0 select
-        stmt = sa.select(Tag).where(Tag.user_id == user.id)
+        # Build query with computed counts
+        stmt = (
+            sa.select(
+                Tag,
+                sa.func.count(sa.distinct(tags_highlights.c.highlight_id)).label("h_count"),
+                sa.func.count(sa.distinct(tags_articles.c.article_id)).label("a_count"),
+            )
+            .outerjoin(tags_highlights, tags_highlights.c.tag_id == Tag.id)
+            .outerjoin(tags_articles, tags_articles.c.tag_id == Tag.id)
+            .where(Tag.user_id == user.id)
+            .group_by(Tag.id)
+        )
 
         if status.lower() == "archived":
             stmt = stmt.where(Tag.archived.is_(True))
         elif status.lower() != "all":
             stmt = stmt.where(Tag.archived.is_(False))
 
-        stmt = stmt.order_by(Tag.name.asc())
+        if search:
+            stmt = stmt.where(Tag.name.ilike(f"%{search}%"))
 
-        tag_list, has_next = apply_pagination(stmt, page, per_page)
-        tags = [tag.to_dict() for tag in tag_list]
+        stmt = stmt.order_by(Tag.name.asc())
 
-        return jsonify(tags=tags, has_next=has_next)
+        # Get total count before pagination
+        count_stmt = sa.select(Tag).where(Tag.user_id == user.id)
+        if status.lower() == "archived":
+            count_stmt = count_stmt.where(Tag.archived.is_(True))
+        elif status.lower() != "all":
+            count_stmt = count_stmt.where(Tag.archived.is_(False))
+        if search:
+            count_stmt = count_stmt.where(Tag.name.ilike(f"%{search}%"))
+        total = get_total_count(count_stmt)
+
+        rows, has_next = apply_pagination(
+            stmt,
+            page=page,
+            per_page=per_page,
+            scalars=False,
+        )
+
+        tags = []
+        for tag, h_count, a_count in rows:
+            tag_dict = tag.to_dict()
+            tag_dict["highlight_count"] = h_count
+            tag_dict["article_count"] = a_count
+            tags.append(tag_dict)
+
+        return jsonify(tags=tags, has_next=has_next, total=total)
 
     except Exception as e:
         if isinstance(e, LurnbyValueError):
@@ -50,14 +86,33 @@ def get_tags():
 
 @bp.route("/tags", methods=["POST"])
 @token_auth.login_required
-def tag():
+def create_tag():
     try:
         user = token_auth.current_user()
         data = json.loads(request.data) if request.data else None
         if not data or not data.get("name"):
             raise LurnbyValueError("Missing data in payload")
 
-        tag = Tag(user_id=user.id, name=data.get("name"))
+        name = data.get("name").strip()
+
+        # Check if a tag with this name already exists
+        existing_tag = Tag.query.filter(
+            Tag.user_id == user.id,
+            sa.func.lower(Tag.name) == name.lower(),
+        ).first()
+
+        if existing_tag:
+            if existing_tag.archived:
+                # Unarchive the existing tag
+                existing_tag.archived = False
+                ev = Event.add(EventName.UPDATED_TAG, user=user)
+                db.session.add(ev)
+                db.session.commit()
+                return jsonify(tag=existing_tag.to_dict()), 200
+            else:
+                raise LurnbyValueError("A tag with this name already exists")
+
+        tag = Tag(user_id=user.id, name=name)
         if uuid := data.get("uuid"):
             tag.uuid = uuid
         db.session.add(tag)

app/client/routes.py

@@ -21,6 +21,12 @@ def highlights():
     return render_template("client/highlights.html")
 
 
+@bp.get("/tags")
+def tags():
+    """Tags management page"""
+    return render_template("client/tags.html")
+
+
 @bp.get("/articles/<uuid>")
 @bp.get("/review")
 @bp.get("/settings")

app/export.py

@@ -68,7 +68,7 @@ def article_export(user, articles, ext):
                     f.write(a.source_url)
                     f.write("\n")
                 f.write("\n")
-                tags = [t.name for t in a.tags.all()]
+                tags = [t.name for t in a.tags]
                 f.write(", ".join(tags))
                 f.write("\n\n")
                 f.write(notes)
@@ -104,7 +104,7 @@ def article_export(user, articles, ext):
             data["Title"] = "".join([c for c in a.title if c.isalpha() or c.isdigit()]).rstrip()
             data["Source"] = a.source_url if a.source_url else a.source
             data["Notes"] = a.notes
-            data["Tags"] = [t.name for t in a.tags.filter_by(archived=False).all()]
+            data["Tags"] = [t.name for t in a.tags if not t.archived]
             a_highlights = a.highlights.filter_by(archived=False).all()
             highlights = []
             for h in a_highlights:

app/helpers/export_helpers.py

@@ -29,7 +29,7 @@ def create_zip_file_for_article(article: Article, path: str, ext: str):
         zip_path = os.path.join(path, f"{zip_title}.zip")
 
         article_dict = create_plain_text_article_dict(article)
-        article_highlights = create_list_of_highlight_dicts(article.highlights.all())
+        article_highlights = create_list_of_highlight_dicts(list(article.highlights))
 
         if ext == "csv":
             article_path, highlights_path = export_to_csv(path, article_dict, article_highlights)
@@ -183,7 +183,7 @@ def create_list_of_highlight_dicts(highlights):
                 "note": make_plain_text(highlight.note) if highlight.note else None,
                 "prompt": make_plain_text(highlight.prompt) if highlight.prompt else None,
                 "source": highlight.source,
-                "tags": ", ".join([tag.name for tag in highlight.tags.all()]),
+                "tags": ", ".join([tag.name for tag in highlight.tags]),
                 "topics": ", ".join([topic.title for topic in highlight.topics.all()]),
             }
         )

app/helpers/on_demand/match_tags.py

@@ -5,8 +5,7 @@
 def match_tags():
     articles = Article.query.all()
     for a in articles:
-        tags = a.tags.all()
-        for t in tags:
+        for t in list(a.tags):  # copy to avoid modification during iteration
             if t.user_id != a.user_id:
                 a.remove_tag(t)
                 tag = Tag.query.filter_by(name=t.name, user_id=a.user_id).first()