Skip to content

01-project-overview.md

Latest commit

 

History

History
297 lines (240 loc) · 8.46 KB

01-project-overview.md

File metadata and controls

297 lines (240 loc) · 8.46 KB

01 - Project Overview

1.1 Executive Summary

OpenWA is an open-source platform that provides an HTTP API for WhatsApp integration. This project is built as a free and fully open-source alternative to paid solutions such as WAHA Plus.

Core Values

┌─────────────────────────────────────────────────────────────┐
│                      OpenWA Values                          │
├─────────────────────────────────────────────────────────────┤
│  🆓 100% Free         │  No paywalled features               │
│  📖 Open Source       │  MIT License, fork friendly          │
│  🔒 Self-Hosted       │  Data stays on your own server       │
│  🚀 Production Ready  │  Scalable & reliable                 │
│  🎯 Developer First   │  Simple, intuitive API               │
└─────────────────────────────────────────────────────────────┘

1.2 Vision & Mission

Vision

To become the most reliable open-source WhatsApp API gateway for production use.

Mission

  1. Provide a complete and free WhatsApp REST API
  2. Build an active open-source community
  3. Deliver excellent documentation and tooling
  4. Ensure user data security and privacy

1.3 Problem Statement

flowchart LR
    subgraph Problems["❌ Current Problems"]
        P1[Existing solutions are paid]
        P2[Critical features are paywalled]
        P3[Vendor lock-in]
        P4[Data privacy concerns]
    end
    
    subgraph Solution["✅ OpenWA Solution"]
        S1[100% Free & Open Source]
        S2[All features included]
        S3[Self-hosted, no lock-in]
        S4[Data stays on your server]
    end
    
    P1 --> S1
    P2 --> S2
    P3 --> S3
    P4 --> S4
Loading

Pain Points Addressed

Pain Point OpenWA Solution
WAHA Plus charges for multi-session Free unlimited multi-session
Dashboard only in paid tiers Free dashboard
PostgreSQL support is paid PostgreSQL included
Limited webhook management Full webhook management
No source code access Full source code available

1.4 Project Goals

Primary Goals

mindmap
  root((OpenWA Goals))
    Functional
      Complete REST API
      Multi-session
      Webhook support
      Media handling
    Technical
      High performance
      Scalable
      Secure
      Well documented
    Community
      Active contributors
      Strong documentation
      Example projects
      Support forum
Loading

Success Metrics

Metric Target (6 months) Target (1 year)
GitHub Stars 500+ 2000+
Active Contributors 10+ 30+
Docker Pulls 5,000+ 20,000+
Production Users 100+ 500+
API Uptime 99.5% 99.9%

1.5 Project Scope

In Scope ✅

Phase 1 (MVP)
├── REST API
│   ├── Session management (create, delete, status)
│   ├── QR code authentication
│   ├── Send messages (text, image, video, audio, document)
│   ├── Receive messages via webhook
│   ├── Contact management
│   └── Basic group operations
├── Infrastructure
│   ├── Docker support
│   ├── SQLite database
│   ├── Swagger documentation
│   └── Health check endpoints
└── Documentation
    ├── API documentation
    ├── Setup guide
    └── Basic examples

Phase 2 (Production Ready)
├── Multi-session support
├── PostgreSQL support
├── Web Dashboard
├── Webhook management UI
├── Message queue (Redis/Bull)
├── Rate limiting
└── Authentication (API Key)

Phase 3 (Advanced)
├── Group management (create, modify, participants)
├── Channels/Newsletter support
├── Label management
├── Status/Stories
├── Proxy per session
├── Horizontal scaling
└── Metrics & monitoring

Out of Scope ❌

  • WhatsApp Business API (official Meta API)
  • Mobile app
  • End-user chat interface
  • Message scheduling (to be a separate plugin)
  • CRM features
  • Billing/payment integration

1.6 Stakeholders

