76aa2c72c5
docs: Add production deployment success documentation for Azure Static Web App docs: Create Quick Start guide for project setup and deployment instructions docs: Update README.md to include new documentation links and structure docs: Enhance User Manual with detailed portal access, roles, and AI assistance features scripts: Implement architecture diagram export script using Mermaid CLI scripts: Create script to auto-generate documentation index for easier navigation chore: Remove unused update-doc-index script
240 lines
17 KiB
Markdown
240 lines
17 KiB
Markdown
# Miracles In Motion - Public Web Platform
|
||
|
||
Enterprise-grade, AI-enabled nonprofit platform (public site + portals + real-time services) for Miracles In Motion, a 501(c)3 organization.
|
||
|
||
## 🌟 About Miracles In Motion
|
||
|
||
Miracles In Motion is a registered 501(c)3 non-profit organization committed to making a meaningful difference in the lives of individuals and families in need. Through our various programs and initiatives, we strive to provide hope, support, and resources to those who need it most.
|
||
|
||
## 🚀 Platform Highlights
|
||
|
||
- **Portals Suite**: Admin, Volunteer, Resource, AI Assistance, Training, Analytics, Mobile Volunteer
|
||
- **AI Matching Engine**: Student assistance recommendations with confidence scoring
|
||
- **Multi-Language**: 8 languages + RTL support (Arabic)
|
||
- **Real-Time Updates**: WebSocket/SignalR for live metrics and request processing
|
||
- **PWA & Offline**: Installable app, caching, background sync
|
||
- **Performance & SEO**: Optimized bundle, Web Vitals tracking, structured data
|
||
- **Scalable Deployment**: Azure Static Web Apps (Standard SKU) + Functions backend
|
||
- **Security & Compliance**: Role-based access; future MFA & audit logging roadmap
|
||
|
||
## 🛠 Technology Stack
|
||
|
||
- **Frontend**: React 18 + TypeScript + Vite
|
||
- **Styling**: Tailwind CSS, Framer Motion animations
|
||
- **AI/ML (planned / partial)**: TensorFlow.js models (matching, impact)
|
||
- **State & Data**: Context + hooks; CRM connector (Salesforce integration draft)
|
||
- **Payments**: Stripe integration (test keys by default)
|
||
- **Internationalization**: i18next multi-language framework
|
||
- **Deployment**: Azure Static Web Apps (Standard SKU) & Azure Functions
|
||
- **Monitoring**: Web Vitals hook; future Application Insights integration
|
||
- **Testing**: Vitest + @testing-library/react
|
||
|
||
## 📁 Project Structure
|
||
|
||
```
|
||
miracles_in_motion/
|
||
├── README.md # Project documentation
|
||
├── package.json # Dependencies and scripts
|
||
├── tsconfig.json # TypeScript configuration
|
||
├── vite.config.ts # Vite build configuration
|
||
├── tailwind.config.cjs # Tailwind CSS configuration
|
||
├── postcss.config.cjs # PostCSS configuration
|
||
├── .eslintrc.cjs # ESLint configuration
|
||
├── .gitignore # Git ignore rules
|
||
├── .env.example # Environment variables template
|
||
├── index.html # Main HTML entry point
|
||
├── public/ # Static assets
|
||
│ ├── favicon.svg # Website favicon
|
||
│ ├── og-image.png # Open Graph image
|
||
│ ├── robots.txt # Search engine directives
|
||
│ └── site.webmanifest # PWA manifest
|
||
├── src/ # Source code
|
||
│ ├── main.tsx # Vite entry point
|
||
│ ├── index.css # Global styles & Tailwind
|
||
│ ├── App.tsx # Complete React application
|
||
│ ├── assets/ # Static assets for bundling
|
||
│ │ └── logos/ # Brand assets
|
||
│ ├── lib/ # Utility libraries
|
||
│ │ ├── analytics.ts # Analytics integration
|
||
│ │ └── routing.ts # Hash routing utilities
|
||
│ └── components/ # Reusable components (optional)
|
||
│ ├── LogoMark.tsx
|
||
│ ├── Nav.tsx
|
||
│ ├── Footer.tsx
|
||
│ ├── ui/ # Shared UI components
|
||
│ └── pages/ # Page components
|
||
│ ├── HomePage.tsx
|
||
│ ├── DonatePage.tsx
|
||
│ ├── VolunteerPage.tsx
|
||
│ ├── SponsorsPage.tsx
|
||
│ ├── StoriesPage.tsx
|
||
│ ├── TestimoniesPage.tsx
|
||
│ └── LegalPage.tsx
|
||
├── scripts/ # Build and utility scripts
|
||
│ └── generate-og.mjs # Open Graph image generator
|
||
├── assets/ # External assets (not bundled)
|
||
│ ├── images/ # Photos and graphics
|
||
│ └── documents/ # PDFs and legal documents
|
||
└── docs/ # Additional documentation
|
||
```
|
||
|
||
## <20> Documentation
|
||
|
||
Central index: `docs/README.md`
|
||
|
||
Key references:
|
||
- **QuickStart**: `docs/QuickStart.md` – install, run, test, deploy
|
||
- **User Manual**: `docs/UserManual.md` – portals, roles, features
|
||
- **Architecture**: `docs/PHASE3_ARCHITECTURE.md`
|
||
- **AI Implementation Plan**: `docs/PHASE3_AI_IMPLEMENTATION.md`
|
||
- **Performance & SEO**: `docs/PHASE5C_PERFORMANCE_COMPLETE.md`
|
||
- **Enterprise Reports**: phase completion & deployment success docs in `docs/`
|
||
|
||
## ⚡ Quick Start (Abbreviated)
|
||
See full instructions in `docs/QuickStart.md`.
|
||
```bash
|
||
git clone https://github.com/Miracles-In-Motion/public-web.git
|
||
cd public-web
|
||
npm install --legacy-peer-deps
|
||
npm run dev
|
||
# visit http://localhost:5173
|
||
```
|
||
|
||
### Scripts
|
||
```bash
|
||
npm run dev # Front-end dev server
|
||
npm test # Run test suite
|
||
npm run build # Production build (frontend)
|
||
npm run preview # Preview build locally
|
||
npm run lint # Lint code
|
||
node scripts/generate-og.mjs # Generate OG images
|
||
```
|
||
|
||
### Building for Production
|
||
|
||
```bash
|
||
# Full production build
|
||
npm run build
|
||
|
||
# The built files will be in the `dist/` directory
|
||
```
|
||
|
||
### Azure Deployment (Standard SKU)
|
||
Refer to `docs/QuickStart.md` for full flow.
|
||
```bash
|
||
az login
|
||
az group create --name rg-mim-prod --location eastus2
|
||
az staticwebapp create \
|
||
--name mim-prod-web-standard \
|
||
--resource-group rg-mim-prod \
|
||
--location eastus2 \
|
||
--source . \
|
||
--branch main \
|
||
--app-location / \
|
||
--output-location dist
|
||
```
|
||
|
||
## 📄 Core Portals & Features
|
||
| Portal | Purpose |
|
||
|--------|---------|
|
||
| Admin | Oversight, approvals, metrics |
|
||
| Volunteer | Assignments, status updates |
|
||
| Resource | Student assistance matching |
|
||
| AI Assistance | Recommendations + confidence |
|
||
| Staff Training | Module progress & badges |
|
||
| Analytics | KPIs, trends, predictive insights |
|
||
| Mobile Volunteer | Touch-optimized PWA workflow |
|
||
|
||
## 🎨 Customization
|
||
- Content & layout adjustments: `src/` (pages, components)
|
||
- Branding assets: `assets/images/`, `public/`
|
||
- Routing additions: update navigation + portal components
|
||
|
||
## 🔧 Configuration
|
||
Environment variables (example) in `.env.local`:
|
||
```env
|
||
VITE_API_BASE=/api
|
||
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
|
||
VITE_DEFAULT_LANGUAGE=en
|
||
VITE_SUPPORTED_LANGUAGES=en,es,fr,de,zh,ar,pt,ru
|
||
```
|
||
|
||
### Analytics
|
||
Google Analytics is integrated and ready to track:
|
||
- Page views
|
||
- Donation conversions
|
||
- Volunteer sign-ups
|
||
- Contact form submissions
|
||
|
||
## 📱 Mobile Optimization
|
||
|
||
The site is fully responsive with:
|
||
- Mobile-first design approach
|
||
- Touch-friendly navigation
|
||
- Optimized images for different screen sizes
|
||
- Fast loading times on mobile networks
|
||
|
||
## ♿ Accessibility
|
||
|
||
We're committed to accessibility:
|
||
- ARIA labels and roles
|
||
- Keyboard navigation support
|
||
- High contrast mode compatibility
|
||
- Screen reader optimization
|
||
- Alt text for all images
|
||
|
||
## 🤝 Contributing
|
||
|
||
We welcome contributions! Please:
|
||
|
||
1. Fork the repository
|
||
2. Create a feature branch
|
||
3. Make your changes
|
||
4. Test thoroughly
|
||
5. Submit a pull request
|
||
|
||
## 📞 Support
|
||
Questions / issues:
|
||
- Email: contact@mim4u.org
|
||
- GitHub Issues: https://github.com/Miracles-In-Motion/public-web/issues
|
||
|
||
## 📄 Legal
|
||
|
||
### 501(c)3 Status
|
||
Miracles In Motion is a registered 501(c)3 non-profit organization.
|
||
- EIN: [Your EIN Number]
|
||
- State Registration: [Your State Registration]
|
||
|
||
### Privacy Policy
|
||
We are committed to protecting your privacy. See our full [Privacy Policy](assets/documents/privacy-policy.pdf).
|
||
|
||
### Terms of Service
|
||
By using this website, you agree to our [Terms of Service](assets/documents/terms-of-service.pdf).
|
||
|
||
## 📊 Performance
|
||
|
||
The website is optimized for:
|
||
- **Page Speed**: <3 second load times
|
||
- **SEO**: Structured data and meta optimization
|
||
- **Lighthouse Score**: 90+ across all metrics
|
||
- **Core Web Vitals**: Excellent ratings
|
||
|
||
## 🔄 Updates & Maintenance
|
||
|
||
- **Content Updates**: Monthly review of all content
|
||
- **Security Updates**: Quarterly security audits
|
||
- **Performance Monitoring**: Continuous monitoring
|
||
- **Backup Strategy**: Daily automated backups
|
||
|
||
---
|
||
|
||
## 💖 Our Mission
|
||
|
||
*"At Miracles In Motion, we believe that every act of kindness creates a ripple effect of positive change. Through compassionate action and community support, we work to transform lives and build a better tomorrow for all."*
|
||
|
||
---
|
||
|
||
**Miracles In Motion** | 501(c)3 Non-Profit Organization
|
||
Creating Hope • Inspiring Change • Building Community
|
||
|
||
© 2025 Miracles In Motion. All rights reserved. |