Back to Documentation

Document Comments

Introduction

Sutram provides a powerful document commenting system that allows project teams to collaborate directly on documents by placing comments at specific locations. Comments are anchored to precise positions within PDFs, images, Office documents, Markdown files, and CAD/BIM models, enabling contextual discussions without leaving the platform.

Key Features

  • Context-Aware Anchoring: Three different anchoring methods depending on file type
  • Threaded Discussions: Reply to comments to create conversation threads
  • Real-Time Collaboration: See comments from other users instantly via PubSub
  • Multi-Format Support: Works with PDFs, images, Office documents (Word, Excel, PowerPoint), Markdown, and CAD/BIM files
  • Comment Resolution: Mark comments as resolved when issues are addressed
  • Visual Markers: Numbered balloon markers show comment locations directly on documents
  • Comments Panel: Bottom sheet with filters (All/Open/Resolved) to browse and navigate comments
  • Navigation: Click markers or panel items to jump to specific comments
  • 6-Language Support: Full internationalization (English, Portuguese, Spanish, French, German, Italian)

Anchoring Methods by File Type

The system uses three distinct anchoring methods depending on the file type, each optimized for how users interact with that type of content:

1. Positional Anchoring (PDF & Images)

Used for: PDF files, Images, Office documents (converted to PDF)

How it works: User clicks anywhere on the document and the comment is anchored to relative coordinates (0.0-1.0).

File Type Position Type Storage User Interaction
PDF pdf_page pdf_page_number + pdf_relative_x/y (0.0-1.0) Click anywhere on page
Images image pdf_relative_x/y (0.0-1.0) Click anywhere on image
Office pdf_page Converted to PDF first, same as PDF Click on converted PDF

Advantages:

  • Works regardless of zoom level or window size
  • Precise positioning on visual content
  • Simple and intuitive for users

Button text: "Click to add..." (translated to 6 languages)

2. Camera View Anchoring (CAD/BIM)

Used for: CAD 2D drawings (DWG, DXF), CAD 3D models (IFC, RVT, etc.)

How it works: User clicks on the model and the comment captures both the world coordinates AND the camera state (view position, zoom, rotation).

File Type Position Type Storage User Interaction
CAD 3D aps_3d aps_world_coordinates {x,y,z} + aps_db_id + aps_camera_state Click on 3D model surface
CAD 2D aps_2d aps_world_coordinates {x,y,z} + aps_sheet_guid + aps_camera_state Click on 2D drawing

Advantages:

  • Markers follow the model during zoom/pan/rotate
  • "Go to location" restores the exact view the commenter saw
  • Works with exploded views and section planes
  • Element ID captured for future integrations

Button text: "Click to add..." (translated to 6 languages)

3. Text-Anchored Comments (Markdown)

Used for: Markdown files (in viewer and editor)

How it works: User selects text (instead of clicking) and the comment is anchored to the selected text with surrounding context for resilience against edits.

File Type Position Type Storage User Interaction
Markdown markdown text_anchor {exact_text, prefix, suffix} + pdf_relative_y (fallback) Select text to comment

Text Anchor Structure:

{
  "exact_text": "the selected text",
  "prefix": "50 chars before selection",
  "suffix": "50 chars after selection",
  "selection_length": 18
}

Advantages:

  • Comments survive document edits (text-based search, not pixel position)
  • Prefix/suffix context helps find text even if exact match moves
  • Visual highlight of commented text in viewer
  • Mobile support with floating "Comment" button

Button text: "Select text..." (translated to 6 languages)

Mobile UX:

  • Touch device detected automatically
  • User does long-press to select text
  • Floating "Comment" button appears below selection (avoids native menu conflict)
  • 600ms debounce allows user to adjust selection handles before button appears

How It Works

Enabling Comment Mode

  1. Open a document preview (PDF, image, Markdown, Office, or CAD file)
  2. Click the comment button in the preview toolbar
  3. The overlay activates and markers appear for existing comments
  4. The Comments Panel appears at the bottom with filter options

