whatshooked/PLAN.md

Lets create a new project. I've already created the go.mod file. Be pricise and summaritive. The project is written in modern go.mod

The project must do the following: A service that connects to whatsapp via the whatsmeow api. When new message are received, it will send the message to all registered hooks. The service must have a list of registered web hooks. Whet a hook is called, it must send a message to whatsapp. Name the hooks and enpoints correctly. Two way communication is needed.

First Phase: COMPLETED Instance / Config level hooks and whatsapp accounts.

• config package: Configuration via viper, loaded from config.json. Covers server host/port, whatsapp accounts, hooks, MQTT, and WhatsApp Business API credentials.
• logging package: Structured logging with severity levels using zerolog.
• whatsapp package (whatsmeow): Connects to personal WhatsApp accounts via tulir/whatsmeow. Handles QR code auth flow, session persistence, and message send/receive.
• whatsapp package (businessapi): WhatsApp Business API integration. Supports sending messages, templates, extended sending, business profile and catalog management.
• server command: HTTP server exposing hook endpoints, health check (/health), and QR code streaming for account pairing. Runs on configurable port (default 8825).
• cli command: Cobra-based CLI for server interaction — health checks, account management, hook management, and pushing messages via the server.
• events system: Pub/sub event bus for whatsapp lifecycle events (connect, disconnect, message received, send success/failure). Events flow between whatsmeow, business API, hooks, and MQTT.
• hooks package: Webhook registration and HTTP dispatch. Incoming whatsapp messages are forwarded to all registered hook URLs.
• cache package: In-memory message caching layer.
• event logger: Persistent event logging to disk for debugging and audit.
• MQTT support: Optional MQTT broker integration for event routing and message delivery.
• Docker: Dockerfile and docker-compose with health checks, session/config volume mounts, and resource limits.
• CI/CD: GitHub Actions workflows with lint and test steps.
• Static pages: Privacy policy and terms of service served via the server.

Second Phase: IN PROGRESS

COMPLETED:

• ✅ Storage setup with PostgreSQL and SQLite support
• ✅ Database models generated in models package (7 tables: users, api_keys, hooks, whatsapp_accounts, event_logs, sessions, message_cache)
• ✅ ResolveSpec integration with unified server architecture (pkg/api/server.go)
• ✅ Combined authentication system (JWT + legacy auth support)
• ✅ Database initialization with SQLite/PostgreSQL compatibility (pkg/storage/db.go)
• ✅ BUN ORM integration with repository pattern (pkg/storage/repository.go)
• ✅ React frontend with Vite
• ✅ User authentication flow (login/logout with JWT tokens)
• ✅ Frontend routing with protected routes (React Router)
• ✅ Dashboard layout with sidebar navigation
• ✅ Default admin user seeding (admin/admin123)
• ✅ ResolveSpec auto-generated CRUD endpoints for all models
• ✅ API client with JWT interceptors (web/src/lib/api.ts)
• ✅ TypeScript types for all models (web/src/types/index.ts)
• ✅ UsersPage with full CRUD operations (vanilla CSS implementation)
• ✅ HooksPage with hooks list and CRUD operations (vanilla CSS implementation)
• ✅ AccountsPage with WhatsApp accounts management (vanilla CSS implementation)
• ✅ Mantine UI library installed (@mantine/core, @mantine/hooks, @mantine/form, @mantine/notifications, @mantine/modals, @mantine/dates)
• ✅ oranguru installed for grids and forms (with --legacy-peer-deps due to React 19)

IN PROGRESS:

• 🚧 Refactoring all pages to use Mantine components (replacing vanilla CSS)
• 🚧 Configuring Mantine theme and providers
• 🚧 Integrating oranguru for data grids

CURRENT REQUIREMENTS:

• ✅ MUST USE Mantine UI library (https://mantine.dev/core/package/) - Provides default styles, eliminates need for custom CSS

• ✅ MUST USE oranguru (https://git.warky.dev/wdevs/oranguru) - Required for grids and forms (npm install @warkypublic/oranguru)

• 🚧 Frontend MUST be served at /ui/ route - Not root path, Go server serves /ui/* for admin interface

• 🚧 Update vite config for /ui/ base path

• 🚧 Update Go server to serve SPA at /ui/ instead of root

TODO:

• ⏳ Refactor UsersPage to use Mantine Table and oranguru DataGrid
• ⏳ Refactor HooksPage to use Mantine components
• ⏳ Refactor AccountsPage to use Mantine components
• ⏳ EventLogsPage with filtering and pagination using Mantine + oranguru
• ⏳ DashboardPage with real statistics using Mantine components
• ⏳ Remove all custom CSS files after Mantine migration
• ⏳ Configure Mantine MantineProvider in App.tsx
• ⏳ Makefile for build, test and migrate (backend + frontend)
• ⏳ tooldoc folder setup for tool documentation

ARCHITECTURE NOTES:

• Unified server on single port (8080, configurable)
• No more Phase 1/Phase 2 separation - single ResolveSpec server
• Combined authentication: JWT (new) + API key/basic auth (legacy backward compatibility)
• Frontend served at /ui/ route (not root) - built to web/dist/ and served by Go server
• API endpoints at /api/v1/* and WhatsApp webhooks at root level
• Database models without schema prefix (works with both SQLite and PostgreSQL)
• Table creation uses dual-path for SQLite/PostgreSQL compatibility
• Have to use relspecgo for model generation and updates.

ROUTING STRUCTURE:

/ (root)                  → WhatsApp API endpoints (legacy Phase 1)
/health                   → Health check
/api/send                 → Send WhatsApp messages
/api/hooks                → Legacy hooks endpoint
/webhooks/whatsapp/*      → WhatsApp webhook receivers
/api/v1/*                 → REST API (ResolveSpec auto-generated CRUD)
/ui/*                     → React Admin UI (Mantine + oranguru)

KEY CHANGES FROM ORIGINAL PLAN:

• Using React + Vite (not Tanstack Start)
• NOW USING Mantine UI (REQUIRED - installed and being integrated)
• NOW USING oranguru (REQUIRED - installed with --legacy-peer-deps)
• Admin UI at /ui/ route instead of root (REQUIRED)