Initial BizOne portal setup

reference/01-product-requirements.md

@@ -0,0 +1,61 @@
+# WA Business Dashboard Platform - Product Requirements
+
+## Overview
+A complete web dashboard to manage WhatsApp Business operations through API integration. The platform acts as an admin dashboard, API backend, webhook receiver, and async processing engine.
+
+## Goals
+- Manage contacts and phonebook
+- View inbound and outbound messages
+- Save and manage draft messages
+- Send single and bulk messages
+- Manage templates
+- Manage users and roles
+- Configure API, webhook, and sender settings
+- Monitor webhook, jobs, and activity logs
+
+## Core Modules
+1. Authentication and RBAC
+2. Dashboard overview and analytics
+3. Contacts and tags
+4. Conversations and messages
+5. Draft management
+6. Campaigns and broadcast
+7. Template management
+8. WhatsApp API integration settings
+9. Webhook settings and logs
+10. User management
+11. Activity logs and queue monitor
+
+## Functional Requirements
+- JWT-based auth with role permissions
+- Contacts CRUD with import/export and tagging
+- Message list with filters and status tracking
+- Conversations inbox with assignment and notes
+- Draft approval flow
+- Bulk send with queue and scheduling
+- Template builder with variable preview
+- Public webhook endpoint with signature verification
+- Webhook logs with raw payload viewer and retry
+- Queue/job monitoring
+- Audit logging for admin actions
+
+## Non-Functional Requirements
+- Secure secret storage
+- HTTPS public webhook endpoint
+- Idempotent webhook processing
+- Queue-based bulk sending
+- Provider abstraction for future switching
+- Responsive desktop-first admin UI
+
+## User Roles
+- Super Admin
+- Admin
+- Operator
+- Viewer
+
+## Success Metrics
+- Message delivery rate
+- Failed message rate
+- Webhook success rate
+- Average job processing time
+- Campaign completion rate

reference/02-system-architecture.md

@@ -0,0 +1,53 @@
+# System Architecture
+
+## Core Components
+
+### Frontend Admin Dashboard
+- Next.js
+- TailwindCSS
+- shadcn/ui
+- TanStack Table
+- Recharts
+
+### Backend API
+- NestJS
+- Prisma ORM
+- PostgreSQL
+
+### Webhook Receiver
+- Public HTTPS endpoint
+- Signature validation
+- Raw payload logging
+- Queue handoff for processing
+
+### Worker / Queue
+- Redis
+- BullMQ
+- Handles bulk send, scheduled send, webhook processing, retries
+
+### Storage
+- S3 compatible or local object storage for media, import/export files
+
+## Logical Flow
+1. Admin uses dashboard
+2. Frontend calls backend API
+3. Backend stores data in PostgreSQL
+4. Bulk and async jobs go to Redis/BullMQ
+5. Worker sends outbound messages to provider
+6. Provider calls webhook endpoint
+7. Webhook receiver stores raw events and dispatches processing jobs
+8. Processed statuses update messages, conversations, and campaign recipients
+
+## Security
+- JWT + refresh token
+- Role-based access control
+- Secret encryption at rest
+- Webhook signature validation
+- Audit logs
+- Rate limiting on public endpoints
+
+## Deployment Recommendation
+- Dockerized services
+- Reverse proxy via Nginx
+- HTTPS domain for webhook
+- Separate worker process

reference/03-database-schema.md

@@ -0,0 +1,57 @@
+# Database Schema
+
+## Main Tables
+- users
+- roles
+- permissions
+- role_permissions
+- contacts
+- tags
+- contact_tags
+- senders
+- templates
+- drafts
+- campaigns
+- campaign_recipients
+- conversations
+- messages
+- webhook_events
+- integration_configs
+- activity_logs
+- jobs
+
+## Key Notes
+- Use UUID primary keys
+- Store raw provider payloads in JSONB
+- Normalize webhook events into internal event types
+- Use created_at and updated_at on all mutable entities
+- Track message lifecycle timestamps: sent, delivered, read, failed
+
+## Suggested Enums
+### User Status
+- active
+- inactive
+- suspended
+
+### Template Status
+- draft
+- pending
+- approved
+- rejected
+- archived
+
+### Campaign Status
+- draft
+- scheduled
+- processing
+- completed
+- paused
+- failed
+- cancelled
+
+### Message Status
+- queued
+- sent
+- delivered
+- read
+- failed

reference/04-api-spec.md

@@ -0,0 +1,82 @@
+# API Specification
+
+## Auth
+- POST /api/auth/login
+- POST /api/auth/refresh
+- POST /api/auth/logout
+- GET /api/auth/me
+
+## Users
+- GET /api/users
+- POST /api/users
+- GET /api/users/:id
+- PATCH /api/users/:id
+- DELETE /api/users/:id
+
+## Contacts
+- GET /api/contacts
+- POST /api/contacts
+- POST /api/contacts/import
+- POST /api/contacts/export
+- GET /api/contacts/:id
+- PATCH /api/contacts/:id
+- DELETE /api/contacts/:id
+
+## Conversations
+- GET /api/conversations
+- GET /api/conversations/:id
+- PATCH /api/conversations/:id/assign
+- PATCH /api/conversations/:id/status
+- POST /api/conversations/:id/note
+
+## Messages
+- GET /api/messages
+- GET /api/messages/:id
+- POST /api/messages/send
+- POST /api/messages/bulk-send
+- POST /api/messages/:id/retry
+
+## Drafts
+- GET /api/drafts
+- POST /api/drafts
+- GET /api/drafts/:id
+- PATCH /api/drafts/:id
+- POST /api/drafts/:id/approve
+- POST /api/drafts/:id/reject
+- POST /api/drafts/:id/send
+
+## Campaigns
+- GET /api/campaigns
+- POST /api/campaigns
+- GET /api/campaigns/:id
+- PATCH /api/campaigns/:id
+- POST /api/campaigns/:id/start
+- POST /api/campaigns/:id/pause
+- POST /api/campaigns/:id/cancel
+- GET /api/campaigns/:id/report
+
+## Templates
+- GET /api/templates
+- POST /api/templates
+- GET /api/templates/:id
+- PATCH /api/templates/:id
+- POST /api/templates/:id/sync
+- POST /api/templates/:id/approve
+- POST /api/templates/:id/archive
+
+## Integrations
+- GET /api/integrations/whatsapp
+- PATCH /api/integrations/whatsapp
+- POST /api/integrations/whatsapp/test
+- GET /api/integrations/senders
+- POST /api/integrations/senders
+
+## Logs
+- GET /api/logs/activity
+- GET /api/logs/webhooks
+- GET /api/logs/jobs
+
+## Dashboard
+- GET /api/dashboard/summary
+- GET /api/dashboard/message-stats
+- GET /api/dashboard/campaign-stats

