Skip to content

FRICTION_LOG.md

Latest commit

 

History

History
480 lines (392 loc) · 14 KB

FRICTION_LOG.md

File metadata and controls

480 lines (392 loc) · 14 KB
Raw

Friction Log

This document tracks friction points, issues, and pain points encountered during the development of Feedback Pulse.

Table of Contents

Development Friction

Database Setup Issues

Date: Initial setup Severity: High Description:

  • D1 database ID configuration was initially set to "local" which caused binding errors
  • Error: binding DB of type d1 must have a valid 'id' specified [code: 10021] Resolution:
  • Ran npx wrangler d1 list to get actual database UUID
  • Updated wrangler.jsonc with correct database_id
  • Applied migrations to both local and remote databases separately

Lessons Learned:

  • Always use actual database UUIDs, not placeholder values
  • Local and remote databases need separate migration commands

Local vs Remote Database Mismatch

Date: During deployment Severity: High Description:

  • Feedback was saving locally but not appearing on deployed server
  • Remote database had outdated schema (missing title column) Resolution:
  • Dropped and recreated remote database table with correct schema
  • Applied proper migrations to remote database Impact: Data loss on remote database (had to recreate table)

Lessons Learned:

  • Always verify remote database schema matches local
  • Use migrations consistently for both environments
  • Consider migration versioning system

Browser Caching Issues

Date: During UI development Severity: Medium Description:

  • Changes to HTML/CSS not reflecting in browser during development
  • User reported: "why it aint changing on the dev server" Resolution:
  • Added cache-busting headers (Cache-Control: no-cache) to static asset serving
  • Instructed user to hard refresh browser (Ctrl+Shift+R / Cmd+Shift+R) Impact: Slowed development iteration

Lessons Learned:

  • Always include cache headers for development
  • Document browser refresh requirements for users

Deployment Friction

Worker Name Changes

Date: During repo setup Severity: Low Description:

  • Initial worker name was auto-generated (flat-wildflower-2869)
  • Needed to change to more meaningful name (feedback-pulse) Resolution:
  • Updated wrangler.jsonc name field
  • Redeployed with new name Impact: Old URL becomes inactive, need to update links

Lessons Learned:

  • Choose meaningful worker names from start
  • Document URL changes for users

Remote Database Schema Drift

Date: After initial deployment Severity: High Description:

  • Remote database schema was outdated compared to local
  • Missing columns caused save operations to fail Resolution:
  • Manual schema update via SQL commands
  • Lost existing data in remote database Impact: Production data loss

Lessons Learned:

  • Implement migration system from start
  • Test migrations on staging before production
  • Consider data migration scripts for schema changes

UI/UX Friction

Emoji Visibility in Gradient Text

Date: During header styling Severity: Low Description:

  • Emoji in header not visible due to -webkit-text-fill-color: transparent
  • Gradient text effect made emoji invisible Resolution:
  • Separated emoji from gradient text using <span> wrapper
  • Applied gradient only to text portion Impact: Minor visual inconsistency

Lessons Learned:

  • Test emoji rendering with CSS effects
  • Consider emoji placement when using advanced CSS

Chart.js CDN Loading

Date: Adding statistics charts Severity: Low Description:

  • Needed to add Chart.js library for statistics visualization
  • Had to add external CDN dependency Resolution:
  • Added Chart.js via CDN in HTML head
  • No build process needed (works with static HTML) Impact: External dependency, potential CDN availability issues

Lessons Learned:

  • Consider bundling for production
  • Document external dependencies
  • Consider fallback if CDN fails

Layout Restructuring Challenges

Date: Multiple iterations Severity: Medium Description:

  • Multiple layout changes requested (side-by-side, stacked, moved positions)
  • Required CSS grid/flexbox changes multiple times Resolution:
  • Used flexbox for final vertical stacking
  • Created reusable container classes Impact: Multiple iterations slowed development

Lessons Learned:

  • Clarify layout requirements upfront
  • Use flexible CSS (flexbox/grid) from start
  • Consider responsive design implications

