Skip to content

replit.md

Latest commit

 

History

History
210 lines (161 loc) · 13.3 KB

replit.md

File metadata and controls

210 lines (161 loc) · 13.3 KB

ICMRubyLens - AI-Powered ICM InfoWorks Ruby Code Analyzer

Overview

ICMRubyLens is a developer utility tool that analyzes Ruby code using multiple AI agents to provide comprehensive code insights, improvements, and documentation. The application accepts Ruby source files and optional markdown documentation, then processes them through four AI services (DeepSeek R1, Claude Sonnet 4-5, and two Gemini 2.5 Flash instances) to generate:

  • Code improvement suggestions and refactored code
  • Mermaid architecture diagrams
  • Comprehensive markdown documentation
  • Code pattern analysis and best practices recommendations
  • Alternative implementation approaches and testing strategies

The system is designed with a clean, developer-focused interface inspired by Linear and VS Code aesthetics with a vibrant blue theme, prioritizing information density and code readability. Users can choose between three analysis modes: verbose (detailed), terse (concise), or "Explain Like I'm New" (beginner-friendly with analogies and term definitions).

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Framework: React with TypeScript, using Vite as the build tool and development server.

Routing: Wouter for lightweight client-side routing with a simple home page and 404 fallback.

UI Design System: Shadcn/ui components built on Radix UI primitives with Tailwind CSS for styling. The design follows a "new-york" style variant with custom color tokens and consistent spacing primitives (2, 4, 6, 8 units).

Typography:

  • Inter font for UI elements (weights: 400, 500, 600)
  • JetBrains Mono for code displays
  • Defined hierarchy for page titles, headers, body text, and labels

State Management:

  • TanStack Query (React Query) for server state management and API interactions
  • Local React state for UI-specific concerns (file uploads, agent status)
  • Custom ThemeProvider context for light/dark mode

Key UI Components:

  • IntroSection: Welcome card with workflow diagram and descriptive text explaining the 4-step process (Upload → AI Analysis → View Results → Download)
  • FileUploadZone: Drag-and-drop interface for Ruby and Markdown files with verbosity controls (verbose/terse radio buttons)
  • AIAgentStatus: Enhanced real-time status display with overall processing banner, detailed task sequences (7 steps per agent), percentage indicators, agent specialty descriptions, and highlighted task boxes (supports 4 agents in 2x2 grid layout)
  • CodePanel: Syntax-highlighted code viewer with download functionality
  • DiffViewer: Side-by-side comparison of original and modified code with LCS-based line-level diff highlighting (added/removed/modified lines with color coding and change statistics)
  • MermaidDiagram: Dynamic rendering of architecture diagrams via Mermaid.js CDN
  • MarkdownPreview: Custom markdown renderer with styled elements
  • ThemeProvider: Light/dark mode toggle with localStorage persistence
  • VisualDiagrams: Interactive gallery for Nano Banana ICM Ruby diagrams with thumbnail navigation, zoom controls (50-300%), fullscreen mode, and topic tags

Tab System (9 tabs total):

  • Code Comparison: Side-by-side diff view of original vs AI-modified Ruby code
  • New Ruby Code: Standalone view of AI-generated improved Ruby code
  • Documentation: AI-generated markdown documentation (old format)
  • New Documentation: Standalone view of AI-generated markdown documentation
  • Architecture Diagram: Mermaid visualization of code structure
  • AI Insights: Analysis from all four AI agents (displayed in 2x2 grid)
  • Original Files: Display of uploaded Ruby and Markdown files
  • InfoWorks API Reference: Complete InfoWorks ICM Ruby API documentation viewer with lazy loading
  • Visual Reference: Nano Banana diagram gallery (6 diagrams) covering Ruby API architecture, licensing, database/network objects, and date/time handling

Download Functionality: All outputs are downloadable with "_new" suffix automatically appended to filenames (e.g., mycode.rb becomes mycode_new.rb).

Backend Architecture

Framework: Express.js server with TypeScript in ESM module format.

API Design: RESTful endpoint (POST /api/process) that accepts Ruby content, optional Markdown content, and verbosity preference ('verbose' or 'terse'), orchestrates AI processing, and returns comprehensive analysis results.

Parallel Processing: All four AI agents (DeepSeek, Claude, Gemini, Gemini Pro) run concurrently using Promise.all() to minimize total processing time.