reference/05-webhook-spec.md

@@ -0,0 +1,45 @@
+# Webhook Specification
+
+## Public Endpoints
+- GET /webhooks/whatsapp
+- POST /webhooks/whatsapp
+- POST /webhooks/whatsapp/:provider
+
+## Responsibilities
+- Validate verification token or signature
+- Store raw payload
+- Detect duplicate event_id
+- Enqueue processing job
+- Return 200 quickly
+
+## Internal Normalized Event Format
+```json
+{
+  "provider": "meta",
+  "event_type": "message.delivered",
+  "event_id": "evt_123",
+  "sender_phone": "628xxxx",
+  "recipient_phone": "628yyyy",
+  "external_message_id": "wamid.xxx",
+  "timestamp": "2026-05-08T06:00:00.000Z",
+  "payload": {}
+}
+```
+
+## Internal Event Types
+- message.inbound
+- message.sent
+- message.delivered
+- message.read
+- message.failed
+- template.updated
+- account.updated
+
+## Processing Flow
+1. Receive request
+2. Verify authenticity
+3. Save webhook_events record
+4. Ignore duplicates
+5. Push job to queue
+6. Worker parses and updates data
+7. Mark processed or failed

reference/06-figma-design-brief.md

@@ -0,0 +1,49 @@
+# Figma Design Brief
+
+Design a modern enterprise SaaS admin dashboard for a WhatsApp Business management platform.
+
+## Style Direction
+- Clean, premium, modern
+- WhatsApp-inspired green accent
+- White cards
+- Light gray background
+- Rounded corners
+- Soft shadows
+- Typography: Inter or Plus Jakarta Sans
+
+## Required Pages
+1. Login
+2. Dashboard Overview
+3. Contacts List
+4. Contact Detail
+5. Conversations Inbox
+6. Messages List
+7. Draft Messages
+8. Draft Editor
+9. Campaign List
+10. Campaign Detail
+11. Template List
+12. Template Builder
+13. Settings Overview
+14. WhatsApp API Settings
+15. Webhook Settings
+16. Webhook Logs
+17. Users Management
+18. Roles and Permissions
+19. Activity Logs
+20. Queue Monitor
+
+## Required Components
+- Left sidebar navigation
+- Top header
+- KPI cards
+- Charts
+- Data tables
+- Status badges
+- Filters
+- Mobile message preview
+- Webhook payload viewer drawer
+- Queue monitor widgets
+
+## Tone
+Professional, scalable, operational, suitable for internal business teams.

reference/07-page-wireframes.md

@@ -0,0 +1,33 @@
+# Page Wireframes
+
+## Dashboard Overview
+- Sidebar left
+- Header top
+- 4 KPI cards top row
+- Message volume chart
+- Delivery funnel
+- Recent campaigns table
+- Webhook health panel
+
+## Contacts List
+- Search and filters top
+- Import/export/add buttons
+- Main contacts table
+- Detail drawer on row click
+
+## Conversations
+- Left thread list
+- Right chat panel
+- Top assignment/status actions
+- Bottom message composer or template quick reply
+
+## Webhook Settings
+- Main config form left
+- Health summary card right
+- Recent event mini-table right bottom
+
+## Queue Monitor
+- Job counters top
+- Worker health section
+- Failed jobs table
+- Retry actions

reference/08-tech-stack-and-roadmap.md

@@ -0,0 +1,47 @@
+# Tech Stack and Roadmap
+
+## Recommended Stack
+### Frontend
+- Next.js
+- TailwindCSS
+- shadcn/ui
+- TanStack Table
+- Recharts
+- React Hook Form
+- Zod
+
+### Backend
+- NestJS
+- Prisma
+- PostgreSQL
+- Redis
+- BullMQ
+
+### Infra
+- Docker
+- Nginx
+- S3/local storage
+
+## Delivery Phases
+### Phase 1
+- Auth and RBAC
+- Users
+- Contacts
+- Integration settings
+- Webhook endpoint
+- Messages table
+- Dashboard summary
+
+### Phase 2
+- Conversations inbox
+- Templates
+- Drafts
+- Single send
+- Webhook logs
+
+### Phase 3
+- Campaign broadcast
+- Scheduling
+- Queue monitor
+- Analytics
+- Retry tools

reference/README.md

@@ -0,0 +1,15 @@
+# WA Dashboard Kit
+
+This ZIP contains a starter documentation and architecture pack for building a WhatsApp Business management dashboard.
+
+## Included
+- Product requirements
+- System architecture
+- Database schema notes
+- API spec
+- Webhook spec
+- Figma design brief
+- Page wireframes
+- Tech stack and roadmap
+- Prisma starter schema
+- OpenAPI starter file