@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/ask-your-architecture/05-slack-integration/04-deployment.md

@@ -0,0 +1,236 @@
+---
+sidebar_position: 4
+keywords:
+- Slack Bot
+- Deployment
+- Docker
+sidebar_label: Deployment
+title: Deployment
+description: Deploy the bot to production
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<PlanBanner plan="Scale" />
+
+Deploy the EventCatalog Slack Bot to your infrastructure. The bot uses Socket Mode, so it maintains an outbound connection to Slack without requiring a public URL, load balancer, or SSL certificates.
+
+## Docker
+
+The simplest way to deploy is using Docker. The bot includes a Dockerfile and docker-compose configuration.
+
+### Build the image
+
+```bash
+docker build -t eventcatalog-slack-bot .
+```
+
+### Run with docker-compose
+
+```bash
+docker compose up -d
+```
+
+### View logs
+
+```bash
+docker compose logs -f
+```
+
+The `docker-compose.yml` file mounts your config and reads environment variables from `.env`:
+
+```yaml
+services:
+  eventcatalog-slack-bot:
+    build: .
+    container_name: eventcatalog-slack-bot
+    restart: unless-stopped
+    env_file:
+      - .env
+    volumes:
+      - ./eventcatalog-bot.config.ts:/app/eventcatalog-bot.config.ts:ro
+    environment:
+      - NODE_ENV=production
+```
+
+## Docker networking
+
+When running the bot in Docker, the container needs network access to your EventCatalog server. Configuration depends on where EventCatalog runs.
+
+### EventCatalog on localhost
+
+Docker containers cannot use `localhost` to reach the host machine. Use one of these approaches:
+
+**Option 1: Use host.docker.internal (recommended)**
+
+Update your config to use the special Docker hostname:
+
+```typescript
+eventCatalog: {
+  url: 'http://host.docker.internal:3000',
+}
+```
+
+:::info
+Your EventCatalog server must bind to all interfaces (`0.0.0.0`), not just `localhost`. Check your EventCatalog startup logs. If it shows `localhost:3000`, you may need to start it with a `--host 0.0.0.0` flag.
+:::
+
+**Option 2: Run the bot outside Docker**
+
+For local development, skip Docker and run the bot directly:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    ```bash
+    npm install
+    npm run dev
+    ```
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    ```bash
+    pnpm install
+    pnpm dev
+    ```
+  </TabItem>
+</Tabs>
+
+This avoids networking complexity during development.
+
+### EventCatalog in Docker
+
+Put both containers on the same Docker network and use the container name as hostname:
+
+```yaml
+services:
+  eventcatalog:
+    # your EventCatalog config
+    networks:
+      - app-network
+
+  eventcatalog-slack-bot:
+    build: .
+    env_file:
+      - .env
+    volumes:
+      - ./eventcatalog-bot.config.ts:/app/eventcatalog-bot.config.ts:ro
+    networks:
+      - app-network
+
+networks:
+  app-network:
+```
+
+Configure the bot to use the container name:
+
+```typescript
+eventCatalog: {
+  url: 'http://eventcatalog:3000',
+}
+```
+
+### EventCatalog at public URL
+
+Use the public URL directly - no special configuration needed:
+
+```typescript
+eventCatalog: {
+  url: 'https://your-catalog.example.com',
+}
+```
+
+## Other deployment options
+
+<details>
+<summary>Railway</summary>
+
+Railway automatically detects the Dockerfile and deploys the bot.
+
+1. Create a new project and connect your repository
+2. Add environment variables in the Railway dashboard:
+   - `EVENTCATALOG_SCALE_LICENSE_KEY`
+   - `SLACK_BOT_TOKEN`
+   - `SLACK_APP_TOKEN`
+   - `SLACK_SIGNING_SECRET`
+   - `ANTHROPIC_API_KEY` (or your chosen provider)
+3. Add your `eventcatalog-bot.config.ts` to the repository
+4. Deploy - Railway detects the Dockerfile automatically
+
+</details>
+
+<details>
+<summary>Fly.io</summary>
+
+Deploy to Fly.io using their CLI.
+
+**Initialize:**
+
+```bash
+fly launch --no-deploy
+```
+
+**Set secrets:**
+
+```bash
+fly secrets set EVENTCATALOG_SCALE_LICENSE_KEY=your-key
+fly secrets set SLACK_BOT_TOKEN=xoxb-...
+fly secrets set SLACK_APP_TOKEN=xapp-...
+fly secrets set SLACK_SIGNING_SECRET=...
+fly secrets set ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**Deploy:**
+
+```bash
+fly deploy
+```
+
+</details>
+
+<details>
+<summary>Render</summary>
+
+Deploy as a Background Worker on Render.
+
+1. Create a new **Background Worker** (not a Web Service)
+2. Connect your repository
+3. Set the build and start commands:
+
+<Tabs>
+  <TabItem value="npm" label="npm" default>
+    - Build command: `npm install && npm run build`
+    - Start command: `npm start`
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+    - Build command: `pnpm install && pnpm build`
+    - Start command: `pnpm start`
+  </TabItem>
+</Tabs>
+
+4. Add environment variables in the Render dashboard
+5. Deploy
+
+</details>
+
+<details>
+<summary>AWS, GCP, or Azure</summary>
+
+Deploy as a container or long-running process. The bot requires:
+
+- Outbound HTTPS/WSS connections to Slack
+- No inbound connections (Socket Mode handles communication)
+- No load balancers or public endpoints needed
+
+Suitable services include:
+
+- **AWS:** ECS, EKS, EC2
+- **GCP:** Cloud Run (always running), GKE, Compute Engine
+- **Azure:** Container Instances, AKS, Virtual Machines
+
+Ensure the process stays running and can make outbound connections to:
+- `slack.com` (Socket Mode connection)
+- Your EventCatalog instance
+- Your AI provider API
+
+</details>

package/dist/docs/development/ask-your-architecture/05-slack-integration/05-usage.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 5
+keywords:
+- Slack Bot
+- Usage
+sidebar_label: Using the bot
+title: Using the bot
+description: Query architecture documentation from Slack
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Interact with the EventCatalog Slack Bot to query your architecture documentation. The bot responds to @mentions and can auto-reply in dedicated channels.
+
+## @Mention in any channel
+
+Invite the bot to any channel and @mention it to ask questions. The bot replies in a thread to keep channels organized.
+
+### Example questions
+
+```
+@eventcatalog Tell me about the OrderCreated event
+```
+
+```
+@eventcatalog What services consume the InventoryUpdated event?
+```
+
+```
+@eventcatalog List all events in the Orders domain
+```
+
+```
+@eventcatalog Show me the schema for the PaymentProcessed event
+```
+
+The bot reads your EventCatalog documentation and provides detailed answers grounded in your architecture.
+
+## Dedicated auto-reply channels
+
+Create a channel where the bot automatically responds to every message - no @mention needed. This gives your team a dedicated space for architecture questions.
+
+### Setup
+
+1. Create a new channel (e.g., `#ask-eventcatalog` or `#ask-eda`)
+2. Invite the bot to the channel
+3. Get the channel ID:
+   - Right-click the channel name
+   - Click **View channel details**
+   - Scroll to the bottom to find the Channel ID
+4. Add the channel ID to your config:
+
+```typescript
+slack: {
+  autoReplyChannels: ['C0123456789'],
+}
+```
+
+5. Restart the bot
+
+Now anyone can post questions directly in the channel and receive instant answers.
+
+### Multiple channels
+
+Configure multiple auto-reply channels:
+
+```typescript
+slack: {
+  autoReplyChannels: ['C0123456789', 'C9876543210'],
+}
+```
+
+## Thread context
+
+The bot automatically reads conversation history in threads. This enables natural follow-up questions without repeating context.
+
+### Example conversation
+
+**User:** Tell me about the OrderCreated event
+
+**Bot:** The OrderCreated event is published when...
+
+**User:** What are its consumers?
+
+**Bot:** Based on our earlier discussion about OrderCreated, the consumers are...
+
+**User:** Show me the schema
+
+**Bot:** Here's the schema for OrderCreated...
+
+Thread context works automatically in public channels. For private channels and DMs, add optional scopes to your Slack app:
+
+- `groups:history` - Private channels
+- `im:history` - Direct messages
+- `mpim:history` - Group DMs
+
+After adding scopes, reinstall the app to your workspace.
+
+## Best practices
+
+### Ask specific questions
+
+The bot performs best with clear, specific questions:
+
+**Good:**
+- "What services consume the OrderCreated event?"
+- "Show me all events in the Payment domain"
+- "What's the schema format for UserRegistered?"
+
+**Less effective:**
+- "Tell me about everything"
+- "What does this system do?"
+
+### Use thread conversations
+
+Keep related questions in the same thread. The bot uses thread history to provide better context-aware answers.
+
+### Name resources clearly
+
+Mention specific event names, service names, or domain names to get precise answers:
+
+- "Tell me about the **OrderCreated** event"
+- "What events does the **PaymentService** produce?"
+- "List all events in the **Orders** domain"
+
+## Invite the bot to channels
+
+The bot can only see messages in channels where it's invited.
+
+### Invite the bot
+
+1. Navigate to the channel
+2. Click the channel name at the top
+3. Click the **Integrations** tab
+4. Click **Add an app**
+5. Search for your bot and add it
+
+Alternatively, type `/invite @eventcatalog` in the channel.

