med-plan-assistant/docs/2025-10-18_MODULAR_STRUCTURE.md

Medication Plan Assistant - Modular Structure

This application has been successfully modularized and migrated to TypeScript with shadcn/ui components.

📁 Current Project Structure (2025-11-26)

src/
├── App.tsx                    # Main component (TypeScript)
├── index.tsx                  # Entry point
├── components/                # UI components (TypeScript)
│   ├── dose-schedule.tsx      # Dosage schedule input
│   ├── deviation-list.tsx     # Deviations from the schedule
│   ├── suggestion-panel.tsx   # Correction suggestions
│   ├── simulation-chart.tsx   # Chart component (Recharts)
│   ├── settings.tsx           # Settings panel
│   ├── language-selector.tsx  # Language switcher
│   └── ui/                    # shadcn/ui components
│       ├── form-time-input.tsx      # Custom time input with picker
│       ├── form-numeric-input.tsx   # Custom numeric input with +/- buttons
│       ├── button.tsx
│       ├── card.tsx
│       ├── input.tsx
│       ├── label.tsx
│       ├── popover.tsx
│       ├── select.tsx
│       ├── separator.tsx
│       ├── slider.tsx
│       ├── switch.tsx
│       └── tooltip.tsx
├── hooks/                     # Custom React hooks (TypeScript)
│   ├── useAppState.ts         # State management & local storage
│   ├── useSimulation.ts       # Simulation logic & calculations
│   └── useLanguage.ts         # i18n language management
├── utils/                     # Utility functions (TypeScript)
│   ├── timeUtils.ts           # Time utility functions
│   ├── pharmacokinetics.ts    # PK calculations
│   ├── calculations.ts        # Concentration calculations
│   └── suggestions.ts         # Correction suggestion algorithm
├── constants/
│   └── defaults.ts            # Constants, types & default values
├── locales/                   # Internationalization
│   ├── en.ts                  # English translations
│   ├── de.ts                  # German translations
│   └── index.ts               # i18n setup
├── styles/
│   └── global.css             # Tailwind CSS + shadcn/ui theme
└── lib/
    └── utils.ts               # Utility functions (cn helper)

🔄 Recent Migrations (November 2025)

✅ JavaScript → TypeScript

• All .js files migrated to .ts/.tsx
• Type definitions in constants/defaults.ts
• Proper TypeScript configuration with strict mode

✅ Custom Components → shadcn/ui

• Replaced custom inputs with shadcn/ui components
• Built custom form components: FormTimeInput, FormNumericInput
• Integrated Radix UI primitives for accessibility
• Tailwind CSS for consistent styling

✅ Validation Enhancement

• Real-time validation with visual feedback
• Error tooltips (shown on focus only)
• Red borders for invalid fields
• Empty value filtering in calculations

✅ Internationalization

• Multi-language support (EN/DE)
• Browser language detection
• LocalStorage persistence

🎯 Advantages of the new structure

✅ Better maintainability

• Small, focused modules: Each file has a clear responsibility
• Easier debugging: Problems can be localized more quickly
• Clearer code organization: Related functions are grouped together

✅ Reusability

• UI components: TimeInput, NumericInput can be used anywhere
• Utility functions: PK calculations are isolated and testable
• Custom hooks: State logic is reusable

✅ Development friendliness

• Parallel development: Teams can work on different modules
• Simpler testing: Each module can be tested in isolation
• Better IDE support: Smaller files = better performance

✅ Scalability

• New features: Easy to add as new modules
• Code splitting: Possible for better performance
• Refactoring: Changes are limited locally

🔧 Technical Details

State Management

• useAppState: Manages global app state with LocalStorage persistence
• useSimulation: Handles all simulation-related calculations and deviations
• useLanguage: Manages i18n state and language switching

Component Architecture

• Presentational components: UI components receive typed props and call callbacks
• Custom hooks: Manage state and business logic
• shadcn/ui base: Radix UI primitives with Tailwind styling
• Form components: Reusable FormTimeInput and FormNumericInput with validation

TypeScript Integration

• Type-safe state: All state objects have proper TypeScript interfaces
• Type inference: Leverages TS for better IDE support and compile-time checks
• Strict mode: Configured for maximum type safety
• Exported types: Dose, Deviation, AppState, PkParams, etc.

Utils & Calculations

• Pure functions: All calculations are side-effect-free and deterministic
• Modular exports: Functions can be imported individually
• Type-safe interfaces: Clear input/output types with TypeScript
• Empty value handling: Filters out invalid entries before calculations

🎯 Key Features

Validation System

• Real-time field validation
• Visual feedback (red borders, error tooltips)
• Focus-based error display (tooltips only show on focus)
• Required field enforcement

UI/UX Enhancements

• Time picker with hour/minute grid selection
• Numeric inputs with increment/decrement buttons
• Responsive layout with Tailwind CSS
• Dark mode ready (HSL color variables)

Data Persistence

• LocalStorage for all settings
• Automatic save on state changes
• Version-based storage key
• Graceful fallback to defaults

🚀 Evolution Summary

The application has evolved significantly:

• 2025-10: Initial modularization (JS)
• 2025-11: TypeScript migration (34 TS/TSX files)
• 2025-11: shadcn/ui component library integration
• 2025-11: Enhanced validation and UX improvements

Current state:

• Full TypeScript with type safety throughout
• Modern component library (shadcn/ui + Radix UI)
• Professional UI/UX with validation and error handling
• Maintainable architecture with clear separation of concerns
• Production-ready with optimized builds