​

Team Messaging (Mattermost Integration)

Status: DRAFT Priority: P2 Last Verified: 2026-03-29 Spec Author: Claude (automated)

​

1. Problem Statement / Feature Purpose

• Team members communicate within their organization context
• No separate account creation — users are provisioned on first access
• Equabot agent is reachable via the #agent channel
• Platform events (share issuance, document uploads, member changes) post notifications to relevant channels

​

2. Current State

​

Frontend (equa-web) — NOT YET IMPLEMENTED

Source: equa-web/src/app/components/header/shared/organization-links.tsx, Line: 125 — “Interact with your organization using our communication system.” Source: equa-web/src/modules/auth/components/carousel.tsx, Line: 117 — Onboarding carousel mentions “Notification System”

​

Backend (equa-server)

Source: equa-server/modules/organizations/src/writing.ts, Line: 173 (onMemberAdded) Source: equa-server/modules/organizations/src/writing.ts, Line: 305 (onMemberRemoved)

​

Agent Bridge (equabot-gateway)

​

Data Flow

equa-web (user navigates to /messaging)
  |
  | POST /api/v1/mattermost/session { organizationId }
  v
equa-server
  | 1. Verify session cookie + org membership
  | 2. Lookup or create Mattermost user (POST /api/v4/users)
  | 3. Issue personal access token (POST /api/v4/users/{id}/tokens)
  | 4. Ensure org team exists + membership
  | Response: { token, baseUrl, teamName, mmUserId }
  v
equa-web
  | <iframe src="chat.equa.cc/login/token?token=xxx&redirect_to=/team">
  v
Mattermost Server (chat.equa.cc)
  | User sends @equabot message in #agent channel
  | WebSocket event -> gateway monitor
  v
equabot-gateway (Mattermost extension)
  | resolveAgentRoute() with teamId
  | equa-platform resolves orgId via GET /api/v1/mattermost/team-mapping/{teamId}
  | Agent processes with org-scoped tools
  | sendMessageMattermost() -> response in channel
  v
Mattermost -> displayed in equa-web iframe

​

3. Target State / Complete Description

• Auto-provisioning: First visit creates Mattermost user, team, default channels, and membership
• Seamless auth: No separate login — equa-server issues personal access tokens mapped to the Equa session
• Default channels per org: #general (auto), #announcements, #cap-table, #documents, #agent
• Platform notifications: Share issuance, document uploads, and member changes post to relevant channels
• Agent integration: Messages in #agent mentioning the bot are routed through equabot-gateway to the org-scoped agent
• Member lifecycle sync: Adding/removing org members in Equa automatically syncs Mattermost team membership

​

4. Data Model

Source: equa-server/modules/persistence/src/schema.ts, Lines: 2042-2080

Source: equa-server/modules/persistence/lab/sql/migrations/2.35.0-mattermost-mappings.sql

​

5. API Endpoints

Source: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts, Lines: 34-170

​

6. Frontend Components

​

Route

​

Component Tree

MessagingPage (Redux-connected, withOrganizationHeader HOC)
  ├── MessagingLoading (while session provisioning)
  ├── MessagingError (on failure, with retry)
  └── MattermostEmbed (iframe with token-based auth URL)

​

Embedding Strategy

{baseUrl}/login/token?token={token}&redirect_to=/{teamName}/channels/{channel}

​

7. Business Rules and Validation

1. Organization membership required: Only org members can access messaging for that org.
   • Enforced at: equa-server/modules/agent/src/mattermost/mattermost-endpoints.ts, Line: 34 (session endpoint checks org access)
2. One Mattermost team per org: Each Equa organization maps to exactly one Mattermost team.
   • Enforced at: equa-server/modules/agent/src/mattermost/mattermost-provisioning.ts (ensureTeam uses org ID as key)
3. Token encryption: Personal access tokens stored in the database are AES-encrypted.
   • Enforced at: equa-server/modules/agent/src/mattermost/mattermost-provisioning.ts (issueSessionToken encrypts with AesKey)
4. Non-blocking sync: Member add/remove sync to Mattermost is fire-and-forget to avoid blocking org operations.
   • Enforced at: equa-server/modules/organizations/src/writing.ts, Lines: 173, 305 (async calls with .catch)
5. Signup disabled: Direct Mattermost signup is disabled. Users can only be provisioned through Equa.
   • Enforced at: Mattermost env vars MM_EMAILSETTINGS_ENABLESIGNUPWITHEMAIL=false, MM_TEAMSETTINGS_ENABLEOPENSERVER=false

​

8. Acceptance Criteria

• AC-1: Navigating to /:orgId/messaging provisions a Mattermost user, team, and membership on first visit — backend ready, frontend not built
• AC-2: Mattermost UI loads in an iframe, auto-authenticated with the provisioned token — frontend not built
• AC-3: User sees only their organization team and channels — backend ready, frontend not built
• AC-4: Messages persist across sessions — backend ready, frontend not built
• AC-5: Mentioning @equabot in #agent channel triggers an agent response — gateway config needed
• AC-6: Share issuance posts a notification to #cap-table — notification service exists, event hooks not wired
• AC-7: Adding/removing org members syncs Mattermost team membership — sync hooks exist, equa-server redeploy needed

​

9. Risks and Edge Cases