---

name: alichs-chat-stack description: Implement and debug the Alichs chat stack across frontend and backend. Use when working on /chat, chat SSE, visitor fingerprint identity, ScrmOpenAPI.js, api-yuntun-main, api-chat-sub, service.rabi.ae, OSS deployment, ngrok exposure, or H5 chat layout issues.

Alichs Chat Stack

Scope

This skill covers the chat feature spanning three workspace projects:

• Frontend: alichs-in-dubai
• Main backend host app: api-codes/api-yuntun-main
• Chat sub-app: api-codes/api-chat-sub

Use this skill for feature work, debugging, deployment, and environment bring-up of the chat page.

Architecture Snapshot

Frontend

• Stack: React 18 + Razzle + Ant Design + Zustand.
• Chat route: /chat.
• User identity: browser fingerprint from @rajesh896/broprint.js.
• API client: src/services/abudhabi/ScrmOpenAPI.js, generated by pnpm openapi.
• Chat state: src/stores/chat.js.
• Chat UI: src/routes/Chat/index.js and src/routes/Chat/index.less.
• Frontend dev proxy: src/server.js proxies /webcore to backend.

Backend

• Main service: Hapi app in api-yuntun-main.
• Chat plugin mount: api-chat-sub is registered under /webcore/chat.
• Public backend domain: https://service.rabi.ae.
• Main runtime ports:
  • 443 HTTPS app
  • 7777 secondary app
• Chat storage:
  • MongoDB for message persistence
  • Redis for online presence and Pub/Sub
• Chat routes and handlers live in api-chat-sub/router.

Runtime Message Flow

1. Frontend generates visitorId from browser fingerprint.
2. Frontend opens SSE stream for online status and realtime messages.
3. Frontend fetches room list and message history through ScrmOpenAPI.
4. Backend stores messages in MongoDB.
5. Backend pushes realtime updates by SSE, using Redis Pub/Sub when available and in-process fallback when Redis is unstable.

Key Files

Frontend

• alichs-in-dubai/config/routes.js
• alichs-in-dubai/src/App.js
• alichs-in-dubai/src/server.js
• alichs-in-dubai/src/utils/interceptors.js
• alichs-in-dubai/src/utils/luna-utils.js
• alichs-in-dubai/src/stores/chat.js
• alichs-in-dubai/src/routes/Chat/index.js
• alichs-in-dubai/src/routes/Chat/index.less

Backend

• api-codes/api-yuntun-main/configuration/config.json
• api-codes/api-yuntun-main/server.js
• api-codes/api-chat-sub/router/messages/index.js
• api-codes/api-chat-sub/router/messages/handlers/index.js
• api-codes/api-chat-sub/router/rooms/handlers/index.js
• api-codes/api-chat-sub/router/chat-runtime.js

Important Design Decisions

Conversation Model

• Do not treat direct chat as a single-user room id.
• Use a stable conversation id:
  • format: dm:<smaller-id>:<larger-id>
• Messages should carry both:
  • senderId
  • receiverId

This prevents the receiver UI from mislabeling the sender.

SSE Host Selection

• Local frontend on localhost should use relative /webcore/... SSE so local proxying works.
• Online frontend on www.rabi.ae must connect SSE to https://service.rabi.ae/webcore/chat/base/stream.
• Do not rely on axios interceptors for SSE. EventSource needs explicit host selection.

SSE Response Handling

• SSE handler uses request.raw.res.writeHead(...).
• Because this bypasses normal Hapi response processing, CORS headers must be set manually.
• Required SSE headers:
  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive
  • X-Accel-Buffering: no
  • Access-Control-Allow-Origin
  • Access-Control-Allow-Credentials
  • Vary: Origin

Redis Failure Tolerance

Redis can be unstable in this environment. Chat must degrade gracefully:

• Rooms endpoint should not hang forever on Redis calls.
• SSE should connect immediately, even if Redis subscription is late or failing.
• Online visitor list should have an in-process fallback.
• Realtime message delivery should still work within the same backend instance if Redis Pub/Sub fails.

Frontend Workflow

When adding or changing chat UI

1. Update route and whitelist if needed.
2. Keep chat logic centralized in src/stores/chat.js.
3. Keep UI components dumb; derive state from store.
4. Normalize any dynamic text before rendering.
5. For H5, ensure only the message area scrolls.

Chat store responsibilities

• generate or restore visitorId
• fetch rooms
• fetch history with pagination
• open and maintain SSE connection
• merge optimistic sends
• maintain unread counts
• handle reconnects

H5 layout requirements

• Use 100dvh rather than only 100vh.
• Parent flex containers must allow children to shrink with min-height: 0.
• Message list must be the scroll container.
• Composer must not shrink away.
• Add bottom safe-area padding for mobile input area.

Backend Workflow

When adding or changing chat API

