# 📁 Project Structure

## Current Development Structure

```
rxminder/
├── 📄 README.md                    # Main project documentation
├── 📦 package.json                 # Dependencies and scripts
├── ⚙️ vite.config.ts               # Build configuration
├── 📝 tsconfig.json                # TypeScript configuration
├── 🎨 index.html                   # Generated entry point
├── 🎨 index.html.template          # Template for HTML generation
├── 🔒 .env.example                 # Environment template
├── 📊 metadata.json                # Project metadata
├── 🖼️ banner.jpeg                  # Project banner image
├── 🚀 index.tsx                    # React application entry point
├── 🎯 App.tsx                      # Main React component
├── 📋 types.ts                     # Global type definitions
│
├── 📁 components/                  # React components (organized by feature)
│   ├── 📝 README.md                # Component architecture docs
│   ├── 📁 medication/              # Medication-related components
│   │   ├── 💊 AddMedicationModal.tsx
│   │   ├── ✏️ EditMedicationModal.tsx
│   │   ├── 📋 ManageMedicationsModal.tsx
│   │   ├── 🏷️ DoseCard.tsx
│   │   └── 📦 index.ts             # Feature exports
│   ├── 📁 auth/                    # Authentication components
│   │   ├── 🔐 AuthPage.tsx         # Login/register interface
│   │   ├── 👤 AvatarDropdown.tsx   # User menu
│   │   ├── 🔑 ChangePasswordModal.tsx
│   │   └── 📦 index.ts             # Feature exports
│   ├── 📁 admin/                   # Admin interface components
│   │   ├── 👑 AdminInterface.tsx   # User management
│   │   └── 📦 index.ts             # Feature exports
│   ├── 📁 modals/                  # Modal components
│   │   ├── ⚙️ AccountModal.tsx     # User settings
│   │   ├── ➕ AddReminderModal.tsx # Add reminders
│   │   ├── ✏️ EditReminderModal.tsx
│   │   ├── 📚 HistoryModal.tsx     # Medication history
│   │   ├── 📋 ManageRemindersModal.tsx
│   │   ├── 🎯 OnboardingModal.tsx  # New user setup
│   │   ├── 📊 StatsModal.tsx       # Analytics dashboard
│   │   └── 📦 index.ts             # Feature exports
│   ├── 📁 ui/                      # Reusable UI components
│   │   ├── 📊 BarChart.tsx         # Data visualization
│   │   ├── 🔔 ReminderCard.tsx     # Reminder display
│   │   ├── 🎨 ThemeSwitcher.tsx    # Dark/light theme
│   │   └── 📦 index.ts             # Feature exports
│   └── 📁 icons/                   # Icon components
│       └── 🎨 Icons.tsx            # All icon definitions
│
├── 📁 services/                    # Business logic & APIs
│   ├── 🗄️ database/               # Unified database service
│   │   ├── 📋 DatabaseService.ts   # Main service with strategy pattern
│   │   ├── 🧪 MockDatabaseStrategy.ts # In-memory implementation
│   │   ├── 🏭 ProductionDatabaseStrategy.ts # CouchDB implementation
│   │   ├── 📝 types.ts             # Database interfaces
│   │   ├── 📦 index.ts             # Public exports
│   │   └── 📝 README.md            # Database service documentation
│   ├── 📧 logging/                 # Centralized logging system
│   │   ├── 📊 Logger.ts            # Main logger implementation
│   │   └── 📦 index.ts             # Public exports
│   ├── 📧 email.ts                 # Email utilities
│   ├── 📧 mailgun.service.ts       # Email delivery
│   ├── 📧 mailgun.config.ts        # Email configuration
│   ├── 🌱 database.seeder.ts       # Data seeding
│   ├── 🔐 oauth.ts                 # OAuth integration
│   └── 📁 auth/                    # Authentication services
│       ├── 🔐 auth.service.ts      # Core auth logic
│       ├── 📝 auth.types.ts        # Auth type definitions
│       ├── 📋 auth.constants.ts    # Auth constants
│       ├── ⚠️ auth.error.ts        # Error handling
│       ├── 🛡️ auth.middleware.ts   # Middleware
│       ├── ✉️ emailVerification.service.ts
│       ├── 📁 templates/           # Email templates
│       │   └── ✉️ verification.email.ts
│       └── 📁 __tests__/           # Unit tests
│           ├── 🧪 auth.integration.test.ts
│           └── 🧪 emailVerification.test.ts
│
├── 📁 config/                      # Configuration management
│   └── ⚙️ unified.config.ts        # Centralized configuration with validation
│
├── 📁 contexts/                    # React context providers
│   └── 👤 UserContext.tsx          # User state management
│
├── 📁 hooks/                       # Custom React hooks
│   ├── 💾 useLocalStorage.ts       # Persistent storage
│   ├── ⚙️ useSettings.ts           # User preferences
│   ├── 🎨 useTheme.ts              # Theme management
│   └── 👤 useUserData.ts           # User data management
│
├── 📁 utils/                       # Utility functions
│   └── ⏰ schedule.ts               # Reminder scheduling
│
├── 📁 types/                       # TypeScript type definitions
│   └── 📝 index.ts                 # Global type exports
│
├── 📁 scripts/                     # Development and build scripts
│   ├── 🔧 setup.sh                 # Development setup
│   ├── 🎨 process-html.sh          # HTML template processing
│   ├── 🧹 setup-pre-commit.sh      # Git hooks setup
│   └── 🌱 seed-production.js       # Database seeding
│
├── 📁 tests/                       # Testing infrastructure
│   ├── 📝 README.md                # Testing documentation
│   ├── ⚙️ setup.ts                 # Jest configuration
│   ├── 📁 integration/             # Integration tests
│   │   └── 🧪 production.test.js   # Production validation
│   ├── 📁 manual/                  # Manual testing scripts
│   │   ├── 🔧 admin-login-debug.js # Admin debugging
│   │   ├── 🔧 auth-db-debug.js     # Auth debugging
│   │   └── 🔧 debug-email-validation.js # Email debugging
│   └── 📁 e2e/                     # End-to-end tests with Playwright
│       ├── 📝 README.md            # E2E testing documentation
│       ├── 🧪 fixtures.ts          # Custom test fixtures
│       ├── 🧪 helpers.ts           # Test utilities and data
│       ├── 🧪 auth.spec.ts         # Authentication flow tests
│       ├── 🧪 medication.spec.ts   # Medication management tests
│       ├── 🧪 admin.spec.ts        # Admin interface tests
│       ├── 🧪 ui-navigation.spec.ts # UI and navigation tests
│       └── 🧪 reminders.spec.ts    # Reminder system tests
│
├── 📁 docs/                        # Project documentation
│   ├── 📋 README.md                # Documentation index
│   ├── 📁 architecture/            # Design & Architecture
│   │   ├── 🏗️ PROJECT_STRUCTURE.md # This file
│   │   └── 🎯 TEMPLATE_APPROACH.md # Configuration approach
│   ├── 📁 setup/                   # Setup & Configuration
│   │   ├── ⚙️ COMPLETE_TEMPLATE_CONFIGURATION.md
│   │   ├── ✅ SETUP_COMPLETE.md
│   │   ├── 🌍 ENVIRONMENT_VARIABLES.md
│   │   └── 🏷️ APP_NAME_CONFIGURATION.md
│   ├── 📁 development/             # Development Guides
│   │   ├── 📖 API.md               # API documentation
│   │   ├── 🗄️ DATABASE.md          # Database service docs
│   │   ├── ✨ CODE_QUALITY.md      # Quality standards
│   │   ├── 🔒 APPLICATION_SECURITY.md # Security practices
│   │   ├── 🔄 SECURITY_CHANGES.md  # Security updates
│   │   └── 🪝 PRE_COMMIT_HOOKS.md  # Git hook configuration
│   └── 📁 implementation/          # Current Status
│       └── 📊 IMPLEMENTATION_SUMMARY.md
│
├── 📁 coverage/                    # Test coverage reports
├── 📁 dist/                        # Production build output
├── 📁 node_modules/                # Dependencies
│
└── 📁 Configuration Files          # Development configuration
    ├── 🔧 .gitignore               # Git ignore patterns
    ├── 🎨 .prettierrc              # Code formatting rules
    ├── ⚡ eslint.config.cjs        # Linting configuration
    ├── 🧪 jest.config.json         # Test configuration
    ├── 🎭 playwright.config.ts     # E2E test configuration
    ├── 📝 .markdownlint.json       # Markdown linting
    ├── 🔒 .secretlintrc.json       # Secret detection
    ├── ✏️ .editorconfig            # Editor consistency
    ├── 🪝 .husky/                  # Git hooks
    └── 📄 Various other config files
```

