diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dd93b93
--- /dev/null
+++ b/README.md
@@ -0,0 +1,268 @@
+# Ultra Low Power Security Device System
+
+A complete IoT security monitoring solution using Particle Boron LTE for ultra-low-power remote monitoring with immediate local alarm response and secure webhook notifications.
+
+## 🎯 Project Overview
+
+This system provides professional-grade security monitoring for remote locations with:
+- **2+ year battery life** on a single charge
+- **Immediate alarm activation** (sub-second response)
+- **Secure webhook notifications** via SMS/email
+- **Enterprise-grade infrastructure** integration
+- **Ultra-low-power design** for remote installations
+
+## 📊 System Architecture
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│  Particle Boron │───▶│  Particle Cloud  │───▶│ Webhook Service │
+│  + Microswitch  │    │   (Cellular)     │    │   (Traefik)     │
+│  + Alarm        │    └──────────────────┘    └─────────────────┘
+└─────────────────┘                                      │
+                                                         ▼
+                                               ┌─────────────────┐
+                                               │  SMS/Email      │
+                                               │  Notifications  │
+                                               └─────────────────┘
+```
+
+## 🚀 Features
+
+### Hardware Features
+- **Ultra Low Power**: 2+ year battery life (5000mAh Li-Po)
+- **Immediate Response**: Local alarm activates in <1 second
+- **Cellular Connectivity**: Works anywhere with LTE coverage
+- **Weather Resistant**: IP65+ rated enclosure capability
+- **Solar Ready**: Optional solar panel for indefinite operation
+
+### Software Features
+- **Secure Authentication**: Bearer token authentication for webhooks
+- **Rich Notifications**: Battery status, signal strength, device health
+- **Rate Limiting**: DoS protection and security headers
+- **SSL/TLS**: End-to-end encryption via Let's Encrypt
+- **Monitoring Ready**: Prometheus/Grafana integration ready
+
+### Security Features
+- **Device Authentication**: Secure webhook token validation
+- **Network Security**: Traefik reverse proxy with security headers
+- **Local Deterrent**: Immediate alarm before network dependency
+- **Tamper Detection**: Device restart and power cycle monitoring
+
+## 📁 Repository Structure
+
+```
+security-device-system/
+├── README.md                 # This file
+├── particle-device/          # Boron LTE device code
+│   ├── README.md
+│   ├── security_device.ino   # Main device firmware
+│   ├── hardware/             # Wiring diagrams and schematics
+│   └── docs/                 # Device-specific documentation
+└── webhook-server/           # Server-side webhook service
+    ├── README.md
+    ├── webhook_app.py        # Flask webhook application
+    ├── Dockerfile            # Container configuration
+    ├── docker-compose.yml    # Service orchestration
+    ├── requirements.txt      # Python dependencies
+    └── docs/                 # Server deployment guides
+```
+
+## 🔧 Quick Start
+
+### Prerequisites
+- **Hardware**: Particle Boron LTE, microswitch, alarm device, battery
+- **Infrastructure**: Server with Docker, domain name, Traefik reverse proxy
+- **Accounts**: Particle.io account, Gmail account with app password
+
+### 1. Hardware Setup
+```bash
+# See particle-device/README.md for complete hardware setup
+# Basic connections:
+# D2 ← Microswitch (NC configuration)
+# D3 → Alarm device (with driver circuit)
+# VIN ← 3.7V Li-Po battery (5000-10000mAh)
+```
+
+### 2. Server Deployment
+```bash
+# Clone repository
+git clone https://github.com/yourusername/security-device-system.git
+cd security-device-system/webhook-server
+
+# Configure environment
+cp .env.example .env
+nano .env  # Add your credentials
+
+# Deploy with Docker
+docker compose up -d --build
+```
+
+### 3. Device Programming
+```bash
+# See particle-device/README.md for complete setup
+particle flash your-device-name security_device.ino
+```
+
+### 4. Particle Webhook Configuration
+```bash
+# Create webhook pointing to your server
+# URL: https://webhook.yourdomain.com/webhook
+# Auth: Bearer your-webhook-secret
+# See webhook-server/README.md for details
+```
+
+## 📊 Performance Specifications
+
+### Power Consumption
+| Mode | Current Draw | Duration | Daily Average |
+|------|-------------|----------|---------------|
+| Sleep (STOP) | 130μA | 23h 59m | ~95% |
+| Active + Cellular | 300-800mA | 30-60s | ~5% |
+| Alarm Active | +50mA | 10s | During events |
+
+### Battery Life Estimates
+- **5000mAh**: 2-3 years normal operation
+- **10000mAh**: 4-5 years normal operation
+- **With Solar**: Indefinite (6W+ panel)
+
+### Network Usage
+- **Data Usage**: 1-5MB per month typical
+- **Alert Latency**: <30 seconds from trigger to notification
+- **Connection Success**: >95% (good cellular coverage)
+
+## 🛡️ Security Model
+
+### Device Level
+- **Physical Security**: Tamper-evident enclosure
+- **Local Response**: Immediate alarm activation
+- **Secure Boot**: Particle device OS security
+- **OTA Updates**: Encrypted firmware updates
+
+### Network Level
+- **TLS Encryption**: All communications encrypted
+- **Authentication**: Bearer token webhook authentication
+- **Rate Limiting**: 10 req/min average, 20 burst
+- **Security Headers**: XSS, clickjacking, content-type protection
+
+### Infrastructure Level
+- **Reverse Proxy**: Traefik with automatic SSL
+- **Container Security**: Non-root user, minimal attack surface
+- **Monitoring**: Comprehensive logging and health checks
+- **Backup**: Easy configuration backup and restore
+
+## 🔄 Maintenance
+
+### Monthly
+- [ ] Review battery status reports
+- [ ] Check cellular signal strength trends
+- [ ] Verify webhook delivery success rate
+- [ ] Test alarm functionality
+
+### Quarterly
+- [ ] Physical device inspection
+- [ ] Update firmware if available
+- [ ] Test backup power systems
+- [ ] Review security logs
+
+### Annually
+- [ ] Battery replacement (if not solar)
+- [ ] Complete system test
+- [ ] Security assessment
+- [ ] Hardware refresh planning
+
+## 📈 Monitoring & Alerts
+
+### Device Health Monitoring
+- **Daily Reports**: Battery, signal strength, uptime
+- **Critical Alerts**: Low battery, connection failures
+- **Security Events**: Breach detection, device tampering
+- **System Status**: Firmware version, boot count
+
+### Server Health Monitoring
+- **Webhook Success Rate**: >98% delivery target
+- **Response Times**: <5 second average
+- **Error Rates**: <1% target
+- **SSL Certificate**: Auto-renewal monitoring
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+**Device Won't Connect**
+- Check cellular signal strength (-70dBm or better)
+- Verify SIM card activation and data plan
+- Confirm device is claimed to your account
+
+**High Power Consumption**
+- Verify sleep mode operation (130μA target)
+- Check for software loops preventing sleep
+- Confirm cellular radio shutdown in sleep
+
+**Missed Notifications**
+- Check webhook service logs
+- Verify Gmail app password configuration
+- Test SMS gateway email address
+
+**False Alarms**
+- Check microswitch mechanical condition
+- Verify NC (normally closed) wiring
+- Consider environmental factors (wind, vibration)
+
+### Support Resources
+- [Particle Community](https://community.particle.io/)
+- [Traefik Documentation](https://doc.traefik.io/traefik/)
+- [Project Issues](https://github.com/yourusername/security-device-system/issues)
+
+## 📚 Documentation
+
+### Technical Specifications
+- **Hardware Requirements**: See `particle-device/docs/hardware.md`
+- **Power Analysis**: See `particle-device/docs/power-analysis.md`
+- **Network Architecture**: See `webhook-server/docs/architecture.md`
+- **Security Analysis**: See `docs/security-analysis.md`
+
+### Deployment Guides
+- **Production Deployment**: See `webhook-server/docs/production-deployment.md`
+- **Scaling Guide**: See `docs/scaling-guide.md`
+- **Integration Guide**: See `docs/integrations.md`
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+```bash
+# Server development
+cd webhook-server
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Device development
+# Use Particle Workbench or Web IDE
+```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- **Particle.io** - Excellent IoT platform and community
+- **Traefik Labs** - Outstanding reverse proxy solution
+- **Let's Encrypt** - Free SSL certificates for everyone
+- **Security Community** - Best practices and threat modeling
+
+## 📞 Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/security-device-system/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/security-device-system/discussions)
+- **Security**: [security@yourdomain.com](mailto:security@yourdomain.com)
+
+---
+
+**⚠️ Disclaimer**: This system is designed for property protection and deterrent purposes. It should not be relied upon as the sole security measure for critical applications. Always follow local laws and regulations regarding security devices and notifications.
\ No newline at end of file