package/dist/docs/development/ask-your-architecture/05-slack-integration/06-troubleshooting.md

@@ -0,0 +1,268 @@
+---
+sidebar_position: 6
+keywords:
+- Slack Bot
+- Troubleshooting
+sidebar_label: Troubleshooting
+title: Troubleshooting
+description: Common issues and solutions
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+<PlanBanner plan="Scale" />
+
+Common issues and solutions for the EventCatalog Slack Bot.
+
+## Bot doesn't respond
+
+### Check bot invitation
+
+The bot must be invited to the channel where you're trying to use it.
+
+**Solution:**
+1. Navigate to the channel
+2. Type `/invite @eventcatalog` (use your bot's actual name)
+3. Try your question again
+
+### Verify Socket Mode
+
+Socket Mode must be enabled in your Slack app settings.
+
+**Solution:**
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **Socket Mode** in the sidebar
+4. Verify it's toggled to **On**
+5. Restart the bot
+
+### Check bot logs
+
+Look for connection errors or startup issues.
+
+**Solution:**
+
+View logs based on how you're running the bot:
+
+```bash
+# Local development
+# Check terminal output
+
+# Docker
+docker compose logs -f
+
+# Docker (specific container)
+docker logs eventcatalog-slack-bot
+```
+
+Look for error messages about:
+- Missing credentials
+- Connection failures
+- License validation issues
+
+## Missing API key error
+
+The bot cannot find the API key for your configured AI provider.
+
+**Solution:**
+
+1. Check your `.env` file contains the correct variable:
+
+```bash
+# For Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# For OpenAI
+OPENAI_API_KEY=sk-...
+
+# For Google
+GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+2. Verify your config matches the environment variable:
+
+```typescript
+ai: {
+  provider: 'anthropic', // Must match your API key
+}
+```
+
+3. Restart the bot after adding the key
+
+## MCP connection errors
+
+The bot cannot connect to your EventCatalog MCP server.
+
+### Verify EventCatalog URL
+
+**Solution:**
+
+1. Check your config has the correct URL:
+
+```typescript
+eventCatalog: {
+  url: 'https://your-catalog.example.com',
+}
+```
+
+2. Verify the URL is accessible from where the bot runs:
+
+```bash
+curl https://your-catalog.example.com/docs/mcp/
+```
+
+3. For Docker deployments, see [Docker networking](/docs/development/ask-your-architecture/slack-integration/deployment#docker-networking)
+
+### Check MCP server status
+
+**Solution:**
+
+1. Visit your MCP endpoint in a browser:
+
+```
+https://your-catalog.example.com/docs/mcp/
+```
+
+2. You should see JSON output with available tools and resources
+3. If you see an error, verify:
+   - EventCatalog is running in [SSR mode](/docs/development/deployment/build-ssr-mode)
+   - You have a valid [Scale license](https://eventcatalog.cloud)
+
+### Authentication required
+
+If your EventCatalog requires authentication, add headers to your config.
+
+**Solution:**
+
+```typescript
+eventCatalog: {
+  url: 'https://your-catalog.example.com',
+  headers: {
+    'Authorization': 'Bearer your-token',
+  },
+}
+```
+
+## Permission errors
+
+The bot is missing required Slack permissions.
+
+**Solution:**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **OAuth & Permissions**
+4. Verify these **Bot Token Scopes** are added:
+   - `app_mentions:read`
+   - `chat:write`
+   - `reactions:read`
+   - `reactions:write`
+   - `channels:history`
+5. If you added new scopes, click **Reinstall to Workspace**
+6. Restart the bot
+
+## Auto-reply channels not working
+
+The bot doesn't auto-reply in configured channels.
+
+### Verify channel ID
+
+**Solution:**
+
+1. Get the correct channel ID:
+   - Right-click channel name
+   - Click **View channel details**
+   - Scroll to bottom for Channel ID
+2. Check your config uses the ID (not name):
+
+```typescript
+slack: {
+  autoReplyChannels: ['C0123456789'], // Channel ID, not #channel-name
+}
+```
+
+3. Restart the bot after changing config
+
+### Check event subscription
+
+**Solution:**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **Event Subscriptions**
+4. Verify **Enable Events** is On
+5. Check `message.channels` is in **Subscribe to bot events**
+
+## Thread context not working
+
+The bot doesn't remember previous messages in a thread.
+
+### Public channels
+
+Thread context should work automatically in public channels.
+
+**Solution:**
+
+1. Verify `channels:history` scope is added
+2. Reinstall the app if you just added the scope
+3. Restart the bot
+
+### Private channels and DMs
+
+Thread context requires additional scopes.
+
+**Solution:**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps)
+2. Select your app
+3. Click **OAuth & Permissions**
+4. Add these scopes:
+   - `groups:history` - Private channels
+   - `im:history` - Direct messages
+   - `mpim:history` - Group DMs
+5. Click **Reinstall to Workspace**
+6. Restart the bot
+
+## Docker networking issues
+
+The bot cannot reach EventCatalog running on localhost.
+
+**Solution:**
+
+See the [Docker networking guide](/docs/development/ask-your-architecture/slack-integration/deployment#docker-networking) for detailed solutions based on your setup.
+
+Quick fix for local EventCatalog:
+
+```typescript
+eventCatalog: {
+  url: 'http://host.docker.internal:3000',
+}
+```
+
+## License validation errors
+
+The bot reports an invalid or expired license.
+
+**Solution:**
+
+1. Verify your license key is correct in `.env`:
+
+```bash
+EVENTCATALOG_SCALE_LICENSE_KEY=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
+```
+
+2. Check your license status at [eventcatalog.cloud](https://eventcatalog.cloud)
+3. For expired trials, upgrade to a paid plan
+4. Restart the bot after updating the key
+
+## Getting help
+
+If you're still experiencing issues:
+
+1. Check the bot logs for detailed error messages
+2. Review the [GitHub repository](https://github.com/event-catalog/eventcatalog-slack-bot) for known issues
+3. Join the [EventCatalog Discord](https://eventcatalog.dev/discord) for community support
+4. File an issue on [GitHub](https://github.com/event-catalog/eventcatalog-slack-bot/issues) with:
+   - Bot version
+   - Error messages from logs
+   - Steps to reproduce the issue

package/dist/docs/development/ask-your-architecture/05-slack-integration/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Slack Integration",
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "slug": "development/ask-your-architecture/slack-integration",
+    "title": "Slack Integration",
+    "description": "Query your EventCatalog directly from Slack using the EventCatalog Slack Bot."
+  }
+}

package/dist/docs/development/ask-your-architecture/_category_.json

@@ -0,0 +1,12 @@
+{
+  "label": "Agents with EventCatalog",
+  "position": 8,
+  "collapsible": false,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "slug": "ask-your-architecture",
+    "title": "Ask your architecture",
+    "description": "Learn how to integrate your LLM models with EventCatalog."
+  }
+}