docs: restructure README with architecture, security model, and roadmap ALL TESTS PASS

README.md

@@ -1,13 +1,21 @@
 # Task WhatsApp Chatbot
 
-## Future Steps
+A WhatsApp chatbot for task management, designed to work with Evolution API in a secure internal network environment.
 
-### Core Principles
+## 📌 Overview
-1. **Trust-but-Verify Approach**: Leverage WhatsApp's message metadata to minimize API calls while maintaining security
+This service provides a WhatsApp interface for task management within WhatsApp groups. It:
-2. **Progressive Validation**: Verify users naturally through interactions rather than upfront checks
+- Listens for `/tarea` commands in WhatsApp groups
-3. **Background Reconciliation**: Use periodic syncs to maintain data accuracy without impacting real-time performance
+- Stores tasks in a SQLite database
+- Manages user permissions and group membership
+- Integrates with Evolution API for WhatsApp connectivity
 
-### Message Processing Flow
+## 🔐 Security Model
+- **Internal Networking**: The webhook only accepts connections from Evolution API via internal Docker networking
+- **Environment Variables**: Sensitive configuration is managed through environment variables
+- **Group Restrictions**: Only operates within pre-approved WhatsApp groups
+- **Input Validation**: Sanitizes and validates all user inputs
+
+## 🧱 Architecture
 ```mermaid
 graph TD
     A[Webhook Received] --> B{Valid Payload?}
@@ -24,25 +32,77 @@ graph TD
     H -->|No| J[Process Command]
 ```
 
-### Alias for actions
+## ✅ Current Features
-
+- Task creation with optional due dates
-- I want that, when an user sends `/tarea` to the bot, with no extra arguments, it should show all the pending tasks for the user in a private message (the same behaviour as calling `/tarea mostrar`
+- Basic command parsing (`/tarea nueva`, `/tarea mostrar`)
-
+- Group membership tracking
-### Periodic Sync Strategy
+- SQLite database persistence
-1. **Rotating Group Check**:
+- Health check endpoint
-   - Verify 1-2 groups per sync cycle
+- Environment validation
-   - Prioritize recently active groups
+- Input validation for dates and commands
-2. **User Reconciliation**:
+
-   - Add newly discovered users
+## 🛠️ Setup
-   - Update `last_confirmed` for active users
+### Environment Variables
-3. **Optimizations**:
+```env
-   - Cache active group IDs in memory
+EVOLUTION_API_URL=http://evolution-api:3000
-   - Batch database writes
+EVOLUTION_API_KEY=your-api-key
-   - Exponential backoff for API failures
+EVOLUTION_API_INSTANCE=main
-
+WHATSAPP_COMMUNITY_ID=your-community-id
-### Security Considerations
+CHATBOT_PHONE_NUMBER=1234567890
-- Reject messages from:
+WEBHOOK_URL=https://your-webhook.com
-  - Non-community groups
+PORT=3007
-  - Unknown private chats
+NODE_ENV=production
-- Implement rate limiting
+```
-- Maintain audit logs of verification events
+
+### Development Setup
+```bash
+# Install dependencies
+bun install
+
+# Start development server
+bun run dev
+
+# Run tests
+bun test
+```
+
+## 📅 Roadmap
+### High Priority
+- [ ] Implement ResponseQueue processing logic with retries
+- [ ] Add database schema validation and migrations
+- [ ] Add error recovery with transaction rollback
+- [ ] Implement group sync delta updates
+
+### Medium Priority
+- [ ] Add task assignment and ownership
+- [ ] Implement user permissions system
+- [ ] Add rate limiting for API calls
+- [ ] Create task history tracking
+
+### Low Priority
+- [ ] Add task reminders system
+- [ ] Implement multi-language support
+- [ ] Create analytics dashboard
+- [ ] Add user-friendly task list UI
+
+## 🧪 Testing
+### Running Tests
+```bash
+bun test
+```
+
+### Test Coverage
+- Webhook validation
+- Command parsing
+- Environment checks
+- Basic error handling
+- Input validation
+
+## 🧑‍💻 Contributing
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Submit a pull request
+
+## 📚 Documentation
+For detailed API documentation and architecture decisions, see the [docs/](docs/) directory.