ADR-018: Mattermost Community Knowledge Integration

Status

Proposed

Date

2025-12-06

Context

The iDempiere community uses Mattermost for discussions, support, and knowledge sharing. Valuable information exists across various channels:

• ~developers - Technical discussions, code reviews, architecture decisions
• ~support - User questions, troubleshooting, solutions
• ~announcements - Release notes, breaking changes, deprecations
• ~plugins - Plugin development, best practices, integrations
• ~documentation - Wiki updates, documentation gaps, improvements

This knowledge is fragmented and hard to search. Integrating Mattermost as a knowledge source enables:

1. RAG-based answers - AI can reference community discussions
2. Historical context - Understand why decisions were made
3. Troubleshooting patterns - Learn from solved issues
4. Best practices - Extract patterns from expert discussions

Mattermost API

Mattermost provides a REST API for reading channel history:

GET /api/v4/channels/{channel_id}/posts
GET /api/v4/posts/search
GET /api/v4/teams/{team_id}/channels/search

Reference: https://api.mattermost.com/

Decision

Implement read-only Mattermost integration for knowledge extraction using the Mattermost REST API.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    AI Knowledge Pipeline                         │
└──────────────────────────┬──────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│ iDempiere Wiki  │ │ Mattermost  │ │ Source Code     │
│ (Existing)      │ │ (This ADR)  │ │ (Javadoc)       │
└─────────────────┘ └──────┬──────┘ └─────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Mattermost Knowledge Agent                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ @Tool searchMattermost(query, channels[], dateRange)       │ │
│  │ @Tool getChannelHistory(channelName, limit)                │ │
│  │ @Tool findSimilarDiscussions(topic)                        │ │
│  │ @Tool extractSolution(threadId)                            │ │
│  └────────────────────────────────────────────────────────────┘ │
│                               │                                  │
│                               ▼                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ MattermostToolLogic (shared layer)                         │ │
│  │  - MattermostApiClient (REST client)                       │ │
│  │  - PostProcessor (clean, extract, summarize)               │ │
│  │  - EmbeddingStore (vector cache)                           │ │
│  └────────────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTPS
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│              Mattermost Server (community.idempiere.org)         │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                │
│  │ ~developers │ │ ~support    │ │ ~plugins    │ ...            │
│  └─────────────┘ └─────────────┘ └─────────────┘                │
└─────────────────────────────────────────────────────────────────┘

Tool Definitions

public class MattermostToolLogic {

    @Tool("Search Mattermost channels for discussions matching a query")
    public ToolResult searchMattermost(
        @P("Search query") String query,
        @P("Channel names to search (optional, searches all if empty)") List<String> channels,
        @P("Date range: 'week', 'month', 'year', 'all'") String dateRange
    ) {
        // Uses Mattermost POST /api/v4/posts/search
    }

    @Tool("Get recent posts from a specific channel")
    public ToolResult getChannelHistory(
        @P("Channel name (e.g., 'developers', 'support')") String channelName,
        @P("Number of posts to retrieve") int limit
    ) {
        // Uses GET /api/v4/channels/{id}/posts
    }

    @Tool("Find discussions similar to a topic using semantic search")
    public ToolResult findSimilarDiscussions(
        @P("Topic or question to find similar discussions for") String topic
    ) {
        // Uses vector embeddings of cached posts
    }

    @Tool("Extract solution from a thread (summarize resolution)")
    public ToolResult extractSolution(
        @P("Thread/post ID") String threadId
    ) {
        // Fetches thread, uses LLM to extract solution
    }
}

Configuration

# application.properties
mattermost.server.url=https://mattermost.idempiere.org
mattermost.api.token=${MATTERMOST_TOKEN}
mattermost.team.name=idempiere
mattermost.channels.default=developers,support,plugins
mattermost.cache.ttl=3600

Channel Mapping

Security Considerations

1. Read-only access - Only GET operations, no posting
2. Token-based auth - Personal access token or bot token
3. Rate limiting - Respect Mattermost API limits
4. Data privacy - No caching of private channels
5. Token storage - Environment variable, not in config files

Use Cases

1. Developer Question

   User: "How do I create a custom callout in iDempiere 12?"
   AI: [searches ~developers and ~plugins for "callout" discussions]
   AI: "Based on community discussions, here's the pattern..."
   

2. Troubleshooting

   User: "Getting NullPointerException in MOrder.completeIt()"
   AI: [searches ~support for similar errors]
   AI: "This issue was discussed in thread X, the solution was..."
   

3. Best Practices

   User: "What's the recommended way to handle multi-tenant data?"
   AI: [searches ~developers for "multi-tenant" discussions]
   AI: "The community recommends the following pattern..."
   

Implementation Plan

Phase 1: API Client (Days 1-2)

• [ ] MattermostApiClient - REST client for Mattermost API
• [ ] Authentication with personal access token
• [ ] Basic endpoints: search, channel history, thread fetch
• [ ] Rate limiting and error handling

Phase 2: Tool Logic (Days 3-4)

• [ ] MattermostToolLogic - LangChain4j @Tool methods
• [ ] PostProcessor - Clean markdown, extract code blocks
• [ ] Integration with CliRouterAgent
• [ ] Test with sample queries

Phase 3: Caching & Embeddings (Days 5-6)

• [ ] In-memory cache for recent posts
• [ ] Vector embeddings for semantic search
• [ ] Incremental sync (fetch only new posts)

Phase 4: Documentation (Day 7)

• [ ] USER_GUIDE.md updates
• [ ] Configuration examples
• [ ] Example queries

Consequences

Positive

• Access to years of community knowledge
• Real troubleshooting patterns from solved issues
• Historical context for architectural decisions
• Reduced documentation gap

Negative

• Dependency on external Mattermost API
• Token management required
• Potential for stale cached data
• API rate limits may affect heavy usage

Neutral

• Read-only, no write operations
• Complements existing wiki integration
• Optional feature (works without token)

References

• Mattermost API Documentation
• iDempiere Community Mattermost
• ADR-012: RAG-Based Context Retrieval (cloudempiere.ai)
• ADR-013: LangChain4j Workflow Routing

ADR-018 | Version 1.0 | 2025-12-06 Status: Proposed Decision: Read-only Mattermost integration for community knowledge extraction