Error Handling:

  • Rate limit retry logic using p-retry library with exponential backoff
  • Comprehensive error detection for quota/rate limit issues
  • Validation using Zod schemas for request/response data

Data Validation: Zod schemas define strict types for:

  • File uploads (filename, content, type)
  • AI processing requests and responses
  • Agent status updates

AI Integration Strategy

Multi-Agent Architecture: Four specialized AI services working in parallel:

  1. DeepSeek (via OpenRouter): Code improvement and refactoring

    • Model: deepseek/deepseek-r1
    • Specialty: Code refactoring & improvements
    • Outputs: Modified Ruby code and detailed suggestions
    • Max tokens: 8192

  2. Claude (via Anthropic SDK): Documentation and architecture visualization

    • Model: claude-sonnet-4-5
    • Specialty: Architecture diagrams & documentation
    • Outputs: Mermaid diagrams, markdown documentation, code analysis
    • Max tokens: 8192

  3. Gemini (via Google GenAI): Pattern analysis and best practices

    • Model: gemini-2.5-flash
    • Specialty: Pattern analysis & best practices
    • Outputs: Code patterns, potential issues, security considerations, performance optimization recommendations

  4. Gemini Pro (via Google GenAI): Alternative approaches and testing strategies

    • Model: gemini-2.5-flash
    • Specialty: Testing strategies & alternatives
    • Outputs: Code quality assessment, alternative implementations, testing recommendations, design pattern analysis

Verbosity Control: All AI agents respect the user's verbosity preference:

  • Verbose Mode: Comprehensive analysis (800+ words per agent) with detailed explanations, code examples, and thorough coverage
  • Terse Mode: Concise analysis (200-300 words per agent) with brief bullet points and focus on critical issues only
  • Explain Like I'm New Mode: Beginner-friendly analysis (500-600+ words per agent) with everyday language, real-world analogies, inline term definitions, and step-by-step explanations assuming zero ICM Ruby experience

Confidence Scoring: The Diagnostics tab shows quantitative consensus with "X/4 agents agree" indicators, progress bars, and summary badges (Unanimous/Strong/Partial) for each finding.

"Fix It For Me" Button: Priority fixes in the Diagnostics tab include a "Fix It For Me" button that uses Gemini to auto-apply the specific fix to the code. The fixed code updates the Code Comparison tab in real-time. Endpoint: POST /api/fix accepts rubyCode, fixDescription, and fixTitle.

Replit AI Integrations: All AI services use Replit's AI Integrations service for simplified authentication and rate limiting, configured via environment variables:

  • AI_INTEGRATIONS_OPENROUTER_BASE_URL and AI_INTEGRATIONS_OPENROUTER_API_KEY
  • AI_INTEGRATIONS_ANTHROPIC_BASE_URL and AI_INTEGRATIONS_ANTHROPIC_API_KEY
  • AI_INTEGRATIONS_GEMINI_BASE_URL and AI_INTEGRATIONS_GEMINI_API_KEY

Resilience Pattern: Each AI service implements retry logic with rate limit detection (using p-retry library), ensuring the application handles quota limits gracefully with exponential backoff.

