A developer-focused web application for analyzing InfoWorks ICM Ruby scripts with multiple AI agents, generated documentation, architecture diagrams, code improvements, and embedded API reference material.
Repository: SWMMEnablement/RubyMakerAI
Replit app: replit.com/@robertdickinson/RubyMakerAI
ICMRubyLens is a full-stack TypeScript application built to help engineers and developers understand, improve, document, and refactor InfoWorks ICM Ruby code. It accepts uploaded Ruby source files and optional Markdown context, then sends the content through four AI analysis agents in parallel to produce improved code, architecture diagrams, markdown documentation, code-quality insights, and alternative implementation guidance. [page:44]
The app is specifically designed for the InfoWorks ICM Ruby ecosystem, not for generic Ruby development alone. Its retrieval system includes a built-in knowledge base for InfoWorks Ruby scripting, API classes, database/network object access, exchange workflows, simulations, imports/exports, TSD operations, and practical scripting examples. [page:44]
For each uploaded Ruby file, ICMRubyLens can generate:
- Refactored or improved Ruby code. [page:44]
- AI-authored markdown documentation. [page:44]
- Mermaid architecture diagrams. [page:44]
- Pattern analysis and best-practices recommendations. [page:44]
- Code-quality findings and possible issues. [page:44]
- Alternative implementation ideas and testing strategies. [page:44]
The UI is described in the handover as a developer-focused interface inspired by Linear and VS Code, with an emphasis on information density, readability, and fast comparison between original and improved outputs. [page:44]
The product workflow is simple from the user’s perspective:
- Upload a Ruby file and, optionally, a Markdown file with context or notes. [page:44]
- Choose one of the three verbosity modes: Verbose, Terse, or Explain Like I’m New. [page:44]
- Start analysis, which triggers all four AI agents in parallel. [page:44]
- Review code diffs, new code, generated documentation, architecture diagrams, and AI-specific insights. [page:44]
- Download outputs with automatically suffixed filenames such as
my_script_new.rb. [page:44]
This flow is surfaced visually in the app through the IntroSection, FileUploadZone, and AIAgentStatus components. [page:44]
The system uses a multi-agent architecture in which four AI services run concurrently via Promise.all(). Each agent has a different specialty and contributes a different type of output. [page:44]
| Agent | Model | Role | Main outputs |
|---|---|---|---|
| DeepSeek | deepseek/deepseek-r1 via OpenRouter |
Code refactoring and improvements | Improved Ruby code and detailed suggestions [page:44] |
| Claude | claude-sonnet-4-5 via Anthropic SDK |
Architecture and documentation | Mermaid diagrams, markdown docs, code analysis [page:44] |
| Gemini | gemini-2.5-flash |
Pattern analysis and best practices | Patterns, risks, performance ideas, security notes [page:44] |
| Gemini Pro | gemini-2.5-flash |
Alternative approaches and testing strategies | Testing ideas, alternate implementations, design-pattern commentary [page:44] |
The app also includes a Diagnostics tab with consensus indicators such as “X/4 agents agree,” and a “Fix It For Me” workflow that can auto-apply a selected Gemini-generated fix to the uploaded Ruby code. That fix updates the code-comparison output in real time. [page:44]
All AI agents respect a shared verbosity setting selected by the user. The three documented modes are: [page:44]
- Verbose — detailed analysis, roughly 800+ words per agent. [page:44]
- Terse — short analysis, roughly 200–300 words per agent. [page:44]
- Explain Like I’m New — beginner-friendly analysis using simple language, analogies, and inline term definitions, roughly 500–600+ words per agent. [page:44]
This makes the same underlying tool useful for experienced scripters, occasional Ruby users, and newcomers to the InfoWorks ICM API. [page:44]
The frontend is a React + TypeScript app using Vite, Wouter, TanStack Query, Tailwind CSS, and shadcn/ui. The handover lists 9 major tabs in the UI. [page:44]
| Tab | Purpose |
|---|---|
| Code Comparison | Side-by-side diff of original vs AI-modified Ruby code. [page:44] |
| New Ruby Code | Clean standalone view of the AI-generated improved Ruby code. [page:44] |
| Documentation | AI-generated markdown documentation in the older/original format. [page:44] |
| New Documentation | Standalone view of the AI-generated documentation output. [page:44] |
| Architecture Diagram | Mermaid rendering of the script architecture and flow. [page:44] |
| AI Insights | Analysis from all four agents in a 2×2 grid. [page:44] |
| Original Files | Display of the uploaded Ruby and Markdown sources. [page:44] |
| InfoWorks API Reference | Lazy-loaded viewer for the full InfoWorks ICM Ruby API documentation. [page:44] |
| Visual Reference | Gallery of six Nano Banana diagrams covering Ruby API architecture, licensing, network objects, and date/time handling. [page:44] |
The interface also includes drag-and-drop uploads, a theme switcher, file download actions, and a live multi-agent status display with step-by-step progress. [page:44]
The handover identifies several important frontend components and their roles: [page:44]
IntroSection— welcome card and 4-step workflow overview. [page:44]FileUploadZone— drag-and-drop file area with verbosity controls. [page:44]AIAgentStatus— real-time status display for all four agents with progress and specialty labels. [page:44]CodePanel— syntax-highlighted code display. [page:44]DiffViewer— side-by-side comparison using LCS-based line-level diffing and change statistics. [page:44]MermaidDiagram— dynamic architecture-diagram rendering via Mermaid.js. [page:44]MarkdownPreview— styled markdown renderer. [page:44]ThemeProvider— dark/light mode with localStorage persistence. [page:44]VisualDiagrams— interactive gallery of Nano Banana visual reference diagrams. [page:44]
These pieces make the app feel closer to a lightweight AI coding workstation than a simple upload form. [page:44]
A major part of the app’s value is its RAG-style documentation layer. The handover describes a built-in InfoWorks documentation corpus assembled from three main sources, totaling 144 structured JSON chunks and about 66,000 tokens. [page:44]
Those sources include:
- API Reference — 6,761 lines converted into 124 chunks. [page:44]
- Ruby Scripting Overview — 703 lines converted into 13 chunks. [page:44]
- ICM 2026 Documentation Index — 703 lines converted into 7 chunks, including Autodesk help hierarchy and GUID-linked references. [page:44]
This corpus covers the practical InfoWorks ICM Ruby environment, including scripts, database access, model objects, networks, row objects, simulations, import/export workflows, time series database operations, and example scripting recipes. [page:44]
Documentation retrieval is handled by server/ai/docRetriever.ts, which performs keyword-based relevance scoring, enhanced InfoWorks term matching, and class-name pattern matching. It returns the top three most relevant chunks, with a typical context budget around 1,455 tokens and a hard cap of 2,000 tokens per agent to avoid prompt overflow. [page:44]
A dedicated endpoint, GET /api/docs/infoworks, serves the complete API reference to the documentation viewer. The raw knowledge files include server/docs/infoworks_ruby_api.json and server/docs/icm_documentation_index.json. [page:44]
The backend uses Express.js with TypeScript in ESM format and exposes a REST-style processing endpoint. The main documented analysis route is POST /api/process, which accepts Ruby content, optional Markdown content, and verbosity preference, then orchestrates all four AI agents and returns their outputs in a structured response. [page:44]
The app also exposes POST /api/fix for the “Fix It For Me” workflow. This endpoint accepts the original Ruby code plus a selected fix description/title and uses Gemini to apply the specific repair automatically. [page:44]
The backend uses:
- Zod schemas for strict validation of requests, file metadata, AI responses, and status updates. [page:44]
- p-retry with exponential backoff for AI-service resilience. [page:44]
- Explicit quota and rate-limit detection to handle AI provider throttling gracefully. [page:44]
This design is important because the product depends on multiple external AI services running in parallel. [page:44]
The repository is primarily TypeScript (96.6%) with a small CSS footprint. GitHub’s language breakdown matches the architecture described in the handover. [page:43]
- React + TypeScript. [page:44]
- Vite. [page:44]
- Wouter. [page:44]
- TanStack Query. [page:44]
- Tailwind CSS. [page:44]
- shadcn/ui + Radix UI. [page:44]
- Lucide React. [page:44]
- Mermaid.js via CDN. [page:44]
- Express.js with TypeScript and ESM modules. [page:44]
- Multer for multipart uploads. [page:44]
- Zod for validation. [page:44]
- p-retry for resilient AI calls. [page:44]
- Anthropic SDK for Claude. [page:44]
- Google GenAI SDK for Gemini. [page:44]
- OpenAI SDK for OpenRouter/DeepSeek-style integration. [page:44]
- Replit AI Integrations for managed base URLs, auth, and rate-limit handling. [page:44]
- Drizzle ORM. [page:44]
- Neon/PostgreSQL driver support. [page:44]
connect-pg-simplefor future session persistence. [page:44]
The app currently uses a Map-based in-memory MemStorage for user data but is structurally prepared to migrate to PostgreSQL later. [page:44]
The repository layout shown on GitHub and described in replit.md is: [page:43][page:44]
RubyMakerAI/
├── attached_assets/ # Ruby/ICM support assets and knowledge-base files
├── client/ # React frontend
├── scripts/ # Documentation-processing scripts
├── server/ # Express backend and AI orchestration
├── shared/ # Shared schemas and types
├── .replit # Replit runtime config
├── components.json # shadcn/ui config
├── design_guidelines.md # UI/design notes
├── drizzle.config.ts # Drizzle ORM config
├── package.json # Scripts and dependencies
├── postcss.config.js
├── replit.md # Main architectural handover
├── tailwind.config.ts
├── tsconfig.json
└── vite.config.ts
The commit history also shows notable enhancements such as InfoWorks ICM documentation added to the knowledge base, Gemini integration, API reference documentation, “Explain Like I’m New,” and the “Fix It For Me” workflow. [page:43]
npm installnpm run devThe documented development workflow uses tsx for TypeScript execution, Vite middleware for hot reload, and shared path aliases such as @/, @shared/, and @assets/. Production builds compile the client to dist/public and bundle the server to dist/index.js with esbuild. [page:44]
The AI providers are configured through Replit AI Integration environment variables, including: [page:44]
AI_INTEGRATIONS_OPENROUTER_BASE_URLAI_INTEGRATIONS_OPENROUTER_API_KEYAI_INTEGRATIONS_ANTHROPIC_BASE_URLAI_INTEGRATIONS_ANTHROPIC_API_KEYAI_INTEGRATIONS_GEMINI_BASE_URLAI_INTEGRATIONS_GEMINI_API_KEY
These variables allow the app to call the AI services without hardcoding provider credentials in the codebase. [page:44]
ICMRubyLens is especially useful for:
- InfoWorks ICM users writing or reviewing Ruby scripts. [page:44]
- Engineers who inherited legacy automation scripts and need to understand them faster. [page:44]
- Teams building internal Ruby utilities for network editing, simulations, or data exchange. [page:44]
- Users who want both conceptual explanation and concrete code improvements in one place. [page:44]
The “Explain Like I’m New” mode also makes the tool practical for onboarding engineers who know hydraulics but are new to the InfoWorks Ruby API. [page:44]
The most important project documentation currently lives in replit.md, which describes the architecture, AI agents, RAG system, endpoints, storage model, UI components, and external dependencies in substantial detail. The GitHub repository currently has no README, so replacing the placeholder with this project-specific version will make the repo much more understandable to visitors and contributors. [page:43][page:44]
Add the appropriate license here if the repository is intended for public reuse.