1. Edit api-chat-sub.
2. If routes change, confirm swagger includes them through api-yuntun-main.
3. Run pnpm install inside api-codes/api-yuntun-main.
   • This is required because api-chat-sub is a file: dependency and may not refresh automatically.
4. Restart api-yuntun-main.
5. Re-run frontend pnpm openapi.

Message endpoints

• history: GET /webcore/chat/base/rooms/{roomId}/messages
• send: POST /webcore/chat/base/rooms/{roomId}/messages
• stream: GET /webcore/chat/base/stream
• offline: POST /webcore/chat/base/offline
• rooms: GET /webcore/chat/base/rooms

Main backend registration

api-yuntun-main/configuration/config.json mounts:

• api-chat-sub at /webcore/chat
• CORS is enabled with origin: ["*"]

Even with route CORS enabled, SSE still needs manual headers because raw response writing bypasses automatic handling.

Local Development Environment

Frontend

Project: alichs-in-dubai

• start dev server: pnpm start
• default local page: http://localhost:8090/chat
• regenerate API client: pnpm openapi

Backend

Project: api-codes/api-yuntun-main

• start service: pnpm start
• runtime is usually kept in tmux
• HTTPS endpoint: https://localhost:443
• swagger: https://localhost:443/swagger.json

External exposure

• ngrok exposes local 443 as https://service.rabi.ae
• frontend local proxy targets service.rabi.ae by default unless intentionally kept local

Deployment Workflow

Frontend deployment

Project: alichs-in-dubai

Run:

pnpm page-publish:mac

This builds static assets and uploads them to OSS.

Expected online entry:

• https://www.rabi.ae/chat/

Note:

• /chat/ may work while /chat returns 404 if OSS/CDN routing is not configured to rewrite to chat/index.html.

Backend deployment model

• backend stays on the local host app
• api-yuntun-main serves 443
• ngrok maps that HTTPS service to https://service.rabi.ae

If backend code changed:

1. update api-chat-sub
2. run pnpm install in api-yuntun-main
3. restart backend in tmux
4. confirm https://service.rabi.ae/swagger.json

Verification Checklist

Frontend checks

• /chat or /chat/ loads
• route is whitelisted
• room list loads
• history loads
• sender label is correct
• H5 can scroll long histories
• input box stays visible on mobile

Backend checks

• swagger includes chat endpoints
• GET /webcore/chat/base/rooms returns quickly
• GET /webcore/chat/base/stream sends stream-open and connected
• SSE response includes CORS headers for www.rabi.ae
• history endpoint returns chronological message list

Useful probe commands

curl -I https://service.rabi.ae/swagger.json
curl -N "http://localhost:8090/webcore/chat/base/stream?visitorId=test&roomId=test"
curl -I -H "Origin: https://www.rabi.ae" "https://service.rabi.ae/webcore/chat/base/stream?visitorId=test&roomId=test"
curl "http://localhost:8090/webcore/chat/base/rooms"

Common Failure Modes

Objects are not valid as a React child

Cause:

• a message or room field contains { code, data, message } or another object and gets rendered directly

Fix:

• normalize renderable text in the store and component layer

History API added but frontend client missing method

Cause:

• api-yuntun-main still uses stale local file: dependency

Fix:

1. run pnpm install in api-yuntun-main
2. restart backend
3. run pnpm openapi in frontend

Local /webcore/chat/base/rooms hangs

Cause:

• Redis calls stall

Fix:

• use timeout-wrapped Redis calls
• return in-memory online visitor fallback

Online SSE blocked by CORS

Cause:

• SSE switched to service.rabi.ae but raw response omitted Access-Control-Allow-Origin

Fix:

• add CORS headers in handleSSEStream

Online page loads but SSE points to wrong host

Cause:

• EventSource still uses relative /webcore/...

Fix:

• explicitly use https://service.rabi.ae/webcore/chat/base/stream online
• keep relative path only for local localhost

H5 cannot scroll and composer is pushed off-screen

Cause:

• stacked viewport heights and missing min-height: 0 in flex containers

Fix:

• use 100dvh
• make message list the only scroll area
• keep composer flex-shrink: 0

Default Execution Order For Future Agents

When asked to change chat behavior, use this order:

1. Confirm whether the problem is frontend-only, backend-only, or both.
2. Check src/stores/chat.js first for state, SSE, and host selection issues.
3. Check api-chat-sub next for API behavior and SSE streaming.
4. If backend code changed, run pnpm install in api-yuntun-main.
5. Restart backend in tmux.
6. If Swagger changed, run pnpm openapi.
7. Verify locally.
8. If requested, deploy frontend with pnpm page-publish:mac.

Output Expectations

When using this skill, the agent should report:

• what changed in frontend
• what changed in backend
• whether api-yuntun-main dependency sync was required
• whether backend restart was performed
• what was verified locally
• what was verified online