# 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<br/>Basic API & Single Session]
    end

    subgraph Phase2["Phase 2"]
        V002[v0.0.2 - Production Ready<br/>Multi-session & Dashboard]
    end

    subgraph Stable["✅ Released"]
        V010[v0.1.0 - Initial Stable Release<br/>All Core Features]
        V020[v0.2.0 - i18n, Real-time Chats,<br/>Webhook Delivery-state & Hardening]
    end

    subgraph v0.x["✅ Released (v0.3–v0.4)"]
        V030[v0.3.0 - Engine Pluggability<br/>Baileys engine + plugin layer]
        V040[v0.4.0 - Single-Port Deployment<br/>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 |

---

<div align="center">

[← 14 - Migration Guide](./14-migration-guide.md) · [Documentation Index](./README.md) · [Next: 16 - Risk Management →](./16-risk-management.md)

</div>