## Key Organizational Principles

### ✅ **Feature-Based Component Organization**

Components are organized by functionality rather than by type:

```
components/
├── medication/     # All medication-related UI
├── auth/          # Authentication components
├── admin/         # Admin interface
├── modals/        # Modal dialogs
└── ui/            # Reusable UI components
```

**Benefits:**

- Related functionality stays together
- Easy to find and modify features
- Clear boundaries between different parts of the app
- Scalable as features grow

### ✅ **Service Layer Architecture**

Services provide business logic separate from UI components:

```
services/
├── database/      # Data persistence with strategy pattern
├── logging/       # Centralized logging system
└── auth/          # Authentication and user management
```

**Benefits:**

- Clear separation of concerns
- Reusable business logic
- Easy to test and mock
- Strategy pattern allows flexible implementations

### ✅ **Configuration Management**

Centralized configuration with environment-based templates:

```
config/
└── unified.config.ts    # Single source of truth

# Template approach
index.html.template → index.html    # Processed with environment variables
.env.example → .env                 # User customization
```

**Benefits:**

- No hardcoded configuration
- Environment-specific settings
- Type-safe configuration access
- Clear separation of config and code

### ✅ **Testing Strategy**

Comprehensive testing at multiple levels:

```
tests/
├── integration/   # Service integration tests
├── manual/        # Debug scripts and manual testing
└── e2e/          # Full application testing

# Unit tests alongside code
services/auth/__tests__/   # Co-located with services
components/__tests__/      # Component-specific tests
```

