# 15 - Project Roadmap ## 15.1 Release Strategy ```mermaid timeline title OpenWA Release Timeline section v0.0.1 - MVP Month 1-3 : Foundation & Engine : Basic API : Single session : Docker ready section v0.0.2 - Production Ready Month 4-6 : Multi-session support : Web Dashboard : Security & Queue : PostgreSQL section v0.1.0 - Initial Stable Release Month 7-9 : Full feature parity : Groups & Channels : Community tools : Stable release section v0.2.0 - i18n, Real-time & Hardening (Released) Jun 2026 : Multi-locale dashboard (i18n) : Real-time Chats view : Webhook delivery-state & templates : Security & container hardening section v0.3.0 - Engine Pluggability & Plugins (Released) Jun 2026 : Baileys engine (browser-free) : Pluggable ENGINE_TYPE env var : Plugin capability layer section v0.4.0 - Single-Port Deployment (Released) Jun 2026 : Dashboard served from API port : Bundled Traefik removed : Bring-your-own reverse proxy section v1.0.0 - Enterprise 2027 : Kubernetes Operator : Multi-tenant ``` ### Release Summary | Version | Focus | Status | | ------- | ---------------------------------------------------------- | ----------- | | v0.0.1 | MVP - Basic API | ✅ Released | | v0.0.2 | Production Ready | ✅ Released | | v0.1.0 | Initial Stable Release | ✅ Released | | v0.1.7 | Maintenance & fixes | ✅ Released | | v0.1.8 | Maintenance & fixes | ✅ Released | | v0.2.0 | i18n, Real-time Chats & Hardening | ✅ Released | | v0.2.1 | Dashboard split-origin fix | ✅ Released | | v0.2.2 | Security hardening (SSRF, secrets, Prometheus metrics) | ✅ Released | | v0.2.3 | Plain-HTTP / LAN dashboard fixes | ✅ Released | | v0.2.4 | CORS LAN fix, pinnable WA-Web version | ✅ Released | | v0.2.5 | Pairing-code linking | ✅ Released | | v0.2.6 | Chromium hardened-container (read-only) fix | ✅ Released | | v0.2.7 | Typing simulation, delete-chat, engine-agnostic groundwork | ✅ Released | | v0.2.8 | Engine decoupling (ack/type/JID), templates, @lid→phone | ✅ Released | | v0.2.9 | Reliability/security/a11y hardening (RBAC, deps, shutdown, retention) | ✅ Released | | v0.2.10 | Dashboard/CI follow-ups (MessageTester JID, neutral MessageType, qemu v4) | ✅ Released | | v0.3.0 | Engine pluggability (Baileys engine, plugin layer) | ✅ Released | | v0.4.0 | Single-port deployment (dashboard on API port, Traefik removed) | ✅ Released | | v1.0.0 | Enterprise Ready (K8s Operator, multi-tenant) | 📋 Planned | > SDK / docs-site / observability features (Node & Python SDK, Postman collection, Grafana, OpenTelemetry) > are delivered **incrementally** in `0.2.x`/`0.3.x` as they're additive — they no longer gate a single > version. The version **number** follows SemVer (see §15.2), not the theme. ### Risk Buffer Each phase includes a 2–3 week buffer for: - Bug fixing and stabilization - WhatsApp protocol changes - Community feedback integration - Documentation updates ### Prerequisites & Resources | Requirement | Details | | ------------------ | --------------------------------------------------------- | | **Development** | 1-2 full-time developers (or equivalent part-time) | | **Environment** | Node.js 22 LTS, Docker, Git | | **Testing** | WhatsApp test accounts (2-3 numbers) | | **Infrastructure** | VPS for staging (2GB RAM minimum) | | **Accounts** | GitHub organization, npm registry access, Docker Hub/GHCR | ## 15.2 Version Numbering ``` MAJOR.MINOR.PATCH MAJOR: Breaking changes MINOR: New features (backward compatible) PATCH: Bug fixes Examples: 0.0.1 - Initial MVP 0.0.2 - Production Ready (Multi-session, Dashboard) 0.1.0 - Initial Stable Release (Full features) 0.1.1 - Bug fix for QR timeout 0.2.0 - i18n, Real-time Chats, Webhook Delivery-state & Hardening 0.3.0 - SDK & Developer Tools 1.0.0 - Enterprise Ready 2.0.0 - Breaking API changes ``` ### Pre-1.0 policy (we are here) While the project is on `0.x`, a `1.0.0`/`2.0.0` bump for every breaking change isn't appropriate, so we follow the SemVer "major version zero" convention: - **PATCH (`0.2.x`)** — bug fixes **and** backward-compatible additions (new endpoints, optional fields, new opt-in features). The default for ongoing work. - **MINOR (`0.3.0`, `0.4.0`, …)** — **breaking changes** (removed/renamed fields, changed payload semantics, deployment-topology changes). A breaking change does **not** stay in `0.2.x`. - Every breaking change ships with a prominent **⚠️ callout + migration note** in the CHANGELOG and the GitHub release, because the version number alone won't fully signal it pre-1.0. > Note: `0.2.8` shipped one breaking change (webhook `type` neutralization, #270) as a patch — that > predates this policy and is documented with a migration note; the policy applies from `0.2.9` onward. ## 15.3 Phase 1: MVP (Month 1-3) ### Goals - Working single-session API - Basic send/receive functionality - Docker deployment ready - Stable WhatsApp connection ### Milestones ```mermaid gantt title Phase 1 - MVP (12 weeks) dateFormat X axisFormat Week %W section Foundation (Week 1-2) Project setup :done, p1-1, 0, 5d Database schema :done, p1-2, after p1-1, 3d Basic NestJS structure :done, p1-3, after p1-2, 4d section WhatsApp Engine (Week 3-5) Engine abstraction layer :p1-4, after p1-3, 3d whatsapp-web.js wrapper :p1-5, after p1-4, 7d Connection management :p1-6, after p1-5, 4d QR code handling :p1-7, after p1-6, 3d section Session (Week 6-7) Session entity & CRUD :p1-8, after p1-7, 4d Session persistence :p1-9, after p1-8, 4d Auto-reconnect logic :p1-10, after p1-9, 3d section Messaging (Week 8-9) Send text message :p1-11, after p1-10, 3d Send image :p1-12, after p1-11, 2d Send video/audio :p1-13, after p1-12, 3d Send document :p1-14, after p1-13, 2d section Webhook (Week 10) Receive messages event :p1-15, after p1-14, 2d Webhook delivery :p1-16, after p1-15, 3d Retry mechanism :p1-17, after p1-16, 2d section Infrastructure (Week 10-11) Docker setup :p1-18, after p1-3, 3d CI/CD pipeline :p1-18b, after p1-18, 3d Swagger documentation :p1-19, after p1-17, 2d Health endpoints :p1-20, after p1-19, 1d Basic logging :p1-21, after p1-20, 2d section Stabilization (Week 12) Integration testing :p1-22, after p1-21, 3d Bug fixes :p1-23, after p1-22, 3d Documentation :p1-24, after p1-23, 2d v0.0.1 Release :milestone, p1-25, after p1-24, 0d ``` ### Complexity Notes ```mermaid flowchart TB subgraph HighRisk["⚠️ High Complexity Areas"] WW[whatsapp-web.js Integration] RC[Reconnection Logic] QR[QR Code Lifecycle] end subgraph MediumRisk["⚡ Medium Complexity"] WH[Webhook Reliability] MD[Media Handling] end subgraph LowRisk["✅ Low Complexity"] CRUD[Basic CRUD APIs] DOC[Documentation] DOCKER[Docker Setup] end ``` | Area | Complexity | Time Buffer | | --------------------------- | ---------- | ----------- | | whatsapp-web.js integration | High | +1 week | | Connection stability | High | +1 week | | Media handling | Medium | +3 days | | Webhook delivery | Medium | +3 days | ### v0.0.1 Features > **Note:** Phase 1 release - MVP with core API functionality. #### Core API & Session Management | Feature | Priority | Status | | ------------------ | -------- | ------ | | Create session | P0 | ✅ | | Delete session | P0 | ✅ | | Get session status | P0 | ✅ | | Generate QR code | P0 | ✅ | | Session reconnect | P1 | ✅ | #### Basic Messaging | Feature | Priority | Status | | ----------------- | -------- | ------ | | Send text message | P0 | ✅ | | Send image | P0 | ✅ | | Send video | P1 | ✅ | | Send audio | P1 | ✅ | | Send document | P1 | ✅ | | Receive messages | P0 | ✅ | #### Basic Webhooks | Feature | Priority | Status | | ---------------- | -------- | ------ | | Webhook delivery | P0 | ✅ | | Webhook retry | P0 | ✅ | #### Infrastructure | Feature | Priority | Status | | -------------- | -------- | ------ | | SQLite storage | P0 | ✅ | | Docker support | P0 | ✅ | | Health check | P1 | ✅ | | Swagger docs | P0 | ✅ | ### Deliverables ``` v0.0.1 Release Package: ├── Docker image (ghcr.io/rmyndharis/openwa:0.0.1) ├── docker-compose.yml ├── Basic API documentation (Swagger) ├── README with quick start ├── Single session example └── CI/CD workflows (GitHub Actions) ├── Build & test pipeline └── Docker image build ``` ## 15.4 Phase 2: Production Ready (Month 4-6) ### Goals - Multi-session support - Web dashboard - Production-grade security - Database scalability ### Milestones ```mermaid gantt title Phase 2 - Production Ready (12 weeks) dateFormat X axisFormat Week %W section Multi-session (Week 1-3) Session manager redesign :p2-1, 0, 5d Memory management :p2-2, after p2-1, 4d Concurrent sessions :p2-3, after p2-2, 4d Session isolation :p2-4, after p2-3, 3d Resource quotas :p2-5, after p2-4, 3d section Database (Week 4-5) PostgreSQL adapter :p2-6, 0, 4d Migration system :p2-7, after p2-6, 3d Connection pooling :p2-8, after p2-7, 2d Table partitioning :p2-9, after p2-8, 3d section Security (Week 5-7) API key system :p2-10, after p2-5, 4d Permission model :p2-11, after p2-10, 3d Rate limiting :p2-12, after p2-11, 3d IP whitelisting :p2-13, after p2-12, 2d Audit logging :p2-14, after p2-13, 3d section Queue System (Week 6-7) Redis integration :p2-15, after p2-9, 3d Bull queue setup :p2-16, after p2-15, 3d Webhook queue :p2-17, after p2-16, 2d Message queue :p2-18, after p2-17, 2d section Dashboard (Week 8-10) React + shadcn/ui setup :p2-19, after p2-18, 3d Authentication UI :p2-20, after p2-19, 3d Session management :p2-21, after p2-20, 4d QR code display :p2-22, after p2-21, 2d Webhook management :p2-23, after p2-22, 4d Logs viewer :p2-24, after p2-23, 3d Test message sender :p2-25, after p2-24, 2d section Stabilization (Week 11-12) Load testing :p2-26, after p2-25, 3d Security audit :p2-27, after p2-26, 3d Performance tuning :p2-28, after p2-27, 3d v0.0.2 Release :milestone, p2-29, after p2-28, 0d ``` ### v0.0.2 Features > **Note:** Phase 2 release - Production Ready with multi-session, dashboard, and security. #### Multi-Session & Database | Feature | Priority | Status | | ------------------ | -------- | ------ | | Multi-session | P0 | ✅ | | Session isolation | P0 | ✅ | | Proxy per session | P1 | ✅ | | PostgreSQL support | P0 | ✅ | | Redis cache | P1 | ✅ | | Job queue (Bull) | P1 | ✅ | | Connection pooling | P1 | ✅ | #### Security & Auth | Feature | Priority | Status | | ---------------------- | -------- | ------ | | API key authentication | P0 | ✅ | | Rate limiting | P0 | ✅ | | Permission system | P1 | ✅ | | IP whitelisting | P2 | ✅ | | Audit logging | P2 | ✅ | #### Dashboard | Feature | Priority | Status | | --------------------- | -------- | ------ | | Web dashboard | P0 | ✅ | | Session management UI | P0 | ✅ | | QR code display | P0 | ✅ | | Webhook management UI | P1 | ✅ | | Logs viewer | P1 | ✅ | | Test message sender | P2 | ✅ | ### Deliverables ``` v0.0.2 Release Package: ├── Docker image (ghcr.io/rmyndharis/openwa:0.0.2) ├── docker-compose.yml (with PostgreSQL & Redis) ├── Web Dashboard ├── API authentication (API keys) ├── Enhanced API documentation ├── Multi-session examples └── Production deployment guide ``` ## 15.5 Phase 3: Advanced Features (Month 7-9) ### Goals - Complete feature parity with WAHA Plus - Stable v0.1.0 release - Community adoption ### Milestones ```mermaid gantt title Phase 3 - Advanced Features (12 weeks) dateFormat X axisFormat Week %W section Groups (Week 1-2) Get groups list :p3-1, 0, 2d Group info & members :p3-2, after p3-1, 2d Create group :p3-3, after p3-2, 2d Manage participants :p3-4, after p3-3, 3d Group settings :p3-5, after p3-4, 2d section Channels (Week 3-4) Channel list :p3-6, 0, 2d Channel messages :p3-7, after p3-6, 3d Create channel :p3-8, after p3-7, 2d section Advanced Messages (Week 5-6) Send location :p3-9, after p3-5, 1d Send contact :p3-10, after p3-9, 1d Send sticker :p3-11, after p3-10, 2d Message reactions :p3-12, after p3-11, 1d Reply to message :p3-13, after p3-12, 1d Forward message :p3-14, after p3-13, 1d section Scaling (Week 7-8) Horizontal scaling docs :p3-15, after p3-8, 3d Session affinity :p3-16, after p3-15, 2d Load testing :p3-17, after p3-16, 2d section Community (Week 9-10) n8n community node :p3-18, after p3-17, 3d Example projects :p3-19, after p3-18, 2d Video tutorials :p3-20, after p3-19, 3d section Release (Week 11-12) Security audit :p3-21, after p3-20, 3d Performance tuning :p3-22, after p3-21, 2d v0.1.0 Release :milestone, p3-23, after p3-22, 0d ``` ### v0.1.0 Features > **Note:** Phase 3 release - Initial Stable Release with full feature parity. #### Advanced Messaging | Feature | Priority | Status | | ----------------- | -------- | ------ | | Send location | P1 | ✅ | | Send contact | P1 | ✅ | | Send sticker | P2 | ✅ | | Message reactions | P2 | ✅ | | Reply to message | P1 | ✅ | | Forward message | P1 | ✅ | | Message history | P2 | ✅ | #### Groups, Channels & Contacts | Feature | Priority | Status | | ------------------- | -------- | ------ | | Groups API (full) | P0 | ✅ | | Channels/Newsletter | P1 | ✅ | | Labels management | P2 | ✅ | | Contact list API | P1 | ✅ | #### Scaling & Infrastructure | Feature | Priority | Status | | ------------------ | -------- | ------ | | Horizontal scaling | P2 | ✅ | | Session affinity | P2 | ✅ | | Security audit | P0 | ✅ | #### Community & Tooling | Feature | Priority | Status | | --------------- | -------- | ------------------ | | n8n integration | P1 | ✅ (separate repo) | | CI/CD pipeline | P0 | ✅ | ### Deliverables ``` v0.1.0 Release Package: ├── Docker image (ghcr.io/rmyndharis/openwa:0.1.0) ├── docker-compose.yml (production ready) ├── Full-featured Web Dashboard ├── Complete API documentation (Swagger) ├── README with comprehensive guide ├── Integration examples │ ├── n8n community node │ └── Basic automation examples └── CI/CD workflows (GitHub Actions) ├── Build & test pipeline ├── Docker image build & push └── Release automation ``` ## 15.6 Future Roadmap (v0.3.0+) > **Note:** Version 0.1.0 is the initial stable release including all features from Phases 1-3. > Versions 0.1.7 through 0.4.6 have since shipped (see the CHANGELOG); v1.0.0 > onward is forward-looking. ```mermaid flowchart LR subgraph Phase1["Phase 1"] V001[v0.0.1 - MVP
Basic API & Single Session] end subgraph Phase2["Phase 2"] V002[v0.0.2 - Production Ready
Multi-session & Dashboard] end subgraph Stable["✅ Released"] V010[v0.1.0 - Initial Stable Release
All Core Features] V020[v0.2.0 - i18n, Real-time Chats,
Webhook Delivery-state & Hardening] end subgraph v0.x["✅ Released (v0.3–v0.4)"] V030[v0.3.0 - Engine Pluggability
Baileys engine + plugin layer] V040[v0.4.0 - Single-Port Deployment
Dashboard on API port, no bundled Traefik] end subgraph v1.x["v1.x Series - Enterprise"] V10[v1.0.0 - Enterprise Ready] end Phase1 --> Phase2 --> Stable --> v0.x --> v1.x ``` ### v0.2.0 - i18n, Real-time Chats, Webhook Delivery-state & Hardening (Released) | Feature | Priority | Status | | -------------------------------- | -------- | ------ | | Multi-locale dashboard (i18n) | P1 | ✅ | | Real-time Chats view (WebSocket) | P1 | ✅ | | Message templates | P1 | ✅ | | Webhook delivery-state tracking | P1 | ✅ | | Security & API surface hardening | P0 | ✅ | | Container / Podman hardening | P1 | ✅ | ### v0.3.0 — Engine pluggability & plugin layer (Released) `0.3.0` shipped as a **breaking** release (per §15.2). It introduced a pluggable engine layer (`ENGINE_TYPE` env var: `whatsapp-web.js` default or `baileys` for a browser-free alternative loaded lazily), moved Puppeteer/browser config out of the neutral engine contract (#265), and added a Tier-2 plugin capability layer (`ctx.messages` / `ctx.engine`; `PluginContext.getService` removed). Ships with a migration guide. ### v0.4.0 — Single-port deployment (Released) `0.4.0` shipped as a **breaking** release. The dashboard SPA is now served directly from the API on its own port (default `:2785`) via `@nestjs/serve-static`; the bundled Traefik service is removed (#275, #276). Use your own reverse proxy (nginx, Caddy, a cloud load balancer) for TLS/public exposure. `SERVE_DASHBOARD=false` opts out. The `DASHBOARD_PORT`, `PROXY_ENABLED`, and `DASHBOARD_ENABLED` env vars are removed. Ships with a migration guide. #### Incremental themes — SDK, Developer Tools & Observability Delivered additively whenever ready (so they land in `0.2.x`/`0.3.x` per SemVer, not gated to one version): | Feature | Priority | Description | | ---------------------- | -------- | ------------------------------- | | JavaScript/Node.js SDK | P1 | Official client library | | Python SDK | P2 | Python client library | | Docs Site | P1 | Documentation website | | Postman Collection | P1 | Ready-to-use API collection | | Video Tutorials | P2 | Getting started video series | | Example Projects | P1 | Real-world integration examples | **Performance & Observability** | Feature | Priority | Description | | ---------------------- | -------- | -------------------------------- | | Prometheus Metrics | P1 | /metrics endpoint for monitoring | | Grafana Dashboard | P2 | Pre-built monitoring dashboard | | OpenTelemetry Tracing | P2 | Distributed tracing support | | Performance Benchmarks | P1 | Documented performance metrics | | Memory Optimization | P1 | Reduced memory per session | ### v1.0.0 - Enterprise Ready | Feature | Priority | Description | | ------------------- | -------- | ------------------------------ | | Kubernetes Operator | P3 | Native K8s deployment | | Multi-tenant | P3 | Enterprise SaaS features | | Encryption at rest | P2 | Full data encryption | | Audit compliance | P2 | SOC2, GDPR compliance | | WhatsApp Pay | P3 | Payment links integration | ## 15.7 Release Checklist ### Pre-Release ```markdown ## Pre-Release Checklist ### Code Quality - [ ] All tests passing - [ ] Code coverage meeting target (v0.1.0: minimal, future: > 80%) - [ ] No critical linter warnings - [ ] Security scan passed - [ ] Dependency audit clean ### Documentation - [ ] API docs updated - [ ] CHANGELOG updated - [ ] README updated - [ ] Migration guide (if breaking) ### Testing - [ ] Manual QA completed - [ ] Performance benchmarks - [ ] Load testing (if applicable) - [ ] Rollback tested ### Infrastructure - [ ] Docker image builds - [ ] Docker Compose tested - [ ] Environment variables documented ``` ### Release Process ```mermaid flowchart TB A[Feature Complete] --> B[Create Release Branch] B --> C[Version Bump] C --> D[Update CHANGELOG] D --> E[Final Testing] E --> F{Tests Pass?} F -->|No| G[Fix Issues] G --> E F -->|Yes| H[Create PR to main] H --> I[Code Review] I --> J[Merge to main] J --> K[Create Git Tag] K --> L[Build & Push Docker] L --> M[Create GitHub Release] M --> N[Announce Release] ``` ## 15.8 Success Metrics ### Phase 1 Success Criteria | Metric | Target | Type | | -------------------------- | --------- | -------- | | Core API endpoints working | 100% | Internal | | Docker deployment works | ✅ | Internal | | Single session stable | 24+ hours | Internal | | Message delivery rate | > 95% | Internal | | API response time | < 500ms | Internal | | CI/CD pipeline operational | ✅ | Internal | ### Phase 2 Success Criteria | Metric | Target | Actual | Type | | --------------------- | ------------ | ----------------- | -------- | | Multi-session support | 10+ sessions | ✅ Achieved | Internal | | Dashboard functional | All features | ✅ Achieved | Internal | | PostgreSQL stable | ✅ | ✅ Achieved | Internal | | Webhook delivery rate | > 99% | ✅ Achieved | Internal | | Test coverage | > 70% | ⚠️ ~5% (deferred) | Internal | | GitHub stars | 100+ | 📋 Pending | External | ### Phase 3 Success Criteria | Metric | Target | Actual | Type | | ----------------------------- | ------- | ----------------- | -------- | | Feature parity with WAHA Plus | 90%+ | ✅ Achieved | Internal | | API response time (p95) | < 200ms | ✅ Achieved | Internal | | Test coverage | > 80% | ⚠️ ~5% (deferred) | Internal | | Documentation coverage | 100% | ✅ 95%+ | Internal | | Production users | 50+ | 📋 Pending | External | | GitHub stars | 500+ | 📋 Pending | External | | Community contributors | 5+ | 📋 Pending | External | ---
[← 14 - Migration Guide](./14-migration-guide.md) · [Documentation Index](./README.md) · [Next: 16 - Risk Management →](./16-risk-management.md)