API & Backend Friction

AI Analysis Consistency

Date: Early development Severity: Medium Description:

  • User reported: "whatever I put in the text input to analyze is giving the same results"
  • Rule-based analysis was too simplistic Resolution:
  • Integrated Cloudflare Workers AI with Llama models
  • Implemented contextual AI analysis instead of keyword matching Impact: Required AI integration, increased complexity

Lessons Learned:

  • Rule-based systems have limitations
  • AI integration requires proper prompt engineering
  • Need fallback mechanisms when AI unavailable

Meaningless Content Detection

Date: Feature addition Severity: Low Description:

  • Needed to filter gibberish/spam feedback
  • Initial rule-based detection was insufficient Resolution:
  • Added AI-powered validation endpoint
  • Falls back to rule-based if AI unavailable Impact: Additional API call, slight latency increase

Lessons Learned:

  • Validation should be fast (use smaller AI model)
  • Always provide fallback mechanisms

Pagination Implementation

Date: Feature addition Severity: Low Description:

  • Needed to handle large datasets efficiently
  • Backend and frontend pagination logic needed coordination Resolution:
  • Implemented server-side pagination with query parameters
  • Added frontend pagination controls Impact: More complex API endpoint

Lessons Learned:

  • Design pagination API early
  • Consider performance implications of large datasets

Tooling Friction

Git Command Abort Issues

Date: Multiple occasions Severity: Low Description:

  • Some git commands were aborted by user or system
  • Commands like git commit sometimes failed to spawn Resolution:
  • User manually executed commands
  • Some operations required retry Impact: Slowed workflow, required manual intervention

Lessons Learned:

  • Some operations may need manual execution
  • Document manual steps as fallback

Wrangler CLI Commands

Date: Throughout development Severity: Low Description:

  • Multiple wrangler commands needed for different operations
  • Local vs remote flag differences Resolution:
  • Created helper scripts where possible
  • Documented command differences Impact: Learning curve, command complexity

Lessons Learned:

  • Create helper scripts for common operations
  • Document command patterns clearly

Package.json Scripts

Date: Deployment Severity: Low Description:

  • User changed npm run deploy to npm wrangler deploy (incorrect)
  • Should be npx wrangler deploy or npm run deploy Resolution:
  • Corrected to use npx wrangler deploy in README Impact: Confusion about correct command

Lessons Learned:

  • Verify command syntax in documentation
  • Use consistent command patterns

Documentation Friction

README Updates

Date: Multiple iterations Severity: Low Description:

  • README needed multiple updates as features were added
  • Had to remove/add sections based on user preferences Resolution:
  • Comprehensive README rewrite
  • Removed live demo section per user request Impact: Documentation maintenance overhead

Lessons Learned:

  • Keep documentation updated incrementally
  • Consider documentation templates
  • Version control helps track doc changes

API Documentation

Date: Feature additions Severity: Low Description:

  • New endpoints added without immediate documentation
  • Had to document API after implementation Resolution:
  • Added comprehensive API documentation to README
  • Included request/response examples Impact: Documentation lagged behind implementation

Lessons Learned:

  • Document APIs as you build them
  • Use API documentation tools
  • Include examples from start

Examples File Creation

Date: Testing and documentation Severity: Low Description:

  • Needed examples for testing spam detection and analysis quality
  • No centralized collection of test cases
  • Users needed reference examples for different feedback types Resolution:
  • Created EXAMPLES.md with comprehensive collection of:
    • Valid feedback examples (positive, negative, neutral, high urgency)
    • Spam examples (promotional, off-topic, offensive, scams)
    • Meaningless/gibberish examples
    • Testing scenarios Impact: Improved testing capabilities and documentation

Lessons Learned:

  • Create examples file early in development
  • Include edge cases and boundary conditions
  • Organize examples by category for easy reference
  • Update examples as new patterns emerge

Performance Friction

Chart Rendering

