docs: refocus architecture docs on current development state
- 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
This commit is contained in:
William Valentin
@@ -1,50 +1,21 @@
|
|||||||
# 📁 Project Structure
|
# 📁 Project Structure
|
||||||
|
|
||||||
## Final Organized Structure
|
## Current Development Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
rxminder/
|
rxminder/
|
||||||
├── 📄 README.md # Main documentation
|
├── 📄 README.md # Main project documentation
|
||||||
├── package.json # Dependencies and scripts
|
├── 📦 package.json # Dependencies and scripts
|
||||||
├── ⚙️ vite.config.ts # Build configuration
|
├── ⚙️ vite.config.ts # Build configuration
|
||||||
├── 📝 tsconfig.json # TypeScript configuration
|
├── 📝 tsconfig.json # TypeScript configuration
|
||||||
├── 🎨 index.html # Entry point
|
├── 🎨 index.html # Generated entry point
|
||||||
|
├── 🎨 index.html.template # Template for HTML generation
|
||||||
├── 🔒 .env.example # Environment template
|
├── 🔒 .env.example # Environment template
|
||||||
├── 📊 metadata.json # Project metadata
|
├── 📊 metadata.json # Project metadata
|
||||||
├── 🖼️ banner.jpeg # Project banner image
|
├── 🖼️ banner.jpeg # Project banner image
|
||||||
│
|
├── 🚀 index.tsx # React application entry point
|
||||||
├── <EFBFBD> docker/ # Container configuration
|
├── 🎯 App.tsx # Main React component
|
||||||
│ ├── 🐳 Dockerfile # Multi-stage Docker build
|
├── 📋 types.ts # Global type definitions
|
||||||
│ ├── <20> docker-compose.yaml # Service orchestration
|
|
||||||
│ ├── 🌐 nginx.conf # Production web server config
|
|
||||||
│ └── 🚫 .dockerignore # Docker ignore patterns
|
|
||||||
│
|
|
||||||
├── 📁 scripts/ # All deployment and utility scripts
|
|
||||||
│ ├── 🚀 deploy.sh # Production deployment
|
|
||||||
│ ├── ⚡ deploy-k8s.sh # Kubernetes deployment
|
|
||||||
│ ├── 🔧 setup.sh # Development setup
|
|
||||||
│ ├── 🌱 seed-production.js # Database seeding
|
|
||||||
│ ├── ✅ validate-env.sh # Environment validation
|
|
||||||
│ └── 🧪 validate-deployment.sh # Deployment testing
|
|
||||||
│
|
|
||||||
├── 📁 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
|
|
||||||
│
|
│
|
||||||
├── 📁 components/ # React components (organized by feature)
|
├── 📁 components/ # React components (organized by feature)
|
||||||
│ ├── 📝 README.md # Component architecture docs
|
│ ├── 📝 README.md # Component architecture docs
|
||||||
@@ -81,102 +52,293 @@ rxminder/
|
|||||||
│
|
│
|
||||||
├── 📁 services/ # Business logic & APIs
|
├── 📁 services/ # Business logic & APIs
|
||||||
│ ├── 🗄️ database/ # Unified database service
|
│ ├── 🗄️ database/ # Unified database service
|
||||||
│ │ ├── DatabaseService.ts # Main service with strategy pattern
|
│ │ ├── 📋 DatabaseService.ts # Main service with strategy pattern
|
||||||
│ │ ├── MockDatabaseStrategy.ts # In-memory implementation
|
│ │ ├── 🧪 MockDatabaseStrategy.ts # In-memory implementation
|
||||||
│ │ ├── ProductionDatabaseStrategy.ts # CouchDB implementation
|
│ │ ├── 🏭 ProductionDatabaseStrategy.ts # CouchDB implementation
|
||||||
│ │ └── types.ts # Database interfaces
|
│ │ ├── 📝 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
|
│ ├── 📧 email.ts # Email utilities
|
||||||
│ ├── 📧 mailgun.service.ts # Email delivery
|
│ ├── 📧 mailgun.service.ts # Email delivery
|
||||||
│ ├── 📧 mailgun.config.ts # Email configuration
|
│ ├── 📧 mailgun.config.ts # Email configuration
|
||||||
│ ├── 🌱 database.seeder.ts # Data seeding
|
│ ├── 🌱 database.seeder.ts # Data seeding
|
||||||
│ ├── 🔐 oauth.ts # OAuth integration
|
│ ├── 🔐 oauth.ts # OAuth integration
|
||||||
│ └── 📁 auth/ # Authentication services
|
│ └── 📁 auth/ # Authentication services
|
||||||
│ ├── 🔐 auth.service.ts # Core auth logic
|
│ ├── 🔐 auth.service.ts # Core auth logic
|
||||||
│ ├── 🔐 auth.types.ts # Auth type definitions
|
│ ├── 📝 auth.types.ts # Auth type definitions
|
||||||
│ ├── 🔐 auth.constants.ts # Auth constants
|
│ ├── 📋 auth.constants.ts # Auth constants
|
||||||
│ ├── 🔐 auth.error.ts # Error handling
|
│ ├── ⚠️ auth.error.ts # Error handling
|
||||||
│ ├── 🔐 auth.middleware.ts # Middleware
|
│ ├── 🛡️ auth.middleware.ts # Middleware
|
||||||
│ ├── ✉️ emailVerification.service.ts
|
│ ├── ✉️ emailVerification.service.ts
|
||||||
│ ├── 📁 templates/ # Email templates
|
│ ├── 📁 templates/ # Email templates
|
||||||
│ │ └── ✉️ verification.email.ts
|
│ │ └── ✉️ verification.email.ts
|
||||||
│ └── 📁 __tests__/ # Unit tests
|
│ └── 📁 __tests__/ # Unit tests
|
||||||
│ ├── 🧪 auth.integration.test.ts
|
│ ├── 🧪 auth.integration.test.ts
|
||||||
│ └── 🧪 emailVerification.test.ts
|
│ └── 🧪 emailVerification.test.ts
|
||||||
│
|
│
|
||||||
|
├── 📁 config/ # Configuration management
|
||||||
|
│ └── ⚙️ unified.config.ts # Centralized configuration with validation
|
||||||
|
│
|
||||||
├── 📁 contexts/ # React context providers
|
├── 📁 contexts/ # React context providers
|
||||||
│ └── 👤 UserContext.tsx # User state management
|
│ └── 👤 UserContext.tsx # User state management
|
||||||
│
|
│
|
||||||
├── 📁 hooks/ # Custom React hooks
|
├── 📁 hooks/ # Custom React hooks
|
||||||
│ ├── 💾 useLocalStorage.ts # Persistent storage
|
│ ├── 💾 useLocalStorage.ts # Persistent storage
|
||||||
│ ├── ⚙️ useSettings.ts # User preferences
|
│ ├── ⚙️ useSettings.ts # User preferences
|
||||||
│ ├── 🎨 useTheme.ts # Theme management
|
│ ├── 🎨 useTheme.ts # Theme management
|
||||||
│ └── 👤 useUserData.ts # User data management
|
│ └── 👤 useUserData.ts # User data management
|
||||||
│
|
│
|
||||||
├── 📁 utils/ # Utility functions
|
├── 📁 utils/ # Utility functions
|
||||||
│ └── ⏰ schedule.ts # Reminder scheduling
|
│ └── ⏰ 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
|
├── 📁 docs/ # Project documentation
|
||||||
│ ├── 🔐 SECURITY.md # Security guidelines
|
│ ├── 📋 README.md # Documentation index
|
||||||
│ ├── 🚀 DEPLOYMENT.md # Deployment instructions
|
│ ├── 📁 architecture/ # Design & Architecture
|
||||||
│ └── 📖 API.md # API documentation
|
│ │ ├── 🏗️ 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
|
||||||
│
|
│
|
||||||
├── 📁 k8s/ # Kubernetes manifests
|
├── 📁 coverage/ # Test coverage reports
|
||||||
│ ├── 📝 README.md # K8s deployment guide
|
├── 📁 dist/ # Production build output
|
||||||
│ ├── 🗺️ configmap.yaml # Configuration
|
├── 📁 node_modules/ # Dependencies
|
||||||
│ ├── 🔒 *-secret.yaml # Secrets
|
|
||||||
│ ├── 🚀 *-deployment.yaml # Deployments
|
|
||||||
│ ├── 🌐 *-service.yaml # Services
|
|
||||||
│ ├── 📊 hpa.yaml # Auto-scaling
|
|
||||||
│ ├── 🌐 ingress.yaml # Load balancing
|
|
||||||
│ └── 🔒 network-policy.yaml # Network security
|
|
||||||
│
|
│
|
||||||
└── 📁 .github/ # GitHub configuration
|
└── 📁 Configuration Files # Development configuration
|
||||||
├── 📝 pull_request_template.md
|
├── 🔧 .gitignore # Git ignore patterns
|
||||||
└── 📁 ISSUE_TEMPLATE/
|
├── 🎨 .prettierrc # Code formatting rules
|
||||||
├── 🐛 bug_report.md
|
├── ⚡ eslint.config.cjs # Linting configuration
|
||||||
└── ✨ feature_request.md
|
├── 🧪 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
|
## Key Organizational Principles
|
||||||
|
|
||||||
### ✅ **Feature-Based Organization**
|
### ✅ **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:**
|
||||||
|
|
||||||
- Components grouped by functionality (medication, auth, admin, etc.)
|
|
||||||
- Clear separation of concerns
|
- Clear separation of concerns
|
||||||
- Easy to locate related files
|
- Reusable business logic
|
||||||
|
- Easy to test and mock
|
||||||
### ✅ **Script Centralization**
|
- Strategy pattern allows flexible implementations
|
||||||
|
|
||||||
- All deployment and utility scripts in `/scripts/`
|
|
||||||
- Consistent naming conventions
|
|
||||||
- Easy access via npm/bun scripts
|
|
||||||
|
|
||||||
### ✅ **Testing Structure**
|
|
||||||
|
|
||||||
- Unit tests alongside source code (`services/auth/__tests__/`)
|
|
||||||
- Integration tests in `/tests/integration/`
|
|
||||||
- E2E tests with Playwright in `/tests/e2e/`
|
|
||||||
- Manual debugging tools in `/tests/manual/`
|
|
||||||
- Comprehensive test documentation
|
|
||||||
- TypeScript support with temporary type declarations
|
|
||||||
|
|
||||||
### ✅ **Documentation Organization**
|
|
||||||
|
|
||||||
- Feature-specific READMEs in relevant folders
|
|
||||||
- Centralized docs in `/docs/` folder
|
|
||||||
- Clear architectural documentation
|
|
||||||
|
|
||||||
### ✅ **Configuration Management**
|
### ✅ **Configuration Management**
|
||||||
|
|
||||||
- Environment files at root level
|
Centralized configuration with environment-based templates:
|
||||||
- Build configurations easily accessible
|
|
||||||
- Docker and K8s configs clearly separated
|
|
||||||
|
|
||||||
## Benefits
|
```
|
||||||
|
config/
|
||||||
|
└── unified.config.ts # Single source of truth
|
||||||
|
|
||||||
🎯 **Maintainability** - Clear structure makes code easy to maintain
|
# Template approach
|
||||||
🔍 **Discoverability** - Logical organization helps find files quickly
|
index.html.template → index.html # Processed with environment variables
|
||||||
🧪 **Testability** - Well-organized test structure
|
.env.example → .env # User customization
|
||||||
📦 **Deployability** - Scripts and configs clearly separated
|
```
|
||||||
|
|
||||||
|
**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
|
👥 **Team Collaboration** - Consistent patterns across the project
|
||||||
📈 **Scalability** - Structure supports growth and new features
|
🛡️ **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.
|
||||||
|
|||||||
@@ -1,159 +1,278 @@
|
|||||||
# 🎯 Template-Based Kubernetes Configuration
|
# 🎯 Template-Based Configuration Approach
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
We've implemented a **template-based approach** using environment variables instead of manual base64 encoding for Kubernetes secrets. This is much more user-friendly and secure.
|
RxMinder uses a **template-based configuration approach** with environment variables to provide flexible, secure, and maintainable configuration management across different environments.
|
||||||
|
|
||||||
## 🆚 Before vs After Comparison
|
## 🆚 Configuration Philosophy
|
||||||
|
|
||||||
### ❌ Before (Manual Base64 Encoding)
|
### ❌ Before (Hardcoded Values)
|
||||||
|
|
||||||
**Old approach required manual base64 encoding:**
|
**Old approach with hardcoded configuration:**
|
||||||
|
|
||||||
```yaml
|
```typescript
|
||||||
# k8s/couchdb-secret.yaml
|
// Hardcoded configuration
|
||||||
apiVersion: v1
|
const config = {
|
||||||
kind: Secret
|
appName: 'RxMinder',
|
||||||
data:
|
baseUrl: 'http://localhost:5173',
|
||||||
# User had to manually encode:
|
dbUrl: 'http://localhost:5984',
|
||||||
# echo -n "admin" | base64 -> YWRtaW4=
|
adminPassword: 'admin123', // ❌ Security risk
|
||||||
# echo -n "password" | base64 -> cGFzc3dvcmQ=
|
};
|
||||||
username: YWRtaW4=
|
|
||||||
password: cGFzc3dvcmQ=
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Problems:**
|
**Problems:**
|
||||||
|
|
||||||
- 😣 Manual base64 encoding required
|
- 😣 No environment flexibility
|
||||||
- 🔧 Error-prone (encoding mistakes)
|
- 🔧 Configuration changes require code changes
|
||||||
- 📝 Hard to read/verify credentials
|
- 📝 Hard to customize for different deployments
|
||||||
- 🔒 Credentials visible in YAML files
|
- 🔒 Security risks with hardcoded credentials
|
||||||
|
|
||||||
### ✅ After (Template-Based)
|
### ✅ After (Template-Based)
|
||||||
|
|
||||||
**New approach uses templates with automatic substitution:**
|
**New approach uses environment variables with templates:**
|
||||||
|
|
||||||
```yaml
|
```typescript
|
||||||
# k8s/couchdb-secret.yaml.template
|
// Environment-based configuration
|
||||||
apiVersion: v1
|
const config = {
|
||||||
kind: Secret
|
appName: process.env.VITE_APP_NAME || 'RxMinder',
|
||||||
metadata:
|
baseUrl: process.env.VITE_BASE_URL || 'http://localhost:5173',
|
||||||
name: couchdb-secret
|
dbUrl: process.env.VITE_COUCHDB_URL || 'http://localhost:5984',
|
||||||
labels:
|
adminPassword: process.env.VITE_COUCHDB_PASSWORD, // ✅ Secure
|
||||||
app: ${APP_NAME}
|
};
|
||||||
type: Opaque
|
|
||||||
stringData:
|
|
||||||
# Kubernetes automatically base64 encodes stringData
|
|
||||||
username: ${COUCHDB_USER}
|
|
||||||
password: ${COUCHDB_PASSWORD}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
**Benefits:**
|
**Benefits:**
|
||||||
|
|
||||||
- ✅ No manual base64 encoding needed
|
- ✅ Environment-specific configuration
|
||||||
- ✅ Environment variables from `.env` file
|
- ✅ No hardcoded secrets in code
|
||||||
- ✅ Human-readable configuration
|
- ✅ Easy customization via `.env` files
|
||||||
- ✅ Automatic deployment script
|
- ✅ Template processing for HTML and other assets
|
||||||
- ✅ Customizable app names
|
- ✅ Type-safe configuration with validation
|
||||||
|
|
||||||
## 🚀 How It Works
|
## 🚀 How It Works
|
||||||
|
|
||||||
### 1. Configuration in `.env`
|
### 1. Environment Configuration
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# .env (user-friendly configuration)
|
# .env.example (template for all environments)
|
||||||
APP_NAME=my-rxminder
|
VITE_APP_NAME=RxMinder
|
||||||
COUCHDB_USER=admin
|
VITE_BASE_URL=http://localhost:5173
|
||||||
COUCHDB_PASSWORD=super-secure-password-123
|
VITE_COUCHDB_URL=http://localhost:5984
|
||||||
INGRESS_HOST=rxminder.mydomain.com
|
VITE_COUCHDB_USER=admin
|
||||||
|
VITE_COUCHDB_PASSWORD=secure-password-123
|
||||||
|
|
||||||
|
# Email configuration (optional)
|
||||||
|
VITE_MAILGUN_API_KEY=your-mailgun-api-key
|
||||||
|
VITE_MAILGUN_DOMAIN=your-domain.com
|
||||||
|
|
||||||
|
# OAuth configuration (optional)
|
||||||
|
VITE_GOOGLE_CLIENT_ID=your-google-client-id
|
||||||
|
VITE_GITHUB_CLIENT_ID=your-github-client-id
|
||||||
|
|
||||||
|
# Feature flags
|
||||||
|
ENABLE_EMAIL_VERIFICATION=true
|
||||||
|
ENABLE_OAUTH=true
|
||||||
|
DEBUG_MODE=false
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2. Template Substitution
|
### 2. Template Processing
|
||||||
|
|
||||||
|
#### HTML Template Processing
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- index.html.template -->
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<title>${APP_NAME}</title>
|
||||||
|
<meta name="description" content="${APP_NAME} - Medication Reminder App" />
|
||||||
|
</head>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Processed to:**
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- index.html -->
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<title>MyCustomApp</title>
|
||||||
|
<meta name="description" content="MyCustomApp - Medication Reminder App" />
|
||||||
|
</head>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Configuration Template
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// config/unified.config.ts (centralized configuration)
|
||||||
|
export const unifiedConfig = {
|
||||||
|
app: {
|
||||||
|
name: import.meta.env.VITE_APP_NAME || 'RxMinder',
|
||||||
|
environment: import.meta.env.NODE_ENV || 'development',
|
||||||
|
baseUrl: import.meta.env.VITE_BASE_URL || 'http://localhost:5173',
|
||||||
|
version: import.meta.env.VITE_APP_VERSION || '0.0.0',
|
||||||
|
},
|
||||||
|
database: {
|
||||||
|
url: import.meta.env.VITE_COUCHDB_URL || 'http://localhost:5984',
|
||||||
|
username: import.meta.env.VITE_COUCHDB_USER || 'admin',
|
||||||
|
password: import.meta.env.VITE_COUCHDB_PASSWORD || '',
|
||||||
|
},
|
||||||
|
features: {
|
||||||
|
emailVerification: import.meta.env.ENABLE_EMAIL_VERIFICATION === 'true',
|
||||||
|
oauth: import.meta.env.ENABLE_OAUTH === 'true',
|
||||||
|
debug: import.meta.env.DEBUG_MODE === 'true',
|
||||||
|
},
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Development vs Production
|
||||||
|
|
||||||
|
#### Development Environment
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Automatic substitution with envsubst
|
# .env (development)
|
||||||
envsubst < k8s/couchdb-secret.yaml.template
|
VITE_APP_NAME=RxMinder-Dev
|
||||||
|
VITE_COUCHDB_URL=http://localhost:5984
|
||||||
|
DEBUG_MODE=true
|
||||||
|
ENABLE_EMAIL_VERIFICATION=false
|
||||||
```
|
```
|
||||||
|
|
||||||
**Result:**
|
#### Production Environment
|
||||||
|
|
||||||
```yaml
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Secret
|
|
||||||
metadata:
|
|
||||||
name: couchdb-secret
|
|
||||||
labels:
|
|
||||||
app: my-rxminder
|
|
||||||
type: Opaque
|
|
||||||
stringData:
|
|
||||||
username: admin
|
|
||||||
password: super-secure-password-123
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Kubernetes Processing
|
|
||||||
|
|
||||||
- Kubernetes automatically base64 encodes `stringData` fields
|
|
||||||
- No manual encoding required
|
|
||||||
- More secure and reliable
|
|
||||||
|
|
||||||
## 🎛️ Deployment Options
|
|
||||||
|
|
||||||
### Option 1: Automated Script (Recommended)
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Copy and configure
|
# .env.production
|
||||||
cp .env.example .env
|
VITE_APP_NAME=MedicationTracker
|
||||||
nano .env
|
VITE_COUCHDB_URL=https://your-couchdb.com
|
||||||
|
ENABLE_EMAIL_VERIFICATION=true
|
||||||
# Deploy everything
|
ENABLE_OAUTH=true
|
||||||
./scripts/k8s-deploy-template.sh deploy
|
DEBUG_MODE=false
|
||||||
```
|
```
|
||||||
|
|
||||||
### Option 2: Manual Template Processing
|
## 🔧 Template Files in Project
|
||||||
|
|
||||||
```bash
|
### 1. HTML Templates
|
||||||
# Set environment variables
|
|
||||||
export APP_NAME=my-rxminder
|
|
||||||
export COUCHDB_PASSWORD=secure-password
|
|
||||||
|
|
||||||
# Process templates
|
- **`index.html.template`** - Main HTML entry point with variable substitution
|
||||||
envsubst < k8s/couchdb-secret.yaml.template | kubectl apply -f -
|
- **`index.html`** - Generated file (processed by `scripts/process-html.sh`)
|
||||||
envsubst < k8s/ingress.yaml.template | kubectl apply -f -
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 Template Files Created
|
### 2. Configuration Templates
|
||||||
|
|
||||||
1. **`k8s/couchdb-secret.yaml.template`** - Database credentials
|
- **`.env.example`** - Template for environment configuration
|
||||||
2. **`k8s/ingress.yaml.template`** - Ingress with custom hostname
|
- **`config/unified.config.ts`** - Centralized configuration with validation
|
||||||
3. **`k8s/configmap.yaml.template`** - Application configuration
|
|
||||||
4. **`k8s/frontend-deployment.yaml.template`** - Frontend deployment
|
### 3. Processing Scripts
|
||||||
5. **`scripts/k8s-deploy-template.sh`** - Automated deployment script
|
|
||||||
|
- **`scripts/process-html.sh`** - HTML template processing
|
||||||
|
- **`package.json`** - Scripts for template processing (`predev`, `prebuild`)
|
||||||
|
|
||||||
## 🛡️ Security Benefits
|
## 🛡️ Security Benefits
|
||||||
|
|
||||||
- **No hardcoded credentials** in version control
|
### Environment Separation
|
||||||
- **Environment-specific configuration** via `.env` files
|
|
||||||
- **Automatic validation** of required variables
|
|
||||||
- **Kubernetes stringData** (auto base64 encoding)
|
|
||||||
- **Clear separation** of config and code
|
|
||||||
|
|
||||||
## 📝 User Experience Improvements
|
- **Development**: Uses mock data and relaxed security
|
||||||
|
- **Production**: Requires all security features and real credentials
|
||||||
|
- **Clear boundaries** between environments
|
||||||
|
|
||||||
| Aspect | Before | After |
|
### Credential Management
|
||||||
| -------------------- | ------------------------ | ---------------------- |
|
|
||||||
| **Setup Complexity** | High (manual base64) | Low (edit .env) |
|
|
||||||
| **Error Rate** | High (encoding mistakes) | Low (plain text) |
|
|
||||||
| **Readability** | Poor (base64 strings) | Excellent (plain text) |
|
|
||||||
| **Customization** | Manual file editing | Environment variables |
|
|
||||||
| **Deployment** | Multi-step manual | Single command |
|
|
||||||
|
|
||||||
## 🎯 Result
|
- **No secrets in code** - All sensitive data in environment variables
|
||||||
|
- **Environment-specific secrets** - Different credentials per environment
|
||||||
|
- **Template validation** - Ensures required variables are set
|
||||||
|
|
||||||
The template-based approach makes RxMinder deployment:
|
### Configuration Validation
|
||||||
|
|
||||||
- **More user-friendly** - No technical encoding required
|
```typescript
|
||||||
- **More secure** - Credentials externalized to `.env`
|
// Automatic validation in unified.config.ts
|
||||||
- **More maintainable** - Clear separation of config and manifests
|
if (!unifiedConfig.database.password && unifiedConfig.app.environment === 'production') {
|
||||||
- **More flexible** - Easy customization via environment variables
|
throw new Error('Database password is required in production');
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
This is a **production-ready, enterprise-grade** configuration management approach that follows Kubernetes best practices.
|
## 📝 Development Workflow
|
||||||
|
|
||||||
|
### 1. Initial Setup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Copy template
|
||||||
|
cp .env.example .env
|
||||||
|
|
||||||
|
# Customize for your environment
|
||||||
|
nano .env
|
||||||
|
|
||||||
|
# Process templates
|
||||||
|
bun run predev
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start with template processing
|
||||||
|
bun run dev # Automatically runs predev
|
||||||
|
|
||||||
|
# Templates are processed automatically
|
||||||
|
# HTML title updates based on APP_NAME
|
||||||
|
# Configuration updates based on environment variables
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Building
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Production build with template processing
|
||||||
|
bun run build # Automatically runs prebuild
|
||||||
|
|
||||||
|
# Templates processed for production
|
||||||
|
# Environment variables baked into build
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🎯 Benefits
|
||||||
|
|
||||||
|
### For Developers
|
||||||
|
|
||||||
|
| Aspect | Before | After |
|
||||||
|
| ----------------- | ------------------- | ------------------------- |
|
||||||
|
| **Setup** | Manual file editing | Copy `.env.example` |
|
||||||
|
| **Customization** | Code changes | Environment variables |
|
||||||
|
| **Testing** | Hardcoded test data | Environment-based mocking |
|
||||||
|
| **Debugging** | Console hunting | Centralized debug flags |
|
||||||
|
|
||||||
|
### For Operations
|
||||||
|
|
||||||
|
| Aspect | Before | After |
|
||||||
|
| -------------- | -------------------- | ---------------------- |
|
||||||
|
| **Deployment** | Manual configuration | Environment-based |
|
||||||
|
| **Security** | Hardcoded secrets | External configuration |
|
||||||
|
| **Monitoring** | Scattered settings | Centralized config |
|
||||||
|
| **Scaling** | Per-instance setup | Template replication |
|
||||||
|
|
||||||
|
## 🔍 Best Practices
|
||||||
|
|
||||||
|
### Environment Variable Naming
|
||||||
|
|
||||||
|
- Use `VITE_` prefix for client-side variables
|
||||||
|
- Use descriptive names (`VITE_COUCHDB_PASSWORD` vs `PASSWORD`)
|
||||||
|
- Group related variables (`VITE_MAILGUN_API_KEY`, `VITE_MAILGUN_DOMAIN`)
|
||||||
|
|
||||||
|
### Template Organization
|
||||||
|
|
||||||
|
- Keep templates close to generated files
|
||||||
|
- Use clear naming conventions (`.template` suffix)
|
||||||
|
- Document all template variables
|
||||||
|
|
||||||
|
### Validation Strategy
|
||||||
|
|
||||||
|
- Validate required variables at startup
|
||||||
|
- Provide clear error messages for missing configuration
|
||||||
|
- Use TypeScript for compile-time validation
|
||||||
|
|
||||||
|
## 🚀 Result
|
||||||
|
|
||||||
|
The template-based approach makes RxMinder configuration:
|
||||||
|
|
||||||
|
- **More flexible** - Easy customization for different environments
|
||||||
|
- **More secure** - No hardcoded secrets in source code
|
||||||
|
- **More maintainable** - Centralized configuration management
|
||||||
|
- **More scalable** - Template-driven deployment processes
|
||||||
|
|
||||||
|
This approach follows modern application configuration best practices and provides a solid foundation for development, testing, and future deployment needs.
|
||||||
|
|||||||
Reference in New Issue
Block a user