BobSWMM Auto Research

An AI-powered deep research tool for EPA SWMM5 (Storm Water Management Model), inspired by deep-research workflows and tailored for stormwater engineers, hydraulic modelers, and SWMM practitioners.

BobSWMM Auto Research is a full-stack TypeScript monorepo that generates grounded technical research reports on SWMM5 topics using AI plus an embedded retrieval-augmented knowledge base. It combines domain-specific presets, streamed report generation, engineering calculators, model QA/QC tools, and SWMM reference utilities in a single web app.

Purpose

The application is built for users who need fast, technically useful answers about SWMM5 hydrology, hydraulics, water quality, calibration, and model interpretation. It supports both open-ended research queries and structured engineering workflows such as .inp review, .rpt diagnostics, design storm setup, unit conversion, and parameter estimation.

Main capabilities

Research and reporting

• Free-form SWMM5 topic research with AI-generated reports and citations.
• Three research depths: Quick (800–1200 words), Standard (2000–3000 words), and Deep (4000–6000 words).
• More than 54 preset research templates across 13 categories, each with emoji icons and system prompts.
• Markdown export, .md download, and print-to-PDF style output for reports.
• KaTeX rendering for equations in technical writeups.

Grounded SWMM knowledge

The RAG layer injects curated SWMM5 reference material into research prompts when topic matches are found. The embedded topics include Green-Ampt, Horton, Curve Number, Dynamic Wave, RTK/RDII, Surcharging, Manning, and LID-Bioretention, with parameter tables, equations, and source-code references.

Interactive tools

The frontend includes six hydraulic calculators: Green-Ampt, Horton, Curve Number, RTK/RDII, Manning’s Pipe, and Surcharge. It also includes a parameter estimation wizard, a unit conversion hub, a design storm library, a PySWMM code generator, and an ICM translation helper for SWMM5-to-ICM mapping.

Model review tools

The app provides client-side .inp parsing, section-aware .inp differencing, automated model QA/QC review, and a dashboard for .rpt health assessment. These features help identify issues such as continuity errors, flooded or surcharged nodes, short pipes, orphaned nodes, and missing sections.

Reference and learning features

Additional pages include a SWMM5 source-code cross-reference, error-code encyclopedia, historical timeline, section explainer, community hub, model comparison page, and a learning log that tracks matched RAG topics by session.

Tech stack

Layer	Technology
Monorepo	pnpm workspaces
Runtime	Node.js 24
Language	TypeScript 5.9
Backend	Express 5
Database	PostgreSQL with Drizzle ORM
Validation	Zod v4 and drizzle-zod
API generation	Orval from OpenAPI spec
Build	esbuild using a CommonJS bundle
AI integration	OpenAI via Replit AI Integrations using gpt-5.2
Frontend	React, Vite, Tailwind CSS, shadcn/ui, and Recharts

Repository structure

artifacts-monorepo/
├── artifacts/
│   ├── api-server/
│   │   └── src/
│   │       ├── routes/
│   │       │   ├── research.ts
│   │       │   └── openai.ts
│   │       └── lib/
│   │           ├── swmm5-presets.ts
│   │           └── rag-knowledge.ts
│   └── bob-swmm/
│       └── src/
│           ├── pages/
│           └── lib/
│               ├── source-code-map.ts
│               └── inp-parser.ts
├── lib/
│   ├── api-spec/
│   ├── api-client-react/
│   ├── api-zod/
│   ├── db/
│   └── integrations-openai-ai-server/
├── scripts/
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── tsconfig.json
└── package.json

The backend exposes research and chat routes, while the frontend hosts the research UI, calculators, file tools, and reference pages. Generated client hooks and schemas live under lib/api-client-react and lib/api-zod, while database schema and connectivity live under lib/db.

Key files