Adding a Comment

The interaction differs by file type:

PDF, Images, Office, CAD

  1. With comment mode enabled, click Add in the Comments Panel
  2. Click on the document at the desired location
  3. A modal appears with a text input
  4. Enter your comment text
  5. Click Post Comment to create the comment
  6. A numbered marker appears at the clicked location

Markdown

  1. With comment mode enabled, click Add in the Comments Panel
  2. Select text by clicking and dragging (desktop) or long-press and drag handles (mobile)
  3. On desktop: modal opens immediately after selection
  4. On mobile: tap the floating "Comment" button that appears below the selection
  5. Enter your comment text
  6. Click Post Comment to create the comment
  7. A numbered marker appears in the left margin, aligned with the selected text

Viewing Existing Comments

  • Markers: Numbered balloon markers show comment locations
    • Purple markers: Open comments
    • Green markers: Resolved comments
    • Orange badge: Number of replies
  • Click marker: Opens the comment thread modal
  • Comments Panel: Bottom sheet showing all comments
    • Expand/collapse by clicking header
    • Filter by status: All / Open / Resolved
    • Click any comment to navigate to its location
  • Navigation: Use "Go to location" or the panel to jump to comments

Replying to Comments

  1. Click on an existing comment marker (or select from Comments Panel)
  2. The thread modal opens showing the original comment and any replies
  3. Type your reply in the input field
  4. Click Post reply to add your response

Resolving Comments

  1. Open a comment thread
  2. Click Mark as resolved (button above reply textarea)
  3. The marker turns green to indicate resolution
  4. Resolved comments can be Reopened from the modal actions

Deleting Comments

  1. Open a comment thread
  2. Click the Delete button (only visible to comment author or project admin)
  3. Confirm deletion
  4. The marker is removed from the document

Office Documents (Word, Excel, PowerPoint)

Office files require special handling because comments need a static canvas for positioning.

How It Works

  1. Project setting: "Allow comments on Office files" must be enabled
  2. First-time activation: When clicking the comment button on an Office file:
    • If PDF cached: Switches to PDF viewer immediately
    • If not cached: Shows "Converting document..." loading state
  3. Conversion: LibreOffice converts Office file to PDF (runs once, cached permanently)
  4. Result: PDF viewer with comment overlay appears
  5. Badge: "Comment mode" badge shows in header when viewing converted PDF

Configuration

Project owners can enable Office comments in Project Settings:

  1. Navigate to Settings > File Settings
  2. Enable "Allow comments on Office files"
  3. Save settings

Limitations

  • Comments are placed on the PDF conversion, not the original Office file
  • Complex formatting may render differently in PDF
  • Excel formulas show calculated values only
  • PowerPoint animations/transitions are lost

CAD/BIM Files (Autodesk APS)

The commenting system fully integrates with the Autodesk Viewer for CAD and BIM files.

3D Models (IFC, RVT, etc.)

For 3D models, comments are anchored using:

  • World Coordinates: The 3D point where the user clicked
  • Element ID: The specific model element (if hit test succeeds)
  • Camera State: The exact view position when comment was created

Behavior:

  • Markers update position in real-time as you rotate/zoom the model
  • "Go to location" restores the exact camera view from when the comment was created
  • Works with exploded views and section planes

2D Drawings (DWG, DXF)

For 2D drawings, comments use:

  • Model Coordinates: Position in drawing units (not screen pixels)
  • Sheet GUID: Identifies which sheet the comment is on

Behavior:

  • Markers stay attached to drawing points during zoom/pan
  • Camera change events trigger marker re-rendering
  • Works across different zoom levels and pan positions

Technical Details

The system uses Autodesk Viewer SDK methods:

Operation Method
Get click position (3D) viewer.impl.hitTest()
Get click position (2D) viewer.clientToWorld()
Render marker position viewer.impl.worldToClient()
Navigate to comment viewer.restoreState()
Track camera changes CAMERA_CHANGE_EVENT listener