**Benefits:**

- Tests close to the code they test
- Multiple testing strategies
- Easy to run specific test suites
- Clear separation of test types

### ✅ **Documentation Structure**

Documentation organized by purpose and audience:

```
docs/
├── architecture/    # System design and patterns
├── setup/          # Configuration and installation
├── development/    # Developer guides and APIs
└── implementation/ # Current status and features
```

**Benefits:**

- Easy navigation by role (developer, ops, etc.)
- Clear separation of different doc types
- Comprehensive coverage of all aspects
- Living documentation that stays current

## 🎯 Development Workflow

### Local Development Setup

1. **Environment Configuration**

   ```bash
   cp .env.example .env    # Copy template
   nano .env               # Customize settings
   ```

2. **Template Processing**

   ```bash
   bun run predev         # Process HTML templates
   bun run dev            # Start development server
   ```

3. **Code Quality**
   ```bash
   bun run lint           # Check code quality
   bun run format         # Format code
   bun run type-check     # TypeScript validation
   ```

### Database Strategy Selection

The application automatically selects the appropriate database strategy:

- **Development**: Mock database (instant responses, no setup)
- **Testing**: Mock database (isolated test data)
- **Production**: CouchDB (persistent storage)

### Component Development

1. **Create feature-based components** in appropriate folders
2. **Export from index.ts** for clean imports
3. **Co-locate tests** with components when appropriate
4. **Use TypeScript** for type safety

### Service Development

1. **Implement business logic** in service layer
2. **Use dependency injection** for testability
3. **Follow strategy pattern** for flexibility
4. **Add comprehensive tests** for reliability

## 📊 Metrics and Standards

### Code Organization

- **Feature cohesion**: Related code stays together
- **Clear boundaries**: Services, components, utilities clearly separated
- **Consistent patterns**: Similar organization across features
- **Scalable structure**: Easy to add new features without reorganization

### Development Experience

- **Fast setup**: One command to get started
- **Quick iteration**: Hot reloading and instant feedback
- **Easy testing**: Multiple test strategies available
- **Clear debugging**: Structured logging and debug tools

### Maintainability

- **Self-documenting**: Clear folder structure and naming
- **Consistent patterns**: Similar approaches across the codebase
- **Easy refactoring**: Loose coupling between components
- **Future-proof**: Architecture supports growth and changes

## 🚀 Benefits

🎯 **Discoverability** - Logical structure makes files easy to find  
🔧 **Maintainability** - Clear patterns make code easy to modify  
🧪 **Testability** - Well-organized test structure and strategy  
📈 **Scalability** - Architecture supports feature growth  
👥 **Team Collaboration** - Consistent patterns across the project  
🛡️ **Reliability** - Strategy pattern provides flexibility and fallbacks  
⚡ **Performance** - Optimized development and build processes  
📚 **Documentation** - Comprehensive guides for all aspects

This structure provides a solid foundation for continued development and future enhancements while maintaining code quality and developer productivity.