f51bdeb284
- Update TEMPLATE_APPROACH.md from Kubernetes deployment to development configuration - Update PROJECT_STRUCTURE.md to reflect current development structure - Remove references to non-existent deployment artifacts - Focus on environment-based configuration and template processing - Document actual current features rather than future deployment scenarios
345 lines
15 KiB
Markdown
345 lines
15 KiB
Markdown
# 📁 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.
|