• artifacts/api-server/src/routes/research.ts — research presets, research-session endpoints, and SSE-based report streaming.
• artifacts/api-server/src/routes/openai.ts — chat conversation endpoints and SSE chat streaming.
• artifacts/api-server/src/lib/swmm5-presets.ts — preset research topics and prompt definitions.
• artifacts/api-server/src/lib/rag-knowledge.ts — embedded RAG knowledge base with SWMM equations, parameters, and references.
• artifacts/bob-swmm/src/lib/inp-parser.ts — client-side .inp parsing support.
• artifacts/bob-swmm/src/lib/source-code-map.ts — source-code function mappings and community links.

Data model

The database includes three named tables: conversations, messages, and research_sessions. The research_sessions table stores the query, depth, status, report text, sources, and a ragTopics array backed by a text[] column.

API endpoints

Research API

Method	Endpoint	Description
GET	/api/research/presets	Returns preset research topics and icons.
POST	/api/research/start	Starts research with SSE streaming and RAG context injection.
GET	/api/research/sessions	Lists saved research sessions, including RAG matches.
GET	/api/research/sessions/:id	Returns a single session and its report details.
DELETE	/api/research/sessions/:id	Deletes a saved session.

Chat API

Method	Endpoint	Description
GET	/api/openai/conversations	Lists chat conversations.
POST	/api/openai/conversations	Creates a new conversation.
GET	/api/openai/conversations/:id	Returns a conversation and its messages.
DELETE	/api/openai/conversations/:id	Deletes a conversation.
POST	/api/openai/conversations/:id/messages	Sends a message and streams the reply.

Research stream events

Research output is streamed using SSE events including status, session_id, rag_matches, content, and sources, followed by a completion payload with done: true and the final sessionId.

Frontend pages and modules

The documented frontend includes pages for home, presets, active research, research detail, history, chat, calculators, compare models, INP analyzer, source-code lookup, community resources, knowledge base, learning log, error codes, parameter wizard, unit converter, design storms, INP diff, model review, RPT dashboard, ICM translator, PySWMM code generation, timeline, and section explainer.

Setup

Prerequisites

• Node.js 24 or later.
• pnpm.
• PostgreSQL.
• OpenAI access via Replit AI Integrations.

Environment variables

AI_INTEGRATIONS_OPENAI_BASE_URL=<openai-base-url>
AI_INTEGRATIONS_OPENAI_API_KEY=<openai-api-key>
DATABASE_URL=<postgres-connection-string>

The repository notes that the AI integration depends on AI_INTEGRATIONS_OPENAI_BASE_URL and AI_INTEGRATIONS_OPENAI_API_KEY. It also notes that the model is gpt-5.2 and that max_completion_tokens should be used instead of max_tokens.

Common commands

pnpm install
pnpm run build
pnpm run typecheck
pnpm --filter @workspace/api-spec run codegen

The root build runs type-checking first and then recursively builds all packages. The codegen command regenerates API client hooks and Zod schemas from the API spec.

Notes for maintainers

• Generated code in lib/api-zod/src/generated/ and lib/api-client-react/src/generated/ is described as manually maintained, or not yet fully auto-generated by Orval.
• Database table names are conversations and messages, not camelCase variants.
• The ragTopics field in research_sessions is backed by a text[] column and was migrated manually.
• KaTeX CSS is imported in markdown.tsx, with dark-mode overrides in index.css.
• The frontend uses Recharts, including components such as CartesianGrid and ReferenceLine, for live calculator charts.
• The CSS note for hydro-gradient states it is plain CSS and cannot be used inside Tailwind @apply.

Audience

This repository is especially relevant for EPA SWMM5 users, drainage modelers, stormwater engineers, CSO/SSO analysts, consultants, and educators who want an AI-assisted technical workspace grounded in SWMM domain knowledge rather than a general-purpose chatbot.

Related links

• Repository on GitHub
• Live Replit app

License

No explicit license text was visible in the repository context that was reviewed. If open-source distribution is intended, adding a license file would make reuse terms clear for