Folo/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Follow (Folo) is a modern RSS aggregator and content management platform with multiple applications across different platforms. It's built as a monorepo using pnpm workspaces with Turbo for build orchestration.

Repository Structure

Applications (apps/)

• apps/desktop/ - Electron desktop application with main and renderer processes
• apps/mobile/ - React Native mobile app for iOS and Android
• apps/ssr/ - Server-side rendered web application
• apps/mobile/web-app/ - HTML renderer for mobile web views

Packages (packages/)

• packages/internal/ - Internal shared packages (components, database, hooks, store, etc.)
• packages/configs/ - Shared configuration files (Tailwind, TypeScript)
• packages/utils/ - Utility functions and helpers
• packages/readability/ - Content readability parsing
• packages/vite-plugin-route-builder/ - Custom Vite plugin for route generation

Essential Commands

Development

# Install dependencies (from root)
pnpm install

# Desktop app development (browser - recommended)
cd apps/desktop && pnpm run dev:web

# Desktop app development (Electron)
cd apps/desktop && pnpm run dev:electron

# Mobile app development
cd apps/mobile && pnpm run dev

# SSR development
cd apps/ssr && pnpm run dev

# Build web version
pnpm run build:web

Code Quality

# Lint all code
pnpm run lint

# Fix linting issues
pnpm run lint:fix

# TypeScript linting
pnpm run lint:tsl

# Format code
pnpm run format

# Type checking
pnpm run typecheck

# Run tests
pnpm run test

Package Management

# Build shared packages
pnpm run build:packages

# Generate i18n templates
pnpm run generator:i18n-template

# Sync icons from SVG to React Native
pnpm run icons:sync

Architecture Guidelines

Multi-Platform Architecture

• Desktop: Electron app with main/renderer processes, using Vite for both
• Mobile: React Native with Expo, shared UI components with web
• Web/SSR: Next.js-style SSR application for server-side rendering
• Shared Logic: Common business logic in packages/internal/

State Management

• Jotai for atomic state management across all platforms
• Zustand for complex state stores (in packages/internal/store/)
• React Query for server state management

Styling

• Tailwind CSS for styling across all platforms
• Platform-specific Tailwind configs in each app
• Shared Tailwind utilities in packages/configs/tailwindcss/
• UI Design Style: Follow Vercel and Linear SaaS UI aesthetics - clean, modern, minimal design with subtle shadows, rounded corners, and excellent typography

UIKit Colors for Desktop Components

For desktop components (apps/desktop/**/*) and shared UI components (packages/internal/components/**/*), use Apple UIKit color system with Tailwind classes. Important: Always use the correct Tailwind prefix for each color category:

System Colors: text-red, bg-red, border-red (same for orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown, gray)

Fill Colors:

• Background: bg-fill, bg-fill-secondary, bg-fill-tertiary, bg-fill-quaternary, bg-fill-quinary, bg-fill-vibrant, bg-fill-vibrant-secondary, bg-fill-vibrant-tertiary, bg-fill-vibrant-quaternary, bg-fill-vibrant-quinary
• Border: border-fill, border-fill-secondary, etc.

Text Colors: text-text, text-text-secondary, text-text-tertiary, text-text-quaternary, text-text-quinary, text-text-vibrant, text-text-vibrant-secondary, text-text-vibrant-tertiary, text-text-vibrant-quaternary, text-text-vibrant-quinary

Material Colors: bg-material-ultra-thick, bg-material-thick, bg-material-medium, bg-material-thin, bg-material-ultra-thin, bg-material-opaque

Control Colors: bg-control-enabled, bg-control-disabled

Interface Colors: bg-menu, bg-popover, bg-titlebar, bg-sidebar, bg-selection-focused, bg-selection-focused-fill, bg-selection-unfocused, bg-selection-unfocused-fill, bg-header-view, bg-tooltip, bg-under-window-background

These colors automatically adapt to light/dark mode following Apple's design system. Remember to use the appropriate prefix (text-, bg-, border-) based on the CSS property you're styling.

Icons

For icon usage, prioritize the MingCute icon library with the i-mgc- prefix. Icons are available in the format i-mgc-[icon-name]-[style] where style can be re (regular), fi (filled), etc.

Important: Always try to find an appropriate icon with the i-mgc- prefix first. Only use the i-mingcute- prefix as a fallback when no suitable i-mgc- icon exists.

Examples:

• Preferred: i-mgc-copy-cute-re, i-mgc-external-link-cute-re
• Fallback only: i-mingcute-copy-line (only if no mgc equivalent exists)

Database

• Drizzle ORM with SQLite for local data storage
• Platform-specific database implementations in packages/internal/database/
• Migration system with versioned SQL files

Internationalization

• i18next for internationalization
• Locale files in locales/ directory organized by feature
• Custom ESLint rules for i18n validation

i18n Writing Guidelines

1. Follow i18next formatting guidelines
2. Use flat keys only - Use . notation for separation, no nested objects
3. For plural-sensitive languages, use _one and _other suffixes
4. Avoid conflicting flat keys - During build, flat dot-separated keys (e.g., 'exif.custom.rendered.custom') are automatically converted to nested objects, which can cause conflicts. For example, 'exif.custom.rendered.custom' conflicts with 'exif.custom.rendered'. Avoid such patterns.

Example:

{
  "personalize.title": "Personalization",
  "personalize.prompt.label": "Personal Prompt",
  "shortcuts.add": "Add Shortcut",
  "shortcuts.validation.required": "Name and prompt are required"
}

Development Setup Notes

Prerequisites

