Added readme

apartment-dashboard-readme.md

@@ -0,0 +1,306 @@
+# 🏠 Country Club Towers & Gardens - Apartment Dashboard
+
+A real-time React dashboard for monitoring apartment availability, pricing trends, and market analytics at Country Club Towers & Gardens.
+
+## 🚀 Live Dashboard
+
+**URL:** https://apartments.maverickapplications.com
+
+## 📋 Features
+
+### 📊 Overview Dashboard
+- **Real-time metrics**: Available units, new units today, rented units, turnover rate
+- **Price trend charts**: 15-day moving average with area charts
+- **Unit availability tracking**: Visual representation of market supply
+- **Floor plan distribution**: Pie chart showing unit types by plan
+- **Recent activity feed**: New units, rentals, and price changes
+
+### 🏠 Available Units View
+- **Interactive unit cards** with detailed information
+- **Priority highlighting** for Maroon Peak units (< $3,800)
+- **Filtering options** by floor plan and bedroom count
+- **Price range visualization** showing current price position
+- **Detailed unit modal** with price history charts
+
+### 📈 Market Analytics
+- **Price distribution** by floor plan
+- **Market insights** with actionable recommendations
+- **Trend analysis** and activity indicators
+
+## 🛠️ Technology Stack
+
+- **Frontend**: React 18 + Vite
+- **Styling**: Tailwind CSS
+- **Charts**: Recharts
+- **Icons**: Lucide React
+- **Deployment**: Docker + Nginx
+- **CI/CD**: Gitea Actions
+- **Reverse Proxy**: Traefik with SSL
+
+## 🔄 Development Workflow
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://git.maverickapplications.com/stephen/apartment-dashboard.git
+cd apartment-dashboard
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+# App will be available at http://localhost:5173
+
+# Build for production
+npm run build
+```
+
+### Making Changes
+
+1. **Create a new branch** (optional but recommended):
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** and test locally
+
+3. **Commit and push**:
+   ```bash
+   git add .
+   git commit -m "Description of your changes"
+   git push origin main  # or your branch name
+   ```
+
+4. **Automatic deployment**: The Gitea Actions workflow will automatically:
+   - Build the React app
+   - Create a Docker image
+   - Deploy to production
+   - Make it available at https://apartments.maverickapplications.com
+
+## 🚀 Deployment Architecture
+
+### Current Setup
+- **Source**: Gitea repository (`git.maverickapplications.com`)
+- **CI/CD**: Gitea Actions with Act runner
+- **Container**: Docker with Nginx serving built React app
+- **Routing**: Traefik reverse proxy with automatic SSL
+- **Domain**: `apartments.maverickapplications.com`
+
+### File Locations
+- **Source code**: Git repository only
+- **Running app**: Docker container (`apartment-dashboard`)
+- **Built files**: Inside container at `/usr/share/nginx/html`
+- **Docker Compose**: Exists only during CI/CD deployment (not persisted on host)
+- **Management**: Use direct Docker commands or redeploy via Gitea Actions
+
+### Auto-restart Behavior
+✅ **The app will automatically restart** after server reboots due to `restart: unless-stopped` in docker-compose.yml
+
+## 🔧 Operational Commands
+
+### Check App Status
+```bash
+# Check if container is running
+docker ps | grep apartment-dashboard
+
+# View container logs
+docker logs apartment-dashboard
+
+# Check detailed container info
+docker inspect apartment-dashboard
+```
+
+### Manual Control
+
+**Note**: Since the app is deployed via CI/CD, there's no persistent docker-compose.yml on the host filesystem. Use Docker commands directly:
+
+```bash
+# Stop the app
+docker stop apartment-dashboard
+docker rm apartment-dashboard
+
+# Restart the app (redeploy)
+# Push a new commit to trigger redeployment, or manually trigger workflow in Gitea Actions
+
+# Restart existing container
+docker restart apartment-dashboard
+
+# View logs in real-time
+docker logs -f apartment-dashboard
+
+# Quick restart without rebuild
+docker restart apartment-dashboard
+```
+
+**For full redeployment**: Go to Gitea Actions tab and manually trigger the workflow, or push a new commit.
+
+### Troubleshooting
+```bash
+# Check Traefik routing
+curl -I https://apartments.maverickapplications.com
+
+# Check if Traefik sees the service
+# Visit: https://traefik.maverickapplications.com
+
+# Test container directly (bypass Traefik)
+docker exec apartment-dashboard curl -I http://localhost:80
+
+# Check container filesystem
+docker exec apartment-dashboard ls -la /usr/share/nginx/html
+```
+
+## 🔄 CI/CD Pipeline
+
+The deployment pipeline is fully automated through Gitea Actions:
+
+### Workflow Trigger
+- **Push to main branch** → Automatic deployment
+- **Manual trigger** → Available in Actions tab
+
+### Pipeline Steps
+1. **Checkout code** from Gitea
+2. **Setup Node.js** environment
+3. **Install dependencies** (`npm ci`)
+4. **Build React app** (`npm run build`)
+5. **Build Docker image** with Nginx
+6. **Deploy to server** and start container
+7. **Verify deployment** is successful
+
+### Workflow File
+`.github/workflows/deploy.yml` - Contains the complete deployment pipeline
+
+## 📁 Project Structure
+
+```
+apartment-dashboard/
+├── src/
+│   ├── App.jsx              # Main dashboard component
+│   ├── index.css            # Global styles + Tailwind
+│   └── main.jsx             # React entry point
+├── public/                  # Static assets
+├── .github/workflows/
+│   └── deploy.yml           # Gitea Actions workflow
+├── docker-compose.yml       # Container orchestration
+├── Dockerfile               # Multi-stage build config
+├── nginx.conf               # Nginx configuration
+├── package.json             # Dependencies and scripts
+├── tailwind.config.js       # Tailwind CSS configuration
+└── README.md                # This file
+```
+
+## 🔐 Security & Performance
+
+### Security Features
+- **SSL/TLS**: Automatic Let's Encrypt certificates via Traefik
+- **Security headers**: Configured in Nginx
+- **Network isolation**: Container runs in Traefik network only
+
+### Performance Optimizations
+- **Multi-stage Docker build**: Minimal production image
+- **Nginx caching**: Static assets cached for 1 year
+- **Gzip compression**: Enabled for all text assets
+- **Production build**: Optimized React bundle
+
+## 🔄 Integration with Apartment Scraper
+
+### Current Status
+The dashboard displays **mock data** that matches your MongoDB structure:
+- Daily summaries (new units, rented units, turnover rates)
+- Unit details (pricing, floor plans, availability)
+- Price history and trends
+- Market analytics
+
+### Next Steps for Live Data
+To connect real data from your apartment scraper:
+
+1. **Create API backend** (Express.js + MongoDB)
+2. **Add API endpoints**:
+   - `GET /api/daily-summary`
+   - `GET /api/price-history`
+   - `GET /api/available-units`
+   - `GET /api/recent-activity`
+3. **Update React app** to fetch from API instead of mock data
+4. **Deploy API backend** through same CI/CD pipeline
+
+## 📊 Data Structure
+
+The dashboard expects data in this format (matching your MongoDB collections):
+
+### Daily Summary
+```javascript
+{
+  date: "2025-01-15",
+  newUnits: 3,
+  rentedUnits: 5,
+  staleUnits: 1,
+  netChange: -3,
+  turnoverRate: 8.2,
+  totalAvailable: 47
+}
+```
+
+### Available Units
+```javascript
+{
+  unitCode: "W2506",
+  planName: "Maroon Peak",
+  bedCount: 2,
+  bathCount: 2,
+  area: 1089,
+  currentPrice: 3750,
+  minPrice: 3650,
+  maxPrice: 3850,
+  daysAvailable: 12,
+  community: "Country Club Towers"
+}
+```
+
+## 🚨 Emergency Procedures
+
+### If App is Down
+1. **Check container status**: `docker ps | grep apartment-dashboard`
+2. **View logs**: `docker logs apartment-dashboard`
+3. **Quick restart**: `docker restart apartment-dashboard`
+4. **Full redeploy**: Push new commit or manually trigger Gitea Actions workflow
+5. **Check Traefik**: Visit traefik dashboard
+
+### If Server Reboots
+✅ **No action needed** - Container will auto-restart
+
+### If Domain Not Accessible
+1. **Check DNS**: `nslookup apartments.maverickapplications.com`
+2. **Check Traefik**: Visit `https://traefik.maverickapplications.com`
+3. **Check container**: `docker ps | grep apartment-dashboard`
+4. **Check logs**: `docker logs traefik`
+
+## 📞 Support Information
+
+### Related Infrastructure
+- **Main infrastructure**: `/media/stephen/Storage_Linux/infrastructure/`
+- **Traefik dashboard**: https://traefik.maverickapplications.com
+- **Gitea repository**: https://git.maverickapplications.com
+- **Harbor registry**: https://registry.maverickapplications.com
+
+### Useful Links
+- **Apartment scraper cron jobs**: Located on server
+- **Email reporting**: `run_email_report.sh`
+- **Data collection**: `run_scraper.sh`
+
+## 📝 Version History
+
+- **v1.0**: Initial dashboard with mock data
+- **Future**: API integration for live apartment data
+
+---
+
+## 🤝 Contributing
+
+1. Create feature branch
+2. Make changes
+3. Test locally with `npm run dev`
+4. Push to repository
+5. Gitea Actions will automatically deploy
+
+**Dashboard URL**: https://apartments.maverickapplications.com