rxminder/docs/architecture/PROJECT_STRUCTURE.md

📁 Project Structure

Final Organized Structure

rxminder/
├── 📄 README.md                    # Main documentation
├──  package.json                 # Dependencies and scripts
├── ⚙️ vite.config.ts               # Build configuration
├── 📝 tsconfig.json                # TypeScript configuration
├── 🎨 index.html                   # Entry point
├── 🔒 .env.example                 # Environment template
├── 📊 metadata.json                # Project metadata
├── 🖼️ banner.jpeg                  # Project banner image
│
├── <20> 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
│
├── 📁 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
│   ├── 🗄️ couchdb.ts              # Mock database service
│   ├── 🗄️ couchdb.production.ts   # Real CouchDB service
│   ├── 🏭 couchdb.factory.ts      # Service factory
│   ├── 📧 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
│
├── 📁 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
│
├── 📁 docs/                        # Project documentation
│   ├── 🔐 SECURITY.md             # Security guidelines
│   ├── 🚀 DEPLOYMENT.md           # Deployment instructions
│   └── 📖 API.md                  # API documentation
│
├── 📁 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
│
└── 📁 .github/                     # GitHub configuration
    ├── 📝 pull_request_template.md
    └── 📁 ISSUE_TEMPLATE/
        ├── 🐛 bug_report.md
        └── ✨ feature_request.md

Key Organizational Principles

✅ Feature-Based Organization

• 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

✅ Configuration Management

• Environment files at root level
• Build configurations easily accessible
• Docker and K8s configs clearly separated

Benefits

🎯 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
👥 Team Collaboration - Consistent patterns across the project
📈 Scalability - Structure supports growth and new features