diff --git a/src/App.tsx b/src/App.tsx
index 450622c..572ed88 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -1,3 +1,14 @@
+/**
+ * Medication Plan Assistant - Main Application
+ *
+ * A pharmacokinetic simulation tool for lisdexamfetamine (Elvanse/Vyvanse)
+ * medication planning. Helps users visualize drug concentration profiles,
+ * manage deviations, and get dose correction suggestions.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 
 // Components
diff --git a/src/components/deviation-list.tsx b/src/components/deviation-list.tsx
index 481054e..7308f85 100644
--- a/src/components/deviation-list.tsx
+++ b/src/components/deviation-list.tsx
@@ -1,3 +1,14 @@
+/**
+ * Deviation List Component
+ *
+ * Tracks and manages deviations from the planned medication schedule.
+ * Supports adding, editing, and deleting deviations with automatic or
+ * manual timestamps. Each deviation can be marked as planned or actual.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { FormTimeInput } from './ui/form-time-input';
 import { FormNumericInput } from './ui/form-numeric-input';
diff --git a/src/components/dose-schedule.tsx b/src/components/dose-schedule.tsx
index 971b2b9..d0869b2 100644
--- a/src/components/dose-schedule.tsx
+++ b/src/components/dose-schedule.tsx
@@ -1,3 +1,13 @@
+/**
+ * Dose Schedule Component
+ *
+ * Manages up to 5 daily dose time slots with time and dose amount inputs.
+ * Provides validation and allows empty entries for flexible scheduling.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { FormTimeInput } from './ui/form-time-input';
 import { FormNumericInput } from './ui/form-numeric-input';
diff --git a/src/components/language-selector.tsx b/src/components/language-selector.tsx
index d601a1b..93f0c03 100644
--- a/src/components/language-selector.tsx
+++ b/src/components/language-selector.tsx
@@ -1,3 +1,13 @@
+/**
+ * Language Selector Component
+ *
+ * Provides UI for switching between supported languages (English/German).
+ * Uses shadcn/ui Select component.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from './ui/select';
 import { Label } from './ui/label';
diff --git a/src/components/settings.tsx b/src/components/settings.tsx
index a7e2296..836c0c9 100644
--- a/src/components/settings.tsx
+++ b/src/components/settings.tsx
@@ -1,3 +1,14 @@
+/**
+ * Settings Component
+ *
+ * Provides configuration for pharmacokinetic parameters (half-lives,
+ * absorption rates) and UI settings (chart view, therapeutic ranges,
+ * x-axis format). Includes data management (import/export/reset).
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { FormNumericInput } from './ui/form-numeric-input';
 import { Card, CardContent, CardHeader, CardTitle } from './ui/card';
diff --git a/src/components/simulation-chart.tsx b/src/components/simulation-chart.tsx
index 40b5035..b80a4b8 100644
--- a/src/components/simulation-chart.tsx
+++ b/src/components/simulation-chart.tsx
@@ -1,3 +1,14 @@
+/**
+ * Simulation Chart Component
+ *
+ * Visualizes pharmacokinetic concentration profiles over time using Recharts.
+ * Displays ideal plan, deviated profile, and corrected profile with
+ * therapeutic range indicators. Supports multiple chart views and x-axis formats.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ReferenceLine, ResponsiveContainer } from 'recharts';
 
diff --git a/src/components/suggestion-panel.tsx b/src/components/suggestion-panel.tsx
index 0042e9f..868382a 100644
--- a/src/components/suggestion-panel.tsx
+++ b/src/components/suggestion-panel.tsx
@@ -1,3 +1,13 @@
+/**
+ * Suggestion Panel Component
+ *
+ * Displays dose correction suggestions based on deviations from the plan.
+ * Shows recommended time and dose adjustments with apply button.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { Card, CardContent, CardHeader, CardTitle } from './ui/card';
 import { Button } from './ui/button';
diff --git a/src/components/ui/form-numeric-input.tsx b/src/components/ui/form-numeric-input.tsx
index 5c13b6d..e045479 100644
--- a/src/components/ui/form-numeric-input.tsx
+++ b/src/components/ui/form-numeric-input.tsx
@@ -1,3 +1,13 @@
+/**
+ * Custom Form Component: Numeric Input with Controls
+ *
+ * A numeric input field with increment/decrement buttons, validation,
+ * and error display. Built on top of shadcn/ui components.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import * as React from "react"
 import { Minus, Plus, X } from "lucide-react"
 import { Button } from "./button"
diff --git a/src/components/ui/form-time-input.tsx b/src/components/ui/form-time-input.tsx
index b40308c..514156c 100644
--- a/src/components/ui/form-time-input.tsx
+++ b/src/components/ui/form-time-input.tsx
@@ -1,3 +1,13 @@
+/**
+ * Custom Form Component: Time Input with Picker
+ *
+ * A time input field with interactive hour/minute picker, validation,
+ * and error display. Built on top of shadcn/ui components.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import * as React from "react"
 import { Clock } from "lucide-react"
 import { Button } from "./button"
diff --git a/src/constants/defaults.ts b/src/constants/defaults.ts
index df3d2d9..2a156be 100644
--- a/src/constants/defaults.ts
+++ b/src/constants/defaults.ts
@@ -1,4 +1,13 @@
-// Application constants
+/**
+ * Application Constants and Type Definitions
+ *
+ * Defines TypeScript interfaces for application state, pharmacokinetic parameters,
+ * and default values. Central configuration for localStorage keys and conversion factors.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 export const LOCAL_STORAGE_KEY = 'medPlanAssistantState_v5';
 export const LDX_TO_DAMPH_CONVERSION_FACTOR = 0.2948;
 
diff --git a/src/hooks/useAppState.ts b/src/hooks/useAppState.ts
index 9001af7..f43bab7 100644
--- a/src/hooks/useAppState.ts
+++ b/src/hooks/useAppState.ts
@@ -1,3 +1,14 @@
+/**
+ * Application State Hook
+ *
+ * Manages global application state with localStorage persistence.
+ * Provides type-safe state updates for nested objects and automatic
+ * state saving on changes.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { LOCAL_STORAGE_KEY, getDefaultState, type AppState } from '../constants/defaults';
 
diff --git a/src/hooks/useLanguage.ts b/src/hooks/useLanguage.ts
index 4f432c5..e3cd76a 100644
--- a/src/hooks/useLanguage.ts
+++ b/src/hooks/useLanguage.ts
@@ -1,3 +1,13 @@
+/**
+ * Language Hook
+ *
+ * Manages application language state and provides translation access.
+ * Persists language preference to localStorage.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { translations, getInitialLanguage } from '../locales/index';
 
diff --git a/src/hooks/useSimulation.ts b/src/hooks/useSimulation.ts
index 6f99355..ffd5ca8 100644
--- a/src/hooks/useSimulation.ts
+++ b/src/hooks/useSimulation.ts
@@ -1,3 +1,14 @@
+/**
+ * Simulation Hook
+ *
+ * Manages pharmacokinetic simulation calculations and deviation handling.
+ * Computes ideal, deviated, and corrected concentration profiles.
+ * Generates dose correction suggestions based on deviations.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import React from 'react';
 import { calculateCombinedProfile } from '../utils/calculations';
 import { generateSuggestion } from '../utils/suggestions';
diff --git a/src/locales/index.ts b/src/locales/index.ts
index 934d1e9..12b9a0c 100644
--- a/src/locales/index.ts
+++ b/src/locales/index.ts
@@ -1,3 +1,13 @@
+/**
+ * Internationalization (i18n) Configuration
+ *
+ * Manages application translations and language detection.
+ * Supports English and German with browser language preference detection.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import en from './en';
 import de from './de';
 
diff --git a/src/utils/calculations.ts b/src/utils/calculations.ts
index e290fb4..b9ab5dd 100644
--- a/src/utils/calculations.ts
+++ b/src/utils/calculations.ts
@@ -1,3 +1,14 @@
+/**
+ * Pharmacokinetic Calculation Utilities
+ *
+ * Combines multiple dose profiles over time to create complete concentration
+ * curves. Handles steady-state calculations, dose accumulation, and empty
+ * value filtering for robust simulation.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import { timeToMinutes } from './timeUtils';
 import { calculateSingleDoseConcentration } from './pharmacokinetics';
 import type { Dose, Deviation, SteadyStateConfig, PkParams, ConcentrationPoint } from '../constants/defaults';
diff --git a/src/utils/pharmacokinetics.ts b/src/utils/pharmacokinetics.ts
index 61cbf4f..7ee87e0 100644
--- a/src/utils/pharmacokinetics.ts
+++ b/src/utils/pharmacokinetics.ts
@@ -1,3 +1,14 @@
+/**
+ * Pharmacokinetic Model
+ *
+ * Implements single-dose concentration calculations for lisdexamfetamine (LDX)
+ * and its active metabolite dextroamphetamine (d-amph). Uses first-order
+ * absorption and elimination kinetics.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import { LDX_TO_DAMPH_CONVERSION_FACTOR, type PkParams } from '../constants/defaults';
 
 interface ConcentrationResult {
diff --git a/src/utils/suggestions.ts b/src/utils/suggestions.ts
index d6932a4..2942b9f 100644
--- a/src/utils/suggestions.ts
+++ b/src/utils/suggestions.ts
@@ -1,3 +1,14 @@
+/**
+ * Dose Correction Suggestion Engine
+ *
+ * Generates dose correction suggestions when deviations occur from the planned
+ * medication schedule. Calculates required dose adjustments and optimal timing
+ * to maintain therapeutic concentrations.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 import { timeToMinutes } from './timeUtils';
 import { calculateCombinedProfile } from './calculations';
 import type { Dose, Deviation, SteadyStateConfig, PkParams } from '../constants/defaults';
diff --git a/src/utils/timeUtils.ts b/src/utils/timeUtils.ts
index 87a8ab8..6ffedfe 100644
--- a/src/utils/timeUtils.ts
+++ b/src/utils/timeUtils.ts
@@ -1,4 +1,13 @@
-// Time utility functions
+/**
+ * Time Utility Functions
+ *
+ * Provides time format conversion utilities for working with HH:MM time strings
+ * and minute-based calculations throughout the application.
+ *
+ * @author Andreas Weyer
+ * @license MIT
+ */
+
 export const timeToMinutes = (timeStr: string): number => {
   if (!timeStr || !timeStr.includes(':')) return 0;
   const [hours, minutes] = timeStr.split(':').map(Number);