flowchart TB
    subgraph Primary["Primary Stakeholders"]
        D[Developers]
        B[Small Businesses]
        S[Startups]
    end
    
    subgraph Secondary["Secondary Stakeholders"]
        C[Community Contributors]
        I[Integration Partners]
        O[Open Source Community]
    end
    
    subgraph Users["End Users"]
        U1[Self-hosted Users]
        U2[Docker Users]
        U3[Cloud Deploy Users]
    end
    
    Primary --> Users
    Secondary --> Primary
Loading

Target Users

  1. Developers - Need WhatsApp integration for their applications
  2. Small Businesses - Need customer service automation
  3. Startups - Need cost-effective solutions
  4. Agencies - Manage multiple WhatsApp accounts

1.7 Competitive Analysis

quadrantChart
    title Feature vs Cost Comparison
    x-axis Low Cost --> High Cost
    y-axis Basic Features --> Advanced Features
    quadrant-1 Premium Solutions
    quadrant-2 Our Target
    quadrant-3 Limited Free
    quadrant-4 Expensive Basic
    
    WAHA Plus: [0.7, 0.8]
    WAHA Core: [0.2, 0.4]
    Whapi.cloud: [0.8, 0.75]
    Green API: [0.6, 0.6]
    OpenWA: [0.1, 0.85]
Loading

Feature Comparison

Feature OpenWA WAHA Core WAHA Plus Whapi.cloud
Price Free Free $50+/mo $30+/mo
Open Source ✅ ❌ ❌ ❌
Multi-session ✅ Limited ✅ ✅
Dashboard ✅ ❌ ✅ ✅
PostgreSQL ✅ ❌ ✅ N/A
Webhook UI ✅ ❌ ✅ ✅
Self-hosted ✅ ✅ ✅ ❌
Source code ✅ ❌ ❌ ❌

1.8 Technology Decisions

Why These Technologies?

flowchart TB
    subgraph Runtime["Runtime & Framework"]
        N[Node.js 20 LTS] --> |"TypeScript support, async/await"| NE[NestJS]
        NE --> |"Modular, scalable, DI"| API[REST API]
    end
    
    subgraph Engine["WhatsApp Engine"]
        WW[whatsapp-web.js] --> |"Puppeteer based"| P[More stealth]
        P --> |"Real browser fingerprint"| S[Lower ban risk]
    end
    
    subgraph Storage["Data Storage"]
        SQ[SQLite] --> |"Development"| DEV[Easy setup]
        PG[PostgreSQL] --> |"Production"| PROD[Scalable]
    end
    
    subgraph Frontend["Dashboard"]
        R[React] --> V[Vite]
        V --> S[shadcn/ui]
        S --> L[Lucide Icons]
        L --> UI[Modern UI]
    end
Loading

Technology Stack Summary

Layer Technology Rationale
Runtime Node.js 20 LTS Stable, long-term support
Language TypeScript Type safety, better developer experience
Framework NestJS Enterprise-grade, modular
WA Engine whatsapp-web.js Mature, active community
Browser Puppeteer/Chrome Real browser, stealth
Database SQLite (default) / PostgreSQL Zero-config default, PostgreSQL for scaling
Cache Redis Fast, pub/sub support
Queue Bull Reliable job processing
Dashboard React + Vite Fast, modern
Styling Tailwind CSS Utility-first CSS
UI Components shadcn/ui + Lucide Accessible, polished
Container Docker Portable, consistent

1.9 Constraints & Assumptions

Constraints

  1. Technical

    • WhatsApp Web protocol can change at any time
    • Puppeteer requires significant resources (~300-500MB RAM per session)
    • WhatsApp rate limiting

  2. Legal

    • Unofficial API, not affiliated with Meta
    • Users are responsible for compliant usage

  3. Resource

    • Open-source project, dependent on community contributions
    • Limited maintainer capacity initially

Assumptions

  1. Users have servers with at least 2GB RAM
  2. Users are familiar with Docker or Node.js
  3. Users understand the risks of using an unofficial API
  4. WhatsApp Web will remain available

1.10 Document History

Version Date Author Changes
1.0 2026-02-02 Team Initial document