InfoWorks Documentation Integration (RAG System): The application includes a retrieval-augmented generation (RAG) system that provides relevant InfoWorks ICM Ruby API context to all AI agents:

  • Documentation Corpus: Merged comprehensive documentation from three complementary sources:
    • API Reference (6,761 lines → 124 chunks): Technical API documentation with class references, method signatures, and database operations
    • Ruby Scripting Overview (703 lines → 13 chunks): Practical usage patterns, complete code examples, workflow guidance, and best practices
    • ICM 2026 Documentation Index (703 lines → 7 chunks): Structured index of all InfoWorks ICM 2026 help sections, class reference URLs, crawl plans, cloud integration notes, and external resources from Autodesk help portal
    • Total: 144 structured JSON chunks, totaling ~66,000 tokens
    • Raw Index File: server/docs/icm_documentation_index.json — complete ICM 2026 documentation hierarchy with GUIDs, URLs, extraction status, and crawl plan metadata
  • Coverage: Complete InfoWorks ICM Ruby ecosystem including:
    • Introduction to Scripts & Ruby conventions
    • Running scripts from UI and Exchange (ICMExchange/IExchange)
    • Working with Database (WSDatabase, WSModelObject classes)
    • Model object access methods (by GUID, ID, path, name)
    • Working with Networks (WSOpenNetwork, WSRowObject)
    • Row object operations, field access, navigation
    • DateTime handling, binary/structured data
    • Simulation creation and job control workflows
    • Import/export patterns (CSV, GIS, ODEC/ODIC)
    • Time series database (TSD) operations
    • Real-world code examples and mini recipe book
  • Storage: Static JSON file at server/docs/infoworks_ruby_api.json containing title, keywords, and content for each chunk
  • DocRetriever Service (server/ai/docRetriever.ts):
    • Performs keyword-based relevance scoring to match code content with documentation
    • Returns top 3 most relevant chunks (~1,455 tokens average) to stay within model context limits
    • Enhanced keyword extraction with 50+ InfoWorks-specific terms and class-name pattern matching
    • Regex escaping for special characters to prevent crashes
    • Provides graceful fallback if documentation fails to load
    • Offers getAsMarkdown() method to serve complete documentation to the UI
  • AI Agent Integration: All 4 agents accept optional markdownContent parameter and inject relevant InfoWorks API context into their prompts
  • Token Budget Management: Documentation context is capped at 2,000 tokens per agent to prevent prompt overflow while maintaining useful context
  • API Endpoint: GET /api/docs/infoworks serves the complete InfoWorks API reference for the documentation viewer tab
  • Processing Pipeline: Custom script (scripts/process-infoworks-docs.ts) handles both plain-text (API reference) and markdown (scripting guide) formats, intelligently detects section boundaries, handles Windows line endings, and splits large sections for optimal chunk sizing

Data Storage

Current Implementation: In-memory storage using a Map-based implementation (MemStorage class) for user data.

Schema Definition: Database schema defined in shared/schema.ts using Drizzle ORM with TypeScript types, prepared for PostgreSQL migration.

Migration Strategy: Drizzle Kit configured for PostgreSQL with schema in shared/schema.ts and migrations in ./migrations directory. The application is ready to transition from in-memory to persistent database storage.

Development Workflow

Build Process:

  • Development: tsx for TypeScript execution with hot reload
  • Production: Vite builds client assets, esbuild bundles server code
  • Output: Client to dist/public, server to dist/index.js

Vite Configuration:

  • Custom aliases for @/ (client), @shared/ (shared schemas), @assets/ (assets)
  • Development middleware mode for HMR
  • Replit-specific plugins for error overlay and dev tools

Type Safety: Strict TypeScript configuration with path mapping, ensuring compile-time type checking across client, server, and shared code.

External Dependencies

Third-Party UI Libraries

  • Radix UI: Comprehensive set of accessible, unstyled React components (accordion, dialog, dropdown, popover, tabs, toast, etc.)
  • Tailwind CSS: Utility-first CSS framework with custom configuration for design system
  • shadcn/ui: Pre-built component library following the "new-york" style variant
  • Lucide React: Icon library for consistent iconography
  • Mermaid.js: Diagram rendering loaded via CDN for architecture visualization

AI Service Providers

  • Anthropic SDK (@anthropic-ai/sdk): Claude API integration
  • Google GenAI SDK (@google/genai): Gemini API integration
  • OpenAI SDK (openai): GPT-4o and OpenRouter/DeepSeek integration
  • Replit AI Integrations: Managed AI service endpoints with built-in rate limiting and automatic authentication

Supporting Libraries

  • TanStack Query: Async state management and server data caching
  • React Hook Form + Zod resolvers: Form handling and validation
  • Wouter: Lightweight routing solution
  • date-fns: Date manipulation utilities
  • multer: Multipart form data handling for file uploads
  • p-retry: Retry logic with exponential backoff for API calls

Database (Prepared)

  • Drizzle ORM: Type-safe database toolkit
  • @neondatabase/serverless: PostgreSQL driver for Neon database
  • connect-pg-simple: PostgreSQL session store (for future session management)

Development Tools

  • Vite: Fast build tool and dev server
  • esbuild: JavaScript bundler for production builds
  • tsx: TypeScript execution for development
  • @replit/vite-plugin-*: Replit-specific development experience enhancements