cbaoth/med-plan-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update readmes

Browse Source
This commit is contained in:
Andreas Weyer
2025-11-26 20:20:32 +00:00
parent 551ba9fd62
commit b262eab508
4 changed files with 429 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@@ -1,14 +1,44 @@
# Medication Plan Assistant
## Basic Setup
A pharmacokinetic simulation tool for Lisdexamfetamine (LDX) and d-Amphetamine medication planning with real-time visualization and dose adjustment suggestions.
## 🚀 Quick Start
```sh
# Install dependencies
npm install -D recharts tailwindcss postcss autoprefixer nodemon
# Initialize tailwind CSS (creates config files)
npx tailwindcss init -p
npm install
# Run the development server
npm start
# Build for production
npm run build
```
The app will be available at `http://localhost:3000` (or `http://0.0.0.0:3000` in dev containers).
## 🛠️ Tech Stack
- **React 19.1** with TypeScript
- **shadcn/ui** component library (Radix UI primitives)
- **Tailwind CSS** for styling
- **Recharts** for concentration-time charts
- **Create React App** as build tool
## 📋 Features
- Interactive dose schedule planning with 5 daily time slots
- Real-time pharmacokinetic simulation
- Deviation tracking from planned doses
- Automatic correction suggestions
- Dual chart view (LDX, d-Amphetamine, or both)
- Advanced PK parameter configuration
- Multi-language support (English/German)
- Local storage persistence
## 📚 Documentation
See the [docs/](./docs) folder for detailed documentation:
- [Development Notes](./docs/README.dev-notes.md) - Setup and troubleshooting
- [Modular Structure](./docs/2025-10-18_MODULAR_STRUCTURE.md) - Architecture overview
- [Dev Container Setup](./docs/README.devcontainer.md) - WSL2/Podman configuration

157
docs/2025-10-18_MODULAR_STRUCTURE.md
View File