Date: Statistics feature Severity: Low Description:

  • Multiple Chart.js instances created
  • Need to destroy old charts before creating new ones Resolution:
  • Implemented chart instance tracking
  • Destroy charts before recreating Impact: Memory leaks if not handled properly

Lessons Learned:

  • Always clean up chart instances
  • Consider chart lifecycle management

Today's Feedback Filtering

Date: Statistics feature Severity: Low Description:

  • Need to filter feedback by date on client side
  • Fetching all feedback then filtering (inefficient) Resolution:
  • Current implementation works but could be optimized
  • Could add date filter to API endpoint Impact: Fetches more data than needed

Lessons Learned:

  • Consider server-side filtering for better performance
  • Add date range parameters to API

Security Friction

CORS Configuration

Date: API development Severity: Medium Description:

  • Currently allows all origins (*)
  • Not suitable for production Resolution:
  • Documented as security consideration
  • Needs production configuration Impact: Security risk if deployed as-is

Lessons Learned:

  • Configure CORS properly for production
  • Document security considerations
  • Consider environment-based CORS settings

Spam Detection Database Migration

Date: Spam detection feature implementation Severity: High Description:

  • Added is_spam column to database schema
  • Error: table feedback has no column named is_spam: SQLITE_ERROR
  • Migration not applied to existing databases (local and remote) Resolution:
  • Created migration file 0002_add_is_spam_column.sql
  • Need to run: npx wrangler d1 migrations apply feedback-db --local for local
  • Need to run: npx wrangler d1 migrations apply feedback-db --remote for remote Impact: Spam detection feature broken until migration applied

Lessons Learned:

  • Always apply migrations after schema changes
  • Document migration steps clearly
  • Consider auto-migration on startup (with caution)
  • Test migrations on both local and remote environments

Feature Implementation Friction

Spam Detection Implementation

Date: Spam detection feature Severity: Medium Description:

  • Needed to implement spam/offensive content detection
  • Requirement: Skip analysis for spam but still store in database
  • Multiple iterations on user experience (alerts, silent handling) Resolution:
  • Implemented AI-powered spam detection with rule-based fallback
  • Early validation check before analysis
  • Silent spam handling (no alerts)
  • Spam records stored with is_spam flag
  • Visual indicators in UI (red background, SPAM badge) Impact:
  • Improved content moderation
  • Better user experience (no interruption for spam)
  • Database stores spam for moderation purposes

Lessons Learned:

  • Early validation prevents unnecessary processing
  • Silent handling improves UX for automated filtering
  • Store spam records for moderation/audit purposes
  • Visual indicators help identify spam quickly

Spam Detection Flow Complexity

Date: Spam detection feature Severity: Low Description:

  • Multiple validation points (frontend validation, backend validation, analyze endpoint)
  • Need to ensure spam is detected early to skip expensive AI analysis
  • Coordination between validation and analysis endpoints Resolution:
  • Early validation in frontend before calling analyze endpoint
  • Backend analyze endpoint also checks for spam as first step
  • Consistent spam detection logic across endpoints Impact: Slight complexity but ensures spam is caught early

Lessons Learned:

  • Early detection saves resources
  • Consistent detection logic across layers
  • Consider caching validation results

Recommendations for Future Development

  1. Migration System: Implement proper database migration versioning
  2. Testing: Add automated tests for critical paths
  3. Error Handling: Improve error messages and user feedback
  4. Performance: Optimize API queries and add caching where appropriate
  5. Security: Implement proper authentication and CORS configuration
  6. Documentation: Keep docs updated incrementally
  7. Monitoring: Add logging and error tracking
  8. CI/CD: Automate deployment process

Friction Patterns Identified

  1. Environment Differences: Local vs remote inconsistencies
  2. Iterative Changes: Multiple UI/layout iterations
  3. External Dependencies: CDN dependencies and availability
  4. Command Complexity: Multiple similar commands with different flags
  5. Documentation Lag: Docs updated after implementation

Last Updated: 2025-01-21 Total Friction Points Documented: 26+