will/rxminder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refocus architecture docs on current development state

Browse Source 
- 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
2025-09-08 21:37:46 -07:00
parent 280eb489e7
commit f51bdeb284
2 changed files with 502 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

380
docs/architecture/PROJECT_STRUCTURE.md
View File

@@ -1,50 +1,21 @@
# 📁 Project Structure
## Final Organized Structure
## Current Development Structure
```
rxminder/
├── 📄 README.md # Main documentation
├── package.json # Dependencies and scripts
├── 📄 README.md # Main project documentation
├── 📦 package.json # Dependencies and scripts
├── ⚙️ vite.config.ts # Build 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
├── 📊 metadata.json # Project metadata
├── 🖼️ banner.jpeg # Project banner image
│
├── <EFBFBD> docker/ # Container configuration
│ ├── 🐳 Dockerfile # Multi-stage Docker build
│ ├── <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
├── 🚀 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
@@ -81,102 +52,293 @@ rxminder/
│
├── 📁 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
│ │ ├── 📋 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
│ ├── 📧 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
│ ├── 📁 templates/ # Email templates
│ │ └── ✉️ verification.email.ts
│ └── 📁 __tests__/ # Unit tests
│ └── 📁 __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
│ └── 👤 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
│ ├── 💾 useLocalStorage.ts # Persistent storage
│ ├── ⚙️ useSettings.ts # User preferences
│ ├── 🎨 useTheme.ts # Theme management
│ └── 👤 useUserData.ts # User data management
│
├── 📁 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
│ ├── 🔐 SECURITY.md # Security guidelines
│ ├── 🚀 DEPLOYMENT.md # Deployment instructions
│ └── 📖 API.md # API 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
│
├── 📁 k8s/ # Kubernetes manifests
│ ├── 📝 README.md # K8s deployment guide
│ ├── 🗺️ configmap.yaml # Configuration
│ ├── 🔒 *-secret.yaml # Secrets
│ ├── 🚀 *-deployment.yaml # Deployments
│ ├── 🌐 *-service.yaml # Services
│ ├── 📊 hpa.yaml # Auto-scaling
│ ├── 🌐 ingress.yaml # Load balancing
│ └── 🔒 network-policy.yaml # Network security
├── 📁 coverage/ # Test coverage reports
├── 📁 dist/ # Production build output
├── 📁 node_modules/ # Dependencies
│
└── 📁 .github/ # GitHub configuration
├── 📝 pull_request_template.md
└── 📁 ISSUE_TEMPLATE/
├── 🐛 bug_report.md
└── ✨ feature_request.md
└── 📁 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 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
- Easy to locate related files
### ✅ **Script Centralization**
- 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
- Reusable business logic
- Easy to test and mock
- Strategy pattern allows flexible implementations
### ✅ **Configuration Management**
- Environment files at root level
- Build configurations easily accessible
- Docker and K8s configs clearly separated
Centralized configuration with environment-based templates:
## Benefits
```
config/
└── unified.config.ts # Single source of truth
🎯 **Maintainability** - Clear structure makes code easy to maintain
🔍 **Discoverability** - Logical organization helps find files quickly
🧪 **Testability** - Well-organized test structure
📦 **Deployability** - Scripts and configs clearly separated
# 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
📈 **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.