@@ -1,32 +1,78 @@
# Medication Plan Assistant - Modular Structure
This application has been successfully modularized to simplify maintenance and further development.
This application has been successfully modularized and migrated to TypeScript with shadcn/ui components.
## 📁 New Project Structure
## 📁 Current Project Structure (2025-11-26)
```text
src/
├── App.js # Main component (greatly simplified)
├── components/ # UI components
│ ├── DoseSchedule.js # Dosage schedule input
│ ├── DeviationList.js # Deviations from the schedule
│ ├── SuggestionPanel.js # Correction suggestions
│ ├── SimulationChart.js # Chart component
│ ├── Settings.js # Settings panel
│ ├── TimeInput.js # Time input with picker
│ └── NumericInput.js # Numeric input with +/- buttons
├── hooks/ # Custom React hooks
│ ├── useAppState.js # State management & local storage
│ └── useSimulation.js # Simulation logic & calculations
├── utils/ # Utility functions
│ ├── timeUtils.js # Time utility functions
│ ├── pharmacokinetics.js # PK calculations
│ ├── calculations.js # Concentration calculations
│ └── suggestions.js # Correction suggestion algorithm
└── constants/
└── defaults.js # Constants & default values
├── 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
@@ -53,30 +99,67 @@ src/
- **Code splitting**: Possible for better performance
- **Refactoring**: Changes are limited locally
## 🔧 Technical details
## 🔧 Technical Details
### State management
### State Management
- **useAppState**: Manages global app state and LocalStorage
- **useSimulation**: Manages all simulation-related calculations
- **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
### Component Architecture
- **Dumb components**: UI components receive props and call callbacks
- **Smart Components**: Hooks manage state and business logic
- **Separation of Concerns**: UI, state, and business logic are separated
- **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
- **Pure functions**: All calculations are side-effect-free and deterministic
- **Modular exports**: Functions can be imported individually
- **Typed interfaces**: Clear input/output definitions
- **Type-safe interfaces**: Clear input/output types with TypeScript
- **Empty value handling**: Filters out invalid entries before calculations
## 🚀 Migration complete
## 🎯 Key Features
The application works identically to the original version, but now:
### Validation System
- Real-time field validation
- Visual feedback (red borders, error tooltips)
- Focus-based error display (tooltips only show on focus)
- Required field enforcement
- Split into **350+ lines** across **several small modules**
- **Easier to understand** and modify
- **Ready for further features** and improvements
- **More test-friendly** for unit and integration tests
### 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

220
docs/2025-11-26_MIGRATION_HISTORY.md Normal file
View File

@@ -0,0 +1,220 @@
# Migration History
## November 26, 2025 - TypeScript & shadcn/ui Migration
### Overview
Complete migration from JavaScript to TypeScript with shadcn/ui component library integration.
### What Was Changed
#### 1. TypeScript Migration
**Files Migrated**: All 34 source files converted from `.js` to `.ts`/`.tsx`
- ✅ `src/utils/*` → TypeScript with proper type definitions
- ✅ `src/hooks/*` → TypeScript with generic types
- ✅ `src/components/*` → React components to `.tsx`
- ✅ `src/locales/*` → i18n files to TypeScript
- ✅ `src/constants/defaults.js` → `defaults.ts` with exported types
**Type Definitions Added**:
```typescript
interface AppState {
pkParams: PkParams;
doses: Dose[];
steadyStateConfig: SteadyStateConfig;
therapeuticRange: TherapeuticRange;
doseIncrement: string;
uiSettings: UiSettings;
}
interface Dose {
time: string;
dose: string;
label: string;
}
interface Deviation extends Dose {
dayOffset?: number;
isAdditional: boolean;
}
```
**Import Changes**:
- All `.js` extensions removed from imports
- TypeScript resolves modules without extensions
- Path aliases maintained: `@/*` → `./src/*`
#### 2. shadcn/ui Component Library
**Installed Components**:
- `button`, `card`, `input`, `label`
- `popover`, `select`, `separator`
- `slider`, `switch`, `tooltip`
**Custom Form Components Created**:
**`FormTimeInput`**:
- Time picker with hour/minute grid selection
- Real-time validation with error tooltips
- Focus-based error display
- HH:MM format enforcement
- Empty value propagation for validation
**`FormNumericInput`**:
- Increment/decrement buttons
- Min/max value enforcement
- Unit display support
- Decimal place formatting
- Empty value validation
- Clear button option
**Migration from Custom Components**:
```
Old: TimeInput.js → New: ui/form-time-input.tsx
Old: NumericInput.js → New: ui/form-numeric-input.tsx
```
#### 3. Validation System Overhaul
**Before**:
- Basic client-side validation
- Inconsistent error display
- No visual feedback consistency
**After**:
- Real-time field validation
- Red borders on invalid fields
- Error tooltips (shown only on focus to avoid clutter)
- Empty value filtering in calculations
- Consistent validation across all forms
**Validation Logic**:
```typescript
const isInvalid = required && (!value || value.trim() === '');
const hasError = error || isInvalid;
const showError = hasError && isFocused; // Only show when focused
```
#### 4. Styling Migration
**From**: Custom CSS with some Tailwind
**To**: Full Tailwind CSS + shadcn/ui theme
**Color System**:
- Migrated from OKLCH to HSL format
- CSS variables for theme colors
- Dark mode ready (infrastructure in place)
**Global Styles**:
- `src/index.css` removed
- `src/styles/global.css` created with Tailwind directives
- shadcn/ui theme variables added
#### 5. Dependency Updates
**Added**:
- `@radix-ui/*` packages (8 primitives)
- `lucide-react` for icons
- `class-variance-authority` for component variants
- `tailwind-merge` for class merging
- `tailwindcss-animate` for animations
**Installed but Not Yet Used**:
- `react-hook-form` (7.66.1)
- `zod` (4.1.13)
- `@hookform/resolvers` (5.2.2)
**Note**: React Hook Form and Zod were installed for potential future use but are not currently integrated. The app uses manual validation.
### Breaking Changes
**None for End Users**: The application functionality remains identical.
**For Developers**:
- Must use `.ts`/`.tsx` file extensions
- Import paths no longer include `.js` extension
- Components expect typed props (currently using `any` for quick migration)
- New component API for form inputs
### File Changes Summary
**Deleted**:
- All `.js` files in `src/` (replaced with `.ts`/`.tsx`)
- `src/index.css` (replaced with `src/styles/global.css`)
- `src/reportWebVitals.js` (removed, not needed)
**Created**:
- `src/components/ui/` directory (10 shadcn/ui components)
- `src/styles/global.css` (Tailwind + theme)
- `src/lib/utils.ts` (cn helper function)
- All TypeScript versions of previous JS files
**Modified**:
- `tsconfig.json` - Updated for strict TypeScript
- `tailwind.config.js` - Added shadcn/ui configuration
- `package.json` - Updated dependencies
### Known Issues & Future Work
**Type Safety**:
- Many components use `: any` for props (quick migration)
- Could be improved with proper prop type interfaces
- Consider using `React.FC<Props>` pattern
**Validation**:
- Currently manual validation in components
- Could integrate React Hook Form + Zod for better DX
- Would provide centralized validation logic
**Testing**:
- Test file uses `@ts-ignore` for jest globals
- Should install `@types/jest` for proper types
**Recommendations**:
1. Add proper prop types to all components
2. Consider React Hook Form integration if forms become more complex
3. Add proper jest types for test files
4. Add more comprehensive TypeScript types (reduce `any` usage)
### Migration Commands Reference
```bash
# TypeScript migration
find src -name "*.js" -o -name "*.jsx" | while read f; do
mv "$f" "${f%.js*}.tsx"
done
# Remove .js extensions from imports
find src -name "*.ts" -o -name "*.tsx" | xargs sed -i "s/from '\(.*\)\.js'/from '\1'/g"
# Add shadcn/ui components
npx shadcn@latest add button card input label popover select separator slider switch tooltip
```
### Verification Checklist
- ✅ All files migrated to TypeScript
- ✅ No `.js` files remain in `src/`
- ✅ App compiles without errors
- ✅ All features working as before
- ✅ Validation working correctly
- ✅ LocalStorage persistence working
- ✅ Charts rendering correctly
- ✅ i18n working (EN/DE)
- ✅ Responsive layout maintained
- ✅ Production build successful
---
## October 18, 2025 - Initial Modularization
### Overview
Original monolithic `App.js` split into modular structure with separate components, hooks, and utilities.
### Changes
- Created component directory structure
- Extracted custom hooks (useAppState, useSimulation)
- Separated utility functions (timeUtils, pharmacokinetics, calculations, suggestions)
- Established constants file for defaults
### Result
Codebase organized into ~20 small, focused modules instead of one large file.

71
docs/README.dev-notes.md
View File

@@ -1,44 +1,81 @@
# Development Notes
## Initial Setup for Tailwind CSS and Recharts
## Current Tech Stack (2025-11-26)
- **React 19.1.1** with TypeScript 5.9.3
- **shadcn/ui** component library (Radix UI + Tailwind)
- **Tailwind CSS 3.4.18** for styling
- **Recharts 3.3.0** for data visualization
- **Create React App 5.0.1** as build tool
## Initial Setup (Fresh Clone)
```sh
# Hard reset in case of version conflicts / existing installs
npm uninstall tailwindcss postcss autoprefixer recharts nodemon
npm install -D tailwindcss@^3.0.0 postcss@^8.0.0 autoprefixer@^10.0.0
npm install --save recharts
rm -rf node_modules package-lock.json
# Fresh install
# Install all dependencies
npm install
# Initialize tailwind CSS (creates config files)
# Note: This may overwrite existing project files
npx tailwindcss init -p
# Run development server
npm start
# Build for production
npm run build
```
Content of ./tailwind.config.js:
## shadcn/ui Setup (Already Done)
The project was set up with shadcn/ui components. If you need to add more components:
```sh
# Add new shadcn/ui components
npx shadcn@latest add [component-name]
# Example:
npx shadcn@latest add dialog
```
## TypeScript Configuration
TypeScript is configured with:
- Strict mode enabled
- Path aliases: `@/*` → `./src/*`
- Target: ES5
- Module: ESNext
- JSX: react-jsx
## Tailwind CSS Configuration
Content paths in `tailwind.config.js`:
```javascript
/** @type {import('tailwindcss').Config} */
module.exports = {
content: [
"./src/**/*.{js,jsx,ts,tsx}",
],
theme: {
extend: {},
extend: {
colors: {
// HSL-based color system for shadcn/ui
},
plugins: [],
},
},
plugins: [require("tailwindcss-animate")],
}
```
Content of ./src/index.css:
Global styles in `./src/styles/global.css`:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
@layer base {
:root {
--background: 0 0% 98%;
--foreground: 222 47% 11%;
/* ... more CSS variables for shadcn/ui theme */
}
}
```
## WSL Networking Issues