rxminder/docs/architecture/PROJECT_STRUCTURE.md

📁 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                   # Application entry point
├── 🔒 .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
│   ├── 🧹 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
│       ├── 🧪 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
    ├── 📝 .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

# Configuration approach
.env.example → .env                 # User customization
config/unified.config.ts            # Centralized configuration

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

# 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

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

2. Template Processing

   bun run dev            # Start development server
   

3. Code Quality

   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.