• Enable Corepack: corepack enable && corepack prepare
• For mobile development: macOS with Xcode required

Environment Setup

• Copy .env.example to .env in relevant app directories
• For development, use VITE_API_URL=https://api.follow.is
• Browser development uses https://app.folo.is/__debug_proxy for API access

Mobile Development

• iOS development requires Xcode and iOS simulator
• Native module development in apps/mobile/native/
• Use pnpm expo prebuild --clean for clean builds

Code Organization Patterns

Import Conventions

• Use pathe instead of node:path for cross-platform compatibility
• Shared utilities should be imported from packages/internal/
• Platform-specific code should be clearly separated

Component Structure

• Shared UI components in packages/internal/components/
• Platform-specific components in respective app directories
• Use TypeScript interfaces for component props

Error Handling

• Custom error parsing utilities in packages/internal/utils/
• Sentry integration for error reporting across platforms

Build and Deployment

Build Outputs

• Desktop: apps/desktop/out/ for packaged applications
• Web: apps/desktop/out/web/ for static web assets
• Mobile: Platform-specific build directories

Turbo Configuration

• Build orchestration via turbo.json
• Dependency-aware builds with output caching
• Parallel execution for independent packages

Testing Strategy

• Vitest for unit testing across packages
• Platform-specific test configurations
• Test files co-located with source code

Key Dependencies

• Build: Vite, Turbo, pnpm workspaces
• Frontend: React 19, Electron, React Native, Expo
• State: Jotai, Zustand, TanStack Query
• Styling: Tailwind CSS, Framer Motion
• Database: Drizzle ORM, SQLite
• Utils: Day.js, Zod, i18next

Specialized Agent Usage Guidelines

Claude Code has access to specialized agents for different development tasks. Always use the most appropriate agent based on the task requirements:

🧭 tech-lead-orchestrator (Project Management & Quality)

Use when:

• Coordinating complex features across multiple components/platforms
• Conducting project quality assessments and code reviews
• Planning large refactoring efforts or architectural changes
• Breaking down complex tasks into manageable subtasks
• Managing cross-platform consistency and standards

Examples: "Implement RSS feed management system", "Review codebase quality", "Plan state management refactor"

⚛️ react-architect (React Architecture & Performance)

Use when:

• Optimizing React component performance and re-rendering issues
• Designing component architecture and data flow patterns
• Implementing complex state management with Jotai/Zustand
• Reviewing React code patterns and best practices
• Solving React-specific performance bottlenecks

Examples: "Component re-renders too much", "Design data visualization architecture", "Optimize React Query usage"

🎨 ui-design-engineer (UI/UX & Components)

Use when:

• Creating or modifying UI components with Tailwind CSS
• Implementing animations with Framer Motion
• Following Apple HIG and modern SaaS design patterns
• Ensuring accessibility and responsive design
• Integrating with UIKit color system and design tokens

Examples: "Create modal component", "Improve visual hierarchy", "Add micro-interactions"

🔗 platform-integration-specialist (Cross-Platform Features)

Use when:

• Implementing features that work across Electron, React Native, and Web
• Handling platform-specific APIs and native integrations
• Managing cross-platform data synchronization
• Creating unified abstractions for platform differences
• Working with Electron main/renderer processes

Examples: "Add notifications across all platforms", "Implement file system access", "Cross-platform deep linking"

📰 content-processing-expert (RSS & Content Handling)

Use when:

• Working with RSS/Atom feed parsing and processing
• Enhancing content extraction and readability
• Implementing content sanitization and security
• Optimizing feed discovery and update mechanisms
• Processing different content types (articles, podcasts, media)

Examples: "Fix RSS parsing issues", "Improve article extraction", "Add new feed format support"

🗄️ data-architect (Database & Data Management)

Use when:

• Designing database schemas and migrations with Drizzle ORM
• Optimizing SQLite performance and query efficiency
• Planning data synchronization strategies
• Creating data access patterns and caching layers
• Managing database performance and scaling

Examples: "Add user preferences table", "Optimize feed loading queries", "Design migration strategy"

⚡ performance-specialist (Performance & Optimization)

Use when:

• Analyzing and fixing performance issues (memory, CPU, rendering)
• Optimizing Vite build times and bundle sizes
• Implementing code splitting and lazy loading
• Monitoring and improving Core Web Vitals
• Debugging memory leaks and performance bottlenecks

Examples: "App feels sluggish", "Bundle size too large", "Memory usage growing"

🧪 test-engineer (Testing & Quality Assurance)

Use when:

• Designing comprehensive testing strategies
• Implementing unit, integration, and E2E tests
• Setting up test automation and CI/CD testing
• Fixing flaky tests and improving test reliability
• Creating testing utilities and mock strategies

Examples: "Add tests for AI chat feature", "Fix failing test suite", "Improve test coverage"

🎯 Agent Selection Guidelines

For multi-domain tasks, start with tech-lead-orchestrator to coordinate other agents.

Common combinations:

• New feature: tech-lead-orchestrator → ui-design-engineer + data-architect + test-engineer
• Performance issues: performance-specialist + react-architect
• Content problems: content-processing-expert + data-architect
• Cross-platform features: platform-integration-specialist + tech-lead-orchestrator

Always specify the agent explicitly when the task matches their domain expertise.

Agent Usage Notes

• Primary web app is at @apps/desktop/layer/renderer - A Vite + React SPA, not full Electron features
• SSR app is minimal - Only for external sharing pages, not main development focus
• Mobile app - React Native with Expo for iOS/Android
• Always use Task tool with appropriate agent - Don't implement complex features directly, delegate to specialized agents