Real-Time Collaboration

Comments are synchronized in real-time across all connected users.

PubSub Topics

Topic format: document_comments:{content_item_id}

Events

Event Description
comment_added New comment created by another user
comment_updated Comment edited, reply added, or status changed
comment_deleted Comment removed by another user

Behavior

  • New markers appear instantly when other users add comments
  • Reply counts update in real-time
  • Resolution status syncs across all viewers
  • If viewing a deleted comment, the modal closes automatically

User Interface

Comment Markers

Markers use a chat balloon design with a pointer:

   ┌───────┐
   │  1.2  │  ← Number (page.index or just index)
   └───┬───┘
       ▽     ← Pointer indicates exact position

Styling:

  • Background: Indigo (#6366f1) for open, Green (#22c55e) for resolved
  • Reply badge: Orange (#f97316) circle in top-right corner
  • Hover effect: Slight scale up (1.1x)
  • Shadow: Drop shadow for visibility on any background

Comment Modal

The modal displays:

Header:

  • Comment author name and avatar
  • Timestamp (relative, e.g., "2 hours ago")
  • Position info (e.g., "Page 3" or "3D Point")

Body:

  • Comment text
  • Replies (threaded, chronological)
  • Reply input field

Actions (thread view):

  • Mark as resolved: Button above reply form (green, prominent)
  • Post reply: Submit reply button
  • Delete: Trash icon (author/admin only)
  • Reopen: Available when comment is resolved
  • Close: Dismiss modal

Architecture

Database Schema

Table: document_comments

Column Type Description
id UUID Primary key
content Text Comment text
content_item_id UUID FK to content_items
user_id UUID FK to users (author)
project_id UUID FK to projects
parent_id UUID FK to document_comments (for replies)
position_type String pdf_page, image, markdown, aps_3d, aps_2d
pdf_page_number Integer Page number (PDF only)
pdf_relative_x Float X position 0.0-1.0 (or pixels for markdown)
pdf_relative_y Float Y position 0.0-1.0 (or pixels for markdown)
aps_world_coordinates Map {x, y, z} for CAD
aps_db_id Integer Autodesk element ID
aps_camera_state Map Viewer state for navigation
aps_sheet_guid String 2D sheet identifier
resolved Boolean Resolution status
resolved_at DateTime When resolved
resolved_by_id UUID FK to users
inserted_at DateTime Creation timestamp
updated_at DateTime Last modification

Backend Modules

Module Purpose
Sutram.Content.DocumentComment Ecto schema with validations
Sutram.Content CRUD functions for comments
SutramWeb.ProjectLive.Content.CommentHandler LiveView event handlers
SutramWeb.ProjectLive.Components.CommentModal Modal LiveComponent
SutramWeb.ProjectLive.Components.CommentsPanel Bottom sheet panel with filters
SutramWeb.ProjectLive.Components.PreviewModal Preview with overlay

Frontend (JavaScript)

File Purpose
assets/js/hooks/comment_overlay.js Main overlay hook
assets/js/viewers/pdf_viewer.js PDF viewer with page tracking
assets/js/viewers/autodesk_viewer.js CAD viewer with getViewerInstance()

Key Functions

CommentOverlay Hook:

  • calculatePdfPosition(): Convert click to PDF coordinates
  • calculateImagePosition(): Convert click to image coordinates
  • calculateMarkdownPosition(): Convert click to markdown pixel coordinates
  • calculateApsPosition(): Convert click to CAD world coordinates
  • calculateScreenPosition(): Convert stored position to screen pixels
  • renderMarkers(): Draw all visible markers
  • navigateToComment(): Scroll/zoom to comment location

Configuration

Project Settings

Setting Default Description
allow_office_comments false Enable comments on Office files

Application Settings

Comments are enabled by default for:

  • PDF files
  • Image files
  • CAD files (when APS is configured)

Office files require explicit project-level opt-in due to the PDF conversion requirement.

Troubleshooting

Comments Not Appearing

Cause: Comment mode not enabled

Solution:

  1. Click the comment button in the preview toolbar
  2. Wait for markers to render
  3. Check browser console for errors

Markers in Wrong Position

Cause: Resize or zoom changed after markers were rendered

Solution:

  • Markers automatically reposition on resize/zoom
  • If still wrong, close and reopen the preview

CAD Comments Not Saving

Cause: APS viewer not fully loaded

Solution:

  1. Wait for the 3D model to fully load
  2. Try clicking on a visible surface
  3. Check that the viewer responds to navigation

Office Comment Button Missing

Cause: Project setting not enabled

Solution:

  1. Go to Project Settings > File Settings
  2. Enable "Allow comments on Office files"
  3. Save and refresh

API Reference

LiveView Events (Client to Server)

Event Payload Description
position_selected Position data User clicked to add comment
marker_clicked {comment_id, marker_number} User clicked existing marker
create_comment {content} Save new comment
create_reply {content, parent_id} Add reply to thread
resolve_comment {comment_id} Mark as resolved
reopen_comment {comment_id} Reopen resolved comment
delete_comment {comment_id} Remove comment
navigate_to_comment {comment_id} Jump to location
request_markers {content_item_id} Request initial markers

Push Events (Server to Client)

Event Payload Description
render_markers {markers: [...]} Full list of markers
add_marker {marker: {...}} Single new marker
update_marker {marker: {...}} Updated marker data
remove_marker {comment_id} Delete marker
navigate_to_comment {comment: {...}} Trigger navigation

Release History

Version Date Changes
v0.58.0 2025-12-22 Initial PDF comments with threading
v0.59.0 2025-12-23 Comments in Chat context
v0.60.0 2025-12-24 Image comments support
v0.61.0 2025-12-24 Office file comments (via PDF)
v0.61.1 2025-12-24 CAD/APS comments (2D and 3D)
v0.62.0 2025-12-24 Onboarding toast hint
v0.63.0 2025-12-25 Comments Panel (V3) - bottom sheet with filters and navigation
v0.64.0 2025-12-26 Markdown comments support
v0.64.1 2025-12-26 UI improvements: reorganized modal actions, removed toast hint
v0.65.0 2025-12-26 Comments mode in markdown editor with manual position adjustment
v0.65.1 2025-12-29 Mobile text selection support for markdown comments
v0.65.2 2025-12-29 UX improvements: floating button positioned below selection to avoid native menu
v0.65.3 2025-12-29 Internationalization: floating "Comment" button translated to 6 languages

Comments Panel (V3)

The Comments Panel is a bottom sheet that lists all comments in the document, providing a unified navigation experience for both mobile and desktop.

Layout

The panel uses a bottom sheet design (unified for mobile and desktop):

┌─────────────────────────────────────────────────┐
│                                                 │
│              Viewer (PDF/Image/CAD)             │
│                                                 │
│                       📍                        │
│                                                 │
├─────────────────────────────────────────────────┤
│ 💬 4 comentários                            ▼  │  ← Click expands
├─────────────────────────────────────────────────┤
│ ◉ Todos   ○ Abertos   ○ Resolvido              │  ← Filters
├─────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────┐ │
│ │ 🗨️1 👤 João · há 2h                         │ │
│ │     Verificar se a cota está correta...     │ │
│ └─────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────┐ │
│ │ 🗨️2 👤 Maria · há 1d                    ✅  │ │
│ │     Conflito com a estrutura existente      │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

States

State Description
Minimized Shows only header with comment count (48px height)
Expanded Shows filters and scrollable list (max 50vh)

Features

  • Toggle: Click header to expand/collapse
  • Filters: All / Open / Resolved (radio buttons)
  • Comment List: Scrollable list with balloon markers matching canvas style
  • Navigation: Click any comment to jump to its location (page change for PDF, camera restore for CAD)
  • Real-time: Updates automatically via existing PubSub

Marker Style

Comments in the list use the same balloon marker style as the canvas:

   ┌───────┐
   │   1   │  ← Number (insertion order)
   └───┬───┘
       ▽     ← Pointer (chat bubble tail)
  • Background: Indigo (#6366f1) for open, Green (#22c55e) for resolved
  • Reply badge: Orange (#f97316) in top-right corner
  • Drop shadow: For visibility

Technical Details

New Component: SutramWeb.ProjectLive.Components.CommentsPanel

Props:

  • comments - List of DocumentComment structs
  • expanded - Boolean (panel state)
  • filter - Atom (:all, :open, :resolved)

Events (sent to parent via send/2):

  • {:comments_panel, :toggle} - Toggle expand/collapse
  • {:comments_panel, :filter, filter} - Change filter
  • {:comments_panel, :go_to_comment, comment_id} - Navigate to comment

State Management (in Content LiveView):

  • comments_panel_expanded - Boolean
  • comments_panel_filter - Atom

Markdown Editor Comments Mode (v0.65.0)

The markdown editor includes a dedicated comments mode that allows users to view and reposition comment markers while editing. This solves the problem where markers become misaligned after editing markdown content (since markdown uses absolute pixel coordinates).

Two Modes

Mode Description
Editing (default) Normal Milkdown WYSIWYG editor, no markers visible
Comments Rendered preview with comment overlay and side panel

Layout (Comments Mode)

┌─────────────────────────────────────────────────────────────────┐
│  ← Back    [Editing] [Comments 📍3]           Upload   │ Header │
├─────────────────────────────────────┬───────────────────────────┤
│                                     │ 💬 3 comments             │
│   Rendered Markdown Preview         │ ─────────────────────────│
│   (read-only)                       │ ◉ All ○ Open ○ Resolved  │
│                                     │ ─────────────────────────│
│        📍 Marker 1                  │ [1] João · 2h ago         │
│                                     │     Check this section    │
│        📍 Marker 2                  │     [Adjust] [Go to]      │
│                                     │ ─────────────────────────│
│                                     │ [2] Maria · 1d ago   ✅   │
│                                     │     Fixed                 │
└─────────────────────────────────────┴───────────────────────────┘

Manual Position Adjustment

When markdown content is edited, comment markers may become misaligned because they use absolute pixel coordinates. Users can manually reposition markers:

  1. Enter Comments mode in the markdown editor
  2. Find the misaligned comment in the side panel
  3. Click "Adjust position" button
  4. Cursor changes to crosshair, side panel shows "Click on the new position"
  5. Click on the correct location in the preview
  6. Marker moves to new position and is saved

Mobile Restriction

⚠️ Comments mode is not available on mobile devices (viewport < 768px). A tooltip on the disabled button explains: "Use a desktop computer to manage comments".

Technical Details

New Assigns (in markdown_editor.ex):

  • editor_mode - Atom (:editing | :comments)
  • comments - List of DocumentComment structs
  • comments_panel_expanded - Boolean
  • comments_panel_filter - Atom (:all | :open | :resolved)
  • repositioning_comment_id - UUID or nil

New Events:

  • toggle_editor_mode - Switch between editing and comments modes
  • start_reposition - Enter reposition mode for a specific comment
  • cancel_reposition - Exit reposition mode
  • update_marker_position - Save new position from reposition click
  • go_to_comment - Navigate/scroll to comment location

JavaScript Changes (comment_overlay.js):

  • Added repositioningCommentId state
  • Added enter_reposition_mode / exit_reposition_mode event handlers
  • Modified click handler to detect reposition mode and send update_marker_position
  • Updated markdown element selectors to work in both viewer and editor contexts

Document Version: 1.3 Last Updated: December 29, 2025 Author: Sutram Development Team

Back to Documentation