gochat/docs/comparison/2026-06-10-gochat-chatwoot-alignment-review.md

GoChat ↔ Chatwoot Fresh Alignment Review Plan

Date: 2026-06-10
Scope: fresh implementation-difference review between GoChat and reference/chatwoot
Output: consolidated gap list and Chatwoot-alignment execution plan
Status: planned

Summary

• Treat /home/rogee/Projects/gochat/reference/chatwoot as the source of truth for routes, controllers, models, serializers, jobs, services, frontend API clients, and side effects.
• Use /home/rogee/Projects/gochat/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md as the current progress baseline, not as replacement evidence for fresh inspection.
• Keep this document as a fresh review deliverable. Do not replace the authoritative parity tracker unless a later implementation task explicitly updates it.
• Produce a decision-ready gap list covering what is already aligned, what still needs Chatwoot parity, priority, reference evidence, GoChat hotspot, and acceptance tests.

Current Baseline To Reconfirm

• Route evidence currently indicates zero missing tracked critical routes in /home/rogee/Projects/gochat/docs/parity/route_parity.md.
• GoChat route dump currently contains 973 lines in /home/rogee/Projects/gochat/docs/parity/gochat_routes.txt.
• The current local quick check of go test ./... passes in this checkout.
• Existing parity status has many slices in Review; these should not be promoted to Done without fresh reference inspection or live smoke evidence.

Review Targets

Area	What To Compare	Chatwoot Source	GoChat Hotspot
Route parity	Tracked critical routes, public routes, parameter-compatible paths, update methods	reference/chatwoot/config/routes.rb	internal/router, docs/parity/gochat_routes.txt, docs/parity/route_parity.md
Core API behavior	Envelopes, status codes, pagination, filters, permissions, serializers	reference/chatwoot/app/controllers, Jbuilder views, frontend API clients	internal/handler, internal/service, serializers
Conversation/message	Finder filters, assignment, status transitions, message windows, attachments, retry/delete behavior	app/finders/conversation_finder.rb, conversation/message controllers, message partials	internal/service/conversation_service.go, internal/service/message_service.go, API handlers
CRM	Contacts, companies, merge/import/export, labels, notes, contact inboxes, custom attributes	contact/company controllers, ContactMergeAction, CRM services	contact/company handlers and services
Inbox/channel	Inbox CRUD, working hours, members, agent bots, channel-specific config, reset secret, avatar	inbox/channel controllers, channel models	inbox/channel handlers, channel services, channel models
Search	Meilisearch payloads, filters, article/contact/conversation/message result shapes, fallback rules	app/services/search_service.rb, search controllers, frontend search clients	internal/search, internal/service/search_indexer*, search handlers
Widget/public APIs	Widget messages, public inbox flow, direct uploads, CSAT, help-center portal/category/article/search/sitemap	widget/public controllers and public Jbuilder views	widget/public handlers and services
Side effects/jobs	Durable async jobs, retries, idempotency, delivery status, webhooks, contact import/export, analytics rollups	app/jobs, listeners, async services	internal/worker, internal/dispatch, job replay services
Enterprise scope	SLA, Audit, CustomRole, AgentCapacity, Captain/Copilot, CSAT, InboxLimit, automation/macros, assignment policies	enterprise/app/controllers, enterprise/app/services, enterprise/app/jobs	enterprise-related handlers/services/models
Placeholder/stubs	Frontend-reachable placeholder responses and uncompiled .go.txt files	reference controllers and frontend clients	internal/handler, internal/service, internal/model, docs/parity/placeholder_audit.md

Expected Gap Categories

Priority	Gap Category	Current Read	Required Alignment
P0	Reused frontend live smoke	API-level and unit coverage is extensive, but full Chatwoot frontend smoke remains the strongest unclosed gate.	Run a full PostgreSQL/Redis/Meilisearch/GoChat/Vite/Chrome smoke and map every failure to an owning parity slice.
P0	Phase 2/3 drift audit	Many controller/serializer slices are in Review.	Freshly inspect reference controllers/Jbuilder/frontend clients before marking any high-impact slice Done.
P1	Attachments	Message attachment serializers are aligned for metadata/push payloads, but durable binary storage and provider-specific send behavior are still explicit review risks.	Define ActiveStorage-equivalent storage behavior or document accepted compatibility boundary; validate provider send paths.
P1	Realtime events	Focused payload tests exist, but browser/WebSocket validation is still required.	Validate ActionCable-compatible event flow from message/conversation/contact mutations into reused frontend state updates.
P1	Help center public surface	Public portal/category/article/search/sitemap routes are implemented in Review.	Close only after route, payload, locale, redirect, markdown, tracking-pixel, sitemap, and frontend smoke validation.
P1	Search live gate	Meilisearch is mandatory for production; DB fallback is development-only.	Run or document the live Meilisearch gate, reindex scheduling, release-mode fallback rejection, and account-scoped filters.
P2	External integrations	Provider webhooks and outbound deliveries are fakeable/tested in many paths, but production provider behavior needs live/failure-mode confirmation.	Validate WhatsApp/Twilio/Telegram/LINE/Meta/TikTok/Twitter/Shopify ack, signature, retry, and status semantics.
P2	CSAT templates	Generic survey send and channel-template jobs exist in Review.	Confirm WhatsApp/Twilio template payloads, observable failures, and frontend-visible states against Chatwoot.
P2	Captain/Copilot providers	Durable jobs and disabled/failure fallbacks exist, provider-specific LLM depth is feature-gated.	Validate provider-enabled behavior or explicitly document deployment feature gates.
P2	Exact route polish	Some paths are parameter-compatible rather than exact.	Convert to exact compatibility where practical, or document why external path compatibility is preserved.

Implementation Steps

1. Refresh factual baseline.
   • Re-run or inspect GoChat route dump tooling.
   • Compare current route evidence with /home/rogee/Projects/gochat/docs/parity/route_parity.md.
   • Record test baseline and any environment limitations.
2. Inspect Chatwoot reference by feature family.
   • For each target area, inspect matching reference controllers, models, Jbuilder partials, services, jobs, listeners, and frontend API clients.
   • Prefer local reference/chatwoot files over older reports or assumptions.
3. Inspect GoChat implementation hotspots.
   • Map each Chatwoot behavior to GoChat handlers, services, workers, models, serializers, and route registration.
   • Distinguish implemented parity, review-only parity, placeholder behavior, and intentionally excluded scope.
4. Produce the fresh review document.
   • Use sections: Current Baseline, Already Aligned, Remaining Gaps, Prioritized Alignment Plan, Acceptance Tests, and Tracker Update Recommendations.
   • For each gap, include priority, Chatwoot reference, GoChat hotspot, current status, required alignment, acceptance evidence, and suggested owner slice.
5. Feed results back into the active tracker only after review is accepted.
   • If new gaps are found, add named rows to /home/rogee/Projects/gochat/docs/CHATWOOT_PARITY_DEVELOPMENT_PLAN.md in a later implementation step.
   • Do not silently mark Review slices as Done without fresh evidence.

Acceptance Tests And Evidence

• Documentation-only review changes must pass git diff --check.
• Go code changes in later alignment work must include focused tests, go test ./..., and route artifact regeneration when routes change.
• Route changes must regenerate:
  • /home/rogee/Projects/gochat/docs/parity/gochat_routes.txt
  • /home/rogee/Projects/gochat/docs/parity/route_parity.md when tracked route sets change
• Optional live gates to record in the review:
  • Full reused Chatwoot frontend smoke with PostgreSQL, Redis, Meilisearch, GoChat, Vite, and Chrome.
  • Live Meilisearch integration test.
  • Provider webhook/delivery smoke in a configured integration environment.

Fresh Review Output Template

Priority	Feature / Gap	Chatwoot Reference	GoChat Hotspot	Current Status	Required Alignment	Acceptance Evidence	Owner Slice
P0	Frontend smoke gate	frontend clients, controllers, routes	full stack	Not closed by unit tests	Run smoke and assign every failure	Smoke report with pass/fail mapping	B12 / M7
P0	Serializer drift audit	controllers + Jbuilder	handlers + serializers	Review	Confirm envelopes/status/pagination/nulls	Focused fixture tests	Phase 2/3
P1	Attachment storage/send	message/attachment models and jobs	message service, upload service, delivery worker	Review	Durable binary and provider send parity	Attachment upload/send tests	B3 / P5.10

Assumptions

• This document is a landed development plan, not the final completed review report.
• The final completed review may update or supersede the gap rows after deeper file-by-file inspection.
• SSO, SAML, LDAP, and OIDC remain excluded from parity scope unless the user explicitly changes scope.
• All other paid features already tracked in GoChat parity work remain in scope.
• Historical Go environment blockers may be stale; current local test status should be revalidated during the actual review.