Skip to content

replit.md

Latest commit

 

History

History
143 lines (111 loc) · 5.87 KB

replit.md

File metadata and controls

143 lines (111 loc) · 5.87 KB
Raw

SWMM5 Import Documentation Portal

Overview

This is a technical documentation portal for SWMM5 (Storm Water Management Model) import functionality into ICM InfoWorks. The application serves as a comprehensive reference guide containing Ruby import scripts, INP file format specifications, ICM engine comparisons, and step-by-step import workflows.

The portal is designed following technical documentation patterns (inspired by GitHub Docs, Read the Docs) with a focus on readability, code clarity, and efficient information architecture. It provides both human-readable documentation and syntax-highlighted code viewing capabilities.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Framework & Build System:

  • React 18 with TypeScript for type safety
  • Vite as the build tool and development server
  • Client-side routing using Wouter (lightweight alternative to React Router)
  • Component library: Radix UI primitives with shadcn/ui styling system

State Management:

  • TanStack Query (React Query) for server state management and API data fetching
  • Local React state for UI interactions
  • No global state management library - relies on React Query's caching and component state

Styling System:

  • Tailwind CSS with custom design tokens
  • CSS variables for theming (light/dark mode support)
  • Custom Tailwind configuration with extended color system
  • Typography: Inter for headings, system fonts for body, JetBrains Mono for code
  • shadcn/ui "new-york" style variant

Key UI Components:

  • CodeViewer: Syntax-highlighted Ruby code display with copy functionality
  • InpFormatReference: Accordion-based section browser with category filtering
  • IcmComparisonTable: Feature comparison table between ICM engines
  • ImportWorkflow: Step-by-step workflow visualization
  • SearchDialog: Global search with keyboard shortcuts

Backend Architecture

Server Framework:

  • Express.js with TypeScript
  • ESM (ES Modules) throughout the codebase
  • HTTP server created with Node's native http module

API Design:

  • RESTful JSON API with four main endpoints:
    • GET /api/scripts - Returns Ruby import scripts
    • GET /api/inp-sections - Returns INP file format sections
    • GET /api/icm-comparison - Returns engine comparison data
    • GET /api/import-steps - Returns workflow steps

Data Storage:

  • In-memory storage implementation (MemStorage class)
  • Data initialized from attached Ruby script files during server startup
  • No database required - all documentation content is statically loaded
  • Schema validation using Zod for type safety

Development Features:

  • Request logging middleware with response time tracking
  • Vite middleware integration for HMR in development
  • Static file serving in production
  • Replit-specific plugins for development (cartographer, dev banner, runtime error overlay)

Data Schema Architecture

Type System:

  • Zod schemas defined in shared/schema.ts for runtime validation
  • TypeScript types inferred from Zod schemas
  • Shared types between frontend and backend

Core Data Models:

  • RubyScript: Code files with metadata (name, description, line count, source code)
  • InpSection: INP file format sections with fields, examples, categories
  • IcmComparison: Engine feature comparisons
  • ImportStep: Workflow steps with sequential ordering

Categories:

  • INP sections organized into 8 categories: Project, Hydrology, Hydraulics, Water Quality, Time Series, Controls, Reporting, Map Data

Build & Deployment

Development:

  • npm run dev - Runs TSX with Vite middleware for hot reload
  • Type checking with tsc --noEmit
  • Path aliases configured for clean imports (@/, @shared/, @assets/)

Production Build:

  • Frontend: Vite builds to dist/public
  • Backend: esbuild bundles server code to dist/index.js
  • ESM output format for modern Node.js runtime
  • External packages not bundled on backend

Configuration Files:

  • tsconfig.json: Shared TypeScript config with path mappings
  • vite.config.ts: Client build config with aliases
  • tailwind.config.ts: Custom design system configuration
  • components.json: shadcn/ui configuration

External Dependencies

UI Component Library

  • Radix UI: Unstyled, accessible component primitives (accordion, dialog, dropdown, tabs, etc.)
  • shadcn/ui: Pre-styled Radix components following "new-york" design system
  • class-variance-authority: Type-safe variant management for components
  • cmdk: Command palette component for search functionality

Database & ORM

  • Drizzle ORM: TypeScript ORM configured for PostgreSQL
  • @neondatabase/serverless: Neon serverless PostgreSQL driver
  • drizzle-zod: Schema-to-Zod validation generator
  • Database configuration in drizzle.config.ts (not currently used but infrastructure present)

Styling & Theming

  • Tailwind CSS: Utility-first CSS framework
  • tailwind-merge & clsx: Utility for conditional class merging
  • Custom CSS variables for comprehensive theming support

Data Fetching & Forms

  • TanStack Query: Server state management with caching, refetching, and optimistic updates
  • React Hook Form: Form state management
  • @hookform/resolvers: Form validation integration
  • Zod: Runtime type validation and schema definition

Development Tools

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

Typography & Fonts

  • Google Fonts: Inter (400-700) for UI, JetBrains Mono (400-500) for code
  • System font stack as fallback

Additional Utilities

  • date-fns: Date manipulation and formatting
  • nanoid: Unique ID generation
  • wouter: Lightweight client-side routing
  • lucide-react: Icon library
  • embla-carousel-react: Carousel/slider component