Skip to content

02-requirements-specification.md

Latest commit

 

History

History
492 lines (412 loc) · 16.8 KB

02-requirements-specification.md

File metadata and controls

492 lines (412 loc) · 16.8 KB

02 - Requirements Specification

2.1 Overview

This document defines the functional and non-functional requirements for OpenWA.

2.2 Functional Requirements

2.2.1 Session Management

flowchart LR
    subgraph Session["Session Lifecycle"]
        C[Create] --> A[Authenticate]
        A --> |QR Scan| R[Ready]
        R --> |Logout| D[Destroy]
        R --> |Disconnect| RC[Reconnect]
        RC --> R
    end
Loading
ID Requirement Priority Phase
FR-SM-001 The system must create new sessions High 1
FR-SM-002 The system must generate a QR code for authentication High 1
FR-SM-003 The system must persist session state for reconnection High 1
FR-SM-004 The system must delete a session High 1
FR-SM-005 The system must display session status High 1
FR-SM-006 The system must support multiple sessions High 2
FR-SM-007 The system must auto-reconnect when the connection is lost Medium 2
FR-SM-008 The system must support session naming Low 2

2.2.2 Messaging

flowchart TB
    subgraph Outbound["Outbound Messages"]
        T[Text] 
        I[Image]
        V[Video]
        A[Audio]
        D[Document]
        L[Location]
        CT[Contact]
        S[Sticker]
    end
    
    subgraph Inbound["Inbound Messages"]
        W[Webhook] --> P[Process]
        P --> ACK[Acknowledgment]
    end
    
    Outbound --> API[REST API]
    API --> WA[WhatsApp]
    WA --> Inbound
Loading
ID Requirement Priority Phase
FR-MSG-001 The system must send text messages High 1
FR-MSG-002 The system must send images with captions High 1
FR-MSG-003 The system must send video messages High 1
FR-MSG-004 The system must send audio/voice notes High 1
FR-MSG-005 The system must send documents/files High 1
FR-MSG-006 The system must send locations Medium 2
FR-MSG-007 The system must send contact cards Medium 2
FR-MSG-008 The system must send stickers Medium 2
FR-MSG-009 The system must reply to a message Medium 2
FR-MSG-010 The system must forward messages Low 3
FR-MSG-011 The system must delete messages Low 3
FR-MSG-012 The system must react to messages Low 3
FR-MSG-013 The system must send bulk messages (batch) Medium 2
FR-MSG-014 The system must support template variables in bulk messages Medium 2
FR-MSG-015 The system must track status per message in a batch Medium 2
FR-MSG-016 The system must cancel a running batch Medium 2
FR-MSG-017 The system must apply delays between messages to reduce ban risk High 2
FR-MSG-018 The system must validate media size before sending High 1
FR-MSG-019 The system must support downloading media from a URL High 1

2.2.3 Webhook & Events

sequenceDiagram
    participant WA as WhatsApp
    participant OW as OpenWA
    participant WH as Webhook URL
    
    WA->>OW: New Message Event
    OW->>OW: Process & Store
    OW->>WH: POST /webhook
    WH-->>OW: 200 OK
    
    alt Webhook Failed
        OW->>OW: Queue for Retry
        OW->>WH: Retry (max 3x)
    end
Loading
ID Requirement Priority Phase
FR-WH-001 The system must deliver events to webhook URLs High 1
FR-WH-002 The system must support multiple webhook URLs Medium 2
FR-WH-003 The system must retry failed webhooks (max 3x) Medium 2
FR-WH-004 The system must filter event types per webhook Medium 2
FR-WH-005 The system must log webhook delivery status Medium 2
FR-WH-006 The system must support webhook signature verification Medium 2
FR-WH-007 The system must provide an idempotency key per event High 2
FR-WH-008 The system must provide a delivery ID to track retries Medium 2
FR-WH-009 The system must support exponential backoff for retries Medium 2
FR-WH-010 The system must enable/disable webhooks without deletion Low 2

2.2.4 Real-time Updates (WebSocket)

flowchart LR
    subgraph WebSocket["WebSocket Features"]
        direction TB
        CONN[Connection Management]
        AUTH[Authentication]
        SUB[Event Subscription]
        PING[Keep-alive Ping/Pong]
    end

    subgraph Events["Real-time Events"]
        MSG[Message Events]
        SESS[Session Events]
        QR[QR Code Updates]
    end

    WebSocket --> Events
Loading
ID Requirement Priority Phase
FR-WS-001 The system must provide a WebSocket endpoint for real-time updates Medium 2
FR-WS-002 The system must support API key authentication for WebSocket Medium 2
FR-WS-003 The system must allow subscribing to a specific session Medium 2
FR-WS-004 The system must allow subscribing to specific event types Medium 2
FR-WS-005 The system must implement ping/pong keep-alive Medium 2
FR-WS-006 The system must auto-reconnect with exponential backoff Low 3
FR-WS-007 The system must stream QR code updates in real time High 2

2.2.5 Contact Management

ID Requirement Priority Phase
FR-CT-001 The system must retrieve all contacts High 1
FR-CT-002 The system must retrieve a contact by ID High 1
FR-CT-003 The system must check if a number exists on WhatsApp High 1
FR-CT-004 The system must retrieve a contact profile picture Medium 2
FR-CT-005 The system must block/unblock a contact Low 3

2.2.6 Group Management

flowchart TB
    subgraph GroupOps["Group Operations"]
        direction TB
        CR[Create Group]
        UP[Update Info]
        AD[Add Participants]
        RM[Remove Participants]
        PR[Promote to Admin]
        DM[Demote Admin]
        LV[Leave Group]
    end
    
    subgraph GroupInfo["Group Info"]
        GI[Get Info]
        GP[Get Participants]
        GL[Get Invite Link]
    end
Loading
ID Requirement Priority Phase
FR-GR-001 The system must retrieve all groups Medium 2
FR-GR-002 The system must retrieve group info Medium 2
FR-GR-003 The system must retrieve group participants Medium 2
FR-GR-004 The system must create a group Medium 3
FR-GR-005 The system must update group info Low 3
FR-GR-006 The system must add participants Low 3
FR-GR-007 The system must remove participants Low 3
FR-GR-008 The system must promote/demote admins Low 3
FR-GR-009 The system must get/revoke invite links Low 3
FR-GR-010 The system must leave a group Low 3

2.2.7 Dashboard (Web UI)

flowchart LR
    subgraph Dashboard["Dashboard Features"]
        direction TB
        SS[Session Status]
        QR[QR Display]
        WM[Webhook Manager]
        LG[Logs Viewer]
        ST[Statistics]
    end
    
    Dashboard --> API[REST API]
    API --> BE[Backend]
Loading
ID Requirement Priority Phase
FR-UI-001 The dashboard must display the status of all sessions High 2
FR-UI-002 The dashboard must display QR codes High 2
FR-UI-003 The dashboard must manage webhooks Medium 2
FR-UI-004 The dashboard must view logs Medium 2
FR-UI-005 The dashboard must test sending messages Medium 2
FR-UI-006 The dashboard must display statistics Low 3
FR-UI-007 The dashboard must support dark mode Low 3

2.2.8 Authentication & Authorization

flowchart TB
    subgraph Auth["Authentication Flow"]
        REQ[Request] --> KEY[API Key Check]
        KEY -->|Valid| IP[IP Whitelist Check]
        KEY -->|Invalid| R401[401 Unauthorized]
        IP -->|Allowed| PERM[Permission Check]
        IP -->|Blocked| R403[403 Forbidden - IP]
        PERM -->|Granted| PROC[Process Request]
        PERM -->|Denied| R403B[403 Forbidden - Permission]
    end
Loading
ID Requirement Priority Phase
FR-AU-001 The system must support API key authentication High 2
FR-AU-002 The system must generate/revoke API keys High 2
FR-AU-003 The system must set permissions per API key Medium 3
FR-AU-004 The system must log API access Medium 2
FR-AU-005 The system must support IP whitelisting per API key Medium 2
FR-AU-006 The system must support CIDR notation for IP ranges Low 2
FR-AU-007 The system must set expiration dates for API keys Medium 2
FR-AU-008 The system must hash API keys before storage (SHA-256) High 2
FR-AU-009 The system must track last used timestamps per API key Low 2
FR-AU-010 The system must support a master API key from environment High 2
FR-AU-011 The system must support the X-Request-ID header for request tracing Medium 2

2.2.9 Bulk Operations

flowchart LR
    subgraph Batch["Batch Processing"]
        direction TB
        CREATE[Create Batch]
        QUEUE[Queue Messages]
        PROCESS[Process with Delay]
        TRACK[Track Progress]
        CANCEL[Cancel Option]
    end

    CREATE --> QUEUE --> PROCESS --> TRACK
    TRACK --> CANCEL
Loading
ID Requirement Priority Phase
FR-BK-001 The system must accept batches up to 100 messages Medium 2
FR-BK-002 The system must apply delays between messages (configurable, min 1s) High 2
FR-BK-003 The system must randomize delays for natural behavior Medium 2
FR-BK-004 The system must track batch progress (sent/failed/pending) Medium 2
FR-BK-005 The system must cancel a running batch Medium 2
FR-BK-006 The system must support template variables in batches Low 3
FR-BK-007 The system must return a batch ID for status tracking High 2
FR-BK-008 The system must clean up completed batches after 24 hours Low 3

2.3 Non-Functional Requirements

2.3.1 Performance

flowchart LR
    subgraph Performance["Performance Targets"]
        RT[Response Time < 500ms]
        TP[Throughput 100 req/s]
        MS[Memory < 500MB/session]
        ST[Startup < 30s]
    end
Loading
ID Requirement Target Priority
NFR-PF-001 API response time < 500ms (p95) High
NFR-PF-002 Message send latency < 2s High
NFR-PF-003 QR code generation < 3s High
NFR-PF-004 Memory per session < 500MB High
NFR-PF-005 Concurrent sessions 10+ per instance Medium
NFR-PF-006 Webhook delivery < 5s Medium
NFR-PF-007 Startup time < 30s Medium

2.3.2 Reliability & Availability

ID Requirement Target Priority
NFR-RL-001 Uptime 99.5% High
NFR-RL-002 Auto-recovery after crash < 60s High
NFR-RL-003 Session persistence Survive restart High
NFR-RL-004 Graceful shutdown Complete pending ops Medium
NFR-RL-005 Data durability No message loss High

2.3.3 Scalability

flowchart TB
    subgraph Vertical["Vertical Scaling"]
        V1[More RAM]
        V2[More CPU]
        V3[More Sessions]
    end
    
    subgraph Horizontal["Horizontal Scaling"]
        H1[Multiple Instances]
        H2[Load Balancer]
        H3[Shared Storage]
    end
    
    Vertical --> Single[Single Instance]
    Horizontal --> Cluster[Cluster Mode]
Loading
ID Requirement Target Priority
NFR-SC-001 Vertical scaling 20+ sessions/instance Medium
NFR-SC-002 Horizontal scaling support Multiple instances Low
NFR-SC-003 Stateless API design Session-independent High

2.3.4 Security

ID Requirement Description Priority
NFR-SE-001 API Authentication API key required High
NFR-SE-002 Data encryption TLS for all connections High
NFR-SE-003 Secret management Encrypted storage High
NFR-SE-004 Input validation Sanitize all inputs High
NFR-SE-005 Rate limiting Prevent abuse Medium
NFR-SE-006 Audit logging Track all operations Medium
NFR-SE-007 CORS configuration Configurable origins Medium

2.3.5 Maintainability

ID Requirement Description Priority
NFR-MT-001 Code coverage > 80% unit tests Medium
NFR-MT-002 Documentation API docs up-to-date High
NFR-MT-003 Logging Structured logging High
NFR-MT-004 Modular architecture Loosely coupled High
NFR-MT-005 Configuration Environment-based High

2.3.6 Usability

ID Requirement Description Priority
NFR-US-001 Setup time < 5 minutes with Docker High
NFR-US-002 API documentation Swagger/OpenAPI High
NFR-US-003 Error messages Clear & actionable High
NFR-US-004 Examples Working code examples Medium
NFR-US-005 Dashboard UX Intuitive interface Medium

2.3.7 Compatibility

ID Requirement Description Priority
NFR-CP-001 Node.js version 18.x, 20.x LTS High
NFR-CP-002 Database support SQLite, PostgreSQL High
NFR-CP-003 OS support Linux, macOS, Windows High
NFR-CP-004 Docker support Official image High
NFR-CP-005 ARM64 support Apple Silicon, ARM servers Medium

2.4 Use Cases

UC-001: Send Text Message

sequenceDiagram
    actor User
    participant API as OpenWA API
    participant Engine as WA Engine
    participant WA as WhatsApp
    
    User->>API: POST /api/sessions/:sessionId/messages/send-text
    API->>API: Validate request
    API->>Engine: sendMessage(chatId, text)
    Engine->>WA: Send via WhatsApp Web
    WA-->>Engine: Message sent
    Engine-->>API: Success response
    API-->>User: 200 OK {messageId}
Loading

Actors: External application, Developer
Precondition: Session is active and connected
Main Flow:

  1. User sends a POST request with chatId and text
  2. The system validates the request
  3. The system sends the message via the WhatsApp engine
  4. The system returns the messageId

Alternative Flow:

  • Session not active → Return 400 error
  • Invalid phone number → Return 400 error
  • WhatsApp error → Return 500 error

UC-002: Receive Message via Webhook

sequenceDiagram
    participant WA as WhatsApp
    participant Engine as WA Engine
    participant API as OpenWA
    participant WH as User Webhook
    
    WA->>Engine: New message received
    Engine->>API: Message event
    API->>API: Store message
    API->>WH: POST webhook payload
    WH-->>API: 200 OK
    API->>API: Mark delivered
Loading

Actors: WhatsApp, External webhook endpoint
Precondition: Webhook URL configured
Main Flow:

  1. WhatsApp sends a message to the session
  2. The engine receives and forwards to the API
  3. The API stores the message and sends it to the webhook
  4. The webhook endpoint acknowledges

Alternative Flow:

  • Webhook failed → Retry 3x
  • All retries failed → Log and mark failed

UC-003: Create New Session

stateDiagram-v2
    [*] --> Creating: POST /sessions
    Creating --> WaitingQR: Generate QR
    WaitingQR --> Scanning: User scans QR
    WaitingQR --> Timeout: 60s timeout
    Scanning --> Authenticating: QR scanned
    Authenticating --> Ready: Auth success
    Authenticating --> Failed: Auth failed
    Ready --> [*]
    Timeout --> [*]
    Failed --> [*]
Loading

2.5 Requirements Traceability Matrix

Requirement ID Use Case Test Case Status
FR-SM-001 UC-003 TC-SM-001 ✅ Implemented
FR-SM-002 UC-003 TC-SM-002 ✅ Implemented
FR-MSG-001 UC-001 TC-MSG-001 ✅ Implemented
FR-WH-001 UC-002 TC-WH-001 ✅ Implemented

2.6 Acceptance Criteria

Phase 1 MVP Acceptance Criteria

✓ A single session can be created and authenticated
✓ QR code can be scanned and session connected
✓ Text messages can be sent
✓ Image messages can be sent
✓ Incoming messages are forwarded to webhooks
✓ API documentation is available via Swagger
✓ Docker image can be built and run
✓ Basic health check endpoint works

Phase 2 Acceptance Criteria

✓ Multiple sessions can run concurrently
✓ Dashboard can display all sessions
✓ Webhooks can be managed via UI
✓ PostgreSQL can be used as storage
✓ API key authentication works
✓ Rate limiting is enabled