Skip to content

replit.md

Latest commit

 

History

History
161 lines (127 loc) · 7.62 KB

replit.md

File metadata and controls

161 lines (127 loc) · 7.62 KB

TruEstate Retail Sales Management System

Overview

This is a production-grade retail sales management system built with React, Express, and TypeScript. The application provides comprehensive tools for searching, filtering, sorting, and analyzing retail sales data. It features a modern, data-dense interface optimized for business users who need to efficiently process and understand large volumes of sales transactions.

The system handles sales data including customer information, product categories, payment methods, regional data, and transaction details. Users can perform full-text searches, apply multiple filters simultaneously, sort by various criteria, and navigate through paginated results—all while maintaining state across interactions.

User Preferences

Preferred communication style: Simple, everyday language.

System Architecture

Frontend Architecture

Framework & Tooling

  • React 18 with TypeScript for type-safe component development
  • Vite as the build tool and development server for fast HMR (Hot Module Replacement)
  • Wouter for lightweight client-side routing
  • React Query (TanStack Query) for server state management and data fetching

UI Component System

  • Radix UI primitives for accessible, unstyled components
  • shadcn/ui component library built on Radix (New York style variant)
  • Tailwind CSS for utility-first styling with custom design tokens
  • Class Variance Authority (CVA) for component variant management
  • Carbon Design System principles for data-heavy enterprise UI patterns

State Management Strategy

  • Zustand for client-side filter and UI state
  • React Query for server state, caching, and synchronization
  • URL query parameters preserved for shareable filter states
  • Separate concerns: UI state (Zustand) vs. server data (React Query)

Design System Decisions

  • IBM Plex Sans typography for professional, readable interfaces
  • Neutral color palette with blue primary color (217° hue)
  • Spacing based on Tailwind's 4px grid system (units: 2, 4, 6, 8, 12)
  • Dark mode support with CSS custom properties and class-based theme switching
  • Responsive breakpoint at 768px for mobile adaptations

Backend Architecture

Server Framework

  • Express.js for HTTP server with TypeScript
  • Single-file route registration pattern in server/routes.ts
  • Middleware chain: JSON body parsing, logging, static file serving
  • Custom request/response logging with timestamp formatting

Data Layer

  • In-memory data storage using plain JavaScript arrays
  • Sales service (server/services/sales-service.ts) encapsulates all business logic
  • Generated mock data with realistic Indian names, regions, and phone numbers
  • No external database required—data generated and held in memory

API Design

  • RESTful endpoint: GET /api/sales with query parameter filtering
  • Filter parameters: search, regions, genders, age range, categories, tags, payment methods, date range
  • Pagination parameters: page (1-indexed), pageSize (default 10, max 100)
  • Sorting parameters: sortBy (date/quantity/customerName), sortOrder (asc/desc)
  • Response includes: filtered data array, total count, pagination metadata, available filter options

Data Processing Pipeline

  1. Parse and validate query parameters
  2. Apply full-text search on customer name and phone number
  3. Apply multi-select filters (regions, genders, categories, tags, payment methods)
  4. Apply range filters (age, date)
  5. Sort results based on sortBy and sortOrder
  6. Paginate results
  7. Return data with metadata

Module Organization

Shared Schema (shared/schema.ts)

  • Zod schemas for runtime validation and type inference
  • Sale entity with 15 fields including transaction details, customer info, product data
  • SalesFilter schema for query parameters
  • SalesResponse schema for API responses
  • Single source of truth for types used across client and server

Client Structure

  • client/src/pages/ - Route components (Dashboard, NotFound)
  • client/src/components/ - Reusable UI components (SearchBar, FilterPanel, SalesTable, etc.)
  • client/src/components/ui/ - shadcn/ui base components
  • client/src/lib/ - Utilities (queryClient, store, utils)
  • client/src/hooks/ - Custom React hooks (use-mobile, use-toast)

Server Structure

  • server/index.ts - Express app initialization and middleware setup
  • server/routes.ts - API route handlers
  • server/services/ - Business logic (SalesService)
  • server/data/ - Mock data generation
  • server/static.ts - Static file serving for production builds
  • server/vite.ts - Vite middleware for development mode

Build and Deployment

Development Mode

  • Vite dev server with HMR integrated into Express
  • Source maps enabled for debugging
  • Replit-specific plugins: error overlay, cartographer, dev banner
  • TypeScript checking without emitting files

Production Build Process

  1. Client build: Vite bundles React app to dist/public/
  2. Server build: esbuild bundles Express server to dist/index.cjs
  3. Selective bundling: Common dependencies bundled, system modules externalized
  4. Single executable: node dist/index.cjs serves both API and static files

Configuration Files

  • vite.config.ts - Client build config with path aliases and plugins
  • tsconfig.json - TypeScript config with path aliases (@/, @shared/, @assets/)
  • tailwind.config.ts - Design tokens, colors, spacing, typography
  • components.json - shadcn/ui configuration (New York style, CSS variables)
  • drizzle.config.ts - Drizzle ORM config (prepared for future PostgreSQL integration)

External Dependencies

UI Component Libraries

  • Radix UI - Headless, accessible component primitives (accordion, checkbox, dialog, dropdown, popover, scroll-area, select, slider, tabs, toast, tooltip)
  • shadcn/ui - Pre-styled components built on Radix UI
  • Lucide React - Icon library for UI elements
  • Embla Carousel - Carousel component (unused in current implementation)

State Management & Data Fetching

  • TanStack React Query (v5) - Server state management, caching, background refetching
  • Zustand - Lightweight state management for client-side filters and UI state

Form Handling & Validation

  • React Hook Form - Form state management
  • Hookform Resolvers - Zod integration for form validation
  • Zod - Schema validation and TypeScript type inference
  • Drizzle Zod - Zod schema generation from Drizzle schemas

Styling & Theming

  • Tailwind CSS - Utility-first CSS framework
  • class-variance-authority - Type-safe component variant API
  • clsx - Conditional className utility
  • tailwind-merge - Merge Tailwind classes intelligently

Backend Framework & Middleware

  • Express - Node.js web server framework
  • CORS - Cross-origin resource sharing (installed but not configured in current code)

Date & Time Handling

  • date-fns - Modern date utility library for formatting and manipulation

Database (Configured but Not Used)

  • Drizzle ORM - TypeScript ORM for SQL databases
  • PostgreSQL driver (pg) - Node.js PostgreSQL client
  • connect-pg-simple - PostgreSQL session store for Express sessions

The application is designed to transition from in-memory storage to PostgreSQL by implementing the schema defined in shared/schema.ts and updating the SalesService to query the database instead of filtering in-memory arrays. Session management infrastructure is in place but not currently utilized.

Development Tools

  • TypeScript - Static typing for JavaScript
  • tsx - TypeScript execution engine for Node.js
  • esbuild - Fast JavaScript bundler for server code
  • Vite - Frontend build tool and dev server
  • Replit-specific plugins - Error overlays, cartographer mapping, dev banners