Skip to content

Yappa Knowledge Hub - Implementation Guide

Last Updated: 2026-02-20 Version: 2.0 Status: Production Ready

This guide provides accurate, tested instructions for setting up and developing the Yappa Knowledge Hub.


1. Prerequisites

Required Software

SoftwareVersionPurposeInstallation
Node.js18.0.0+Slack bot runtimecurl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - && sudo apt-get install -y nodejs
PHP8.2+Symfony backendsudo apt-get install php8.2 php8.2-cli php8.2-xml php8.2-mbstring php8.2-sqlite3
ComposerLatestPHP dependency managercurl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer
npm/pnpmLatestNode package managerIncluded with Node.js (pnpm: npm install -g pnpm)

Optional Tools

  • Symfony CLI: For easier development server management
  • PM2: For production process management
  • Git: For version control

Accounts Required

  • Slack workspace with admin permissions
  • Notion account with API access
  • (Optional) OpenAI API key for AI summaries

2. Environment Setup

2.1 Clone and Install

bash
# Navigate to project directory
cd /home/ubuntu/yappa-knowledge-hub

# Install Node.js dependencies
npm install
# OR if using pnpm
pnpm install

# Install PHP dependencies
cd backend
composer install
cd ..

2.2 Configure Slack Bot (.env in root)

Create /home/ubuntu/yappa-knowledge-hub/.env:

bash
#  Slack Bot Configuration (Required)
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_SIGNING_SECRET=your-signing-secret-here
SLACK_APP_TOKEN=xapp-your-app-level-token-here

#  Node.js App
PORT=3000
NODE_ENV=development

#  Backend API
API_BASE_URL=http://localhost:8000/api

#  AI Provider (Optional)
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

How to get Slack tokens:

  1. Go to https://api.slack.com/apps
  2. Create new app or select existing
  3. Navigate to "OAuth & Permissions" Copy Bot User OAuth Token
  4. Navigate to "Basic Information" Copy Signing Secret
  5. Navigate to "Basic Information" App-Level Tokens Generate token with connections:write scope

2.3 Configure Backend (backend/.env)

Create https://github.com/undead2146/KnowledgeHub/blob/main/backend/.env:

bash
#  Symfony Environment
APP_ENV=dev
APP_SECRET=generate-random-32-char-string

#  Database (SQLite)
DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"

#  Notion API
NOTION_API_KEY=ntn_your-notion-integration-key
NOTION_VERSION=2022-06-28
NOTION_DATABASE_KNOWLEDGE=306e292a15d58004a8cbc222dcd48bb2
NOTION_DATABASE_CATEGORIES=306e292a15d5805dae13e64bed8519c5
NOTION_DATABASE_DIGESTS=306e292a15d580d7a0f6fe8421baff10

#  Slack Integration
SLACK_BOT_URL=http://localhost:3001

#  Optional: Webhook Security
NOTION_WEBHOOK_SECRET=your-webhook-secret

How to get Notion credentials:

  1. Go to https://www.notion.so/my-integrations
  2. Create new integration Copy "Internal Integration Token"
  3. Create three databases (Knowledge, Categories, Digests)
  4. Share each database with your integration
  5. Copy database IDs from URLs (32-char hex after last slash)

3. Database Setup

3.1 Run Doctrine Migrations

bash
cd /home/ubuntu/yappa-knowledge-hub/backend

# Create database and run migrations
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate

# Verify database was created
ls -lh var/data.db

3.2 Verify Database Schema

bash
# Check that tables were created
php bin/console doctrine:schema:validate

Expected output:

[Mapping]  OK - The mapping files are correct.
[Database] OK - The database schema is in sync with the mapping files.

3.3 Seed Test Data (Optional)

bash
# Load sample knowledge items and categories
php bin/console app:seed-poc-data

4. Notion Setup

4.1 Create Notion Integration

  1. Visit https://www.notion.so/my-integrations
  2. Click "New integration"
  3. Name: "Yappa Knowledge Hub"
  4. Associated workspace: Select your workspace
  5. Capabilities: Read content, Update content, Insert content
  6. Copy the "Internal Integration Token" (starts with ntn_)

4.2 Create Notion Databases

Database 1: Knowledge Items

  1. Create new database in Notion
  2. Add these properties:
Property NameTypeOptions
TitleTitle-
ContentText-
StatusStatusDraft, Review, Published, Archived
TagsMulti-select-
CategoriesRelationLink to Categories database
Target GroupsMulti-selectDevelopers, Marketers, CEO, Service Desk, Sales, HR
Source URLURL-
Slack IDText-
AI SummaryText-
TSText-
ChannelText-
  1. Share database with integration (click "..." Add connections)
  2. Copy database ID from URL

Database 2: Categories

  1. Create new database
  2. Add properties:
Property NameTypeOptions
NameTitle-
DescriptionText-
IconText-
Default Target GroupsMulti-selectSame as Knowledge
Digest FrequencySelectDaily, Weekly, Monthly
ActiveCheckbox-
Knowledge CountRollupFrom Categories relation
  1. Share with integration
  2. Copy database ID

Database 3: Digests

  1. Create new database
  2. Add properties:
Property NameTypeOptions
TitleTitle-
CategoryRelationLink to Categories
Period StartDate-
Period EndDate-
Items CountNumber-
Target GroupsMulti-selectSame as Knowledge
StatusStatusGenerating, Sent, Failed
  1. Share with integration
  2. Copy database ID

4.3 Update Environment Variables

Add the three database IDs to backend/.env:

bash
NOTION_DATABASE_KNOWLEDGE=your-knowledge-db-id
NOTION_DATABASE_CATEGORIES=your-categories-db-id
NOTION_DATABASE_DIGESTS=your-digests-db-id

5. Slack Setup

5.1 Create Slack App

  1. Go to https://api.slack.com/apps
  2. Click "Create New App" "From an app manifest"
  3. Select your workspace
  4. Paste contents of /home/ubuntu/yappa-knowledge-hub/slack-app-manifest.yaml
  5. Review permissions and create app

5.2 Configure App Settings

OAuth & Permissions:

  • Bot Token Scopes (should be set by manifest):
    • app_mentions:read
    • channels:history
    • channels:read
    • chat:write
    • commands
    • files:read
    • reactions:read
    • users:read

Event Subscriptions:

  • Enable Events: On
  • Subscribe to bot events:
    • app_home_opened
    • app_mention
    • message.channels
    • reaction_added

Interactivity & Shortcuts:

  • Enable Interactivity: On
  • Request URL: (Not needed for Socket Mode)
  • Shortcuts:
    • Message shortcut: "Save to Knowledge Hub"
    • Global shortcut: "Quick Add Knowledge"

App Home:

  • Home Tab: Enabled
  • Messages Tab: Enabled

5.3 Enable Socket Mode

  1. Go to "Socket Mode" in sidebar
  2. Enable Socket Mode
  3. Generate App-Level Token with connections:write scope
  4. Copy token (starts with xapp-)

5.4 Install App to Workspace

  1. Go to "Install App" in sidebar
  2. Click "Install to Workspace"
  3. Authorize the app
  4. Copy "Bot User OAuth Token" (starts with xoxb-)

6. Local Development

6.1 Start Development Servers

Terminal 1 - Slack Bot:

bash
cd /home/ubuntu/yappa-knowledge-hub
npm run dev

Expected output:

 Bolt app is running on port 3000!
 Express API running on port 3001

Terminal 2 - Symfony Backend:

bash
cd /home/ubuntu/yappa-knowledge-hub/backend
symfony server:start

Or without Symfony CLI:

bash
php -S localhost:8000 -t public/

Expected output:

[OK] Web server listening on http://127.0.0.1:8000

6.2 Verify Services Are Running

bash
# Check Slack bot health
curl http://localhost:3001/health

# Check backend health
curl http://localhost:8000/api/notion/verify

# Check Notion connection
curl http://localhost:8000/api/notion/verify

6.3 Test Basic Functionality

  1. Open Slack workspace
  2. Find "Yappa Knowledge Hub" app in Apps section
  3. Click on app to open Home tab
  4. Try /knowledge command
  5. Test "Quick Add Knowledge" shortcut (lightning bolt icon)

6.4 Development Workflow

Watch Mode (TypeScript):

bash
npm run dev

Build TypeScript:

bash
npm run build

Type Checking:

bash
npm run typecheck

Clear Symfony Cache:

bash
cd backend
php bin/console cache:clear

7. Testing

7.1 Run Test Suites

All Node.js Tests:

bash
npm test

Specific Test Suites:

bash
# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# API tests
npm run test:api

# E2E tests
npm run test:e2e

# Watch mode
npm run test:watch

PHP Tests:

bash
cd backend
./vendor/bin/phpunit

7.2 Test Coverage

Generate Coverage Report:

bash
npm run test:coverage

View HTML report at coverage/index.html

PHP Coverage:

bash
cd backend
./vendor/bin/phpunit --coverage-html coverage

7.3 Manual Testing Checklist

  • [ ] /knowledge command opens dashboard
  • [ ] Add knowledge via modal
  • [ ] Edit existing knowledge
  • [ ] Delete knowledge
  • [ ] Create category
  • [ ] Assign knowledge to category
  • [ ] Search knowledge items
  • [ ] Message shortcut saves message
  • [ ] Global shortcut opens form
  • [ ] Emoji reactions trigger save (:brain:, :bulb:, :bookmark:)
  • [ ] URL detection and scraping
  • [ ] File detection prompt
  • [ ] App Home displays stats
  • [ ] Notion sync works bidirectionally

8. Debugging

8.1 Enable Debug Logging

Slack Bot:

bash
# In .env
NODE_ENV=development

Symfony:

bash
# In backend/.env
APP_ENV=dev
APP_DEBUG=true

8.2 View Logs

Slack Bot Logs:

bash
# Console output when running npm run dev
# Or if using PM2:
pm2 logs yappa-bot

Symfony Logs:

bash
tail -f https://github.com/undead2146/KnowledgeHub/blob/main/backend/var/log/dev.log

Notion Sync Logs:

bash
tail -f /tmp/notion-sync.log

8.3 Common Debug Commands

Check running processes:

bash
ps aux | grep node
ps aux | grep php

Check port usage:

bash
lsof -i :3000
lsof -i :3001
lsof -i :8000

Test API endpoints:

bash
# Test knowledge creation
curl -X POST http://localhost:8000/api/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Knowledge",
    "content": "Test content",
    "targetGroups": ["developers"]
  }'

# Test Notion sync
curl -X POST http://localhost:8000/api/notion/sync/from-notion \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

8.4 Debug Slack Interactions

View Slack API Logs:

  1. Go to https://api.slack.com/apps
  2. Select your app
  3. Click "Event Subscriptions" or "Interactivity & Shortcuts"
  4. View recent requests and responses

Test Slack Payloads:

javascript
// Add to src/app.ts for debugging
app.use(async ({ payload, next }) => {
  console.log('Received payload:', JSON.stringify(payload, null, 2));
  await next();
});

9. Code Structure

9.1 Project Layout

/home/ubuntu/yappa-knowledge-hub/
 src/                          # Slack Bot (TypeScript/Node.js)
    app.ts                    # Main entry point
    api/                      # Express API routes
       slack.ts              # Home refresh endpoints
    handlers/                 # Slack event handlers
       commands.ts           # Slash commands
       events.ts             # Message/file events
       home.ts               # App Home tab
       shortcuts.ts          # Message/global shortcuts
       submissions.ts        # Modal submissions
    services/                 # Business logic
        categories.ts         # Category operations
        knowledge.ts          # Knowledge operations
        urlScraper.ts         # URL metadata extraction
        homeRefresh.ts        # Home page refresh

 backend/                      # Symfony Backend (PHP)
    src/
       Controller/           # API endpoints
          KnowledgeController.php
          CategoryController.php
          NotionSyncController.php
       Service/              # Business services
          Notion/
              NotionClient.php
              NotionKnowledgeService.php
              NotionCategoryService.php
              NotionSyncService.php
       Entity/               # Doctrine entities
          Knowledge.php
          Category.php
       Repository/           # Data repositories
           KnowledgeRepository.php
           CategoryRepository.php
    migrations/               # Database migrations
    var/
        data.db               # SQLite database

 tests/                        # Test suites
    unit/                     # Unit tests
    integration/              # Integration tests
    api/                      # API tests
    e2e/                      # End-to-end tests

 docs/                         # Documentation
     .vitepress/               # VitePress site

9.2 Key Files

Configuration:

  • .env - Slack bot environment variables
  • backend/.env - Symfony environment variables
  • slack-app-manifest.yaml - Slack app configuration
  • tsconfig.json - TypeScript configuration
  • backend/config/services.yaml - Symfony services

Entry Points:

  • src/app.ts - Slack bot main file
  • backend/public/index.php - Symfony entry point

Database:

  • backend/migrations/ - Doctrine migrations
  • backend/var/data.db - SQLite database file

9.3 Important Services

Slack Bot Services:

  • src/services/knowledge.ts - CRUD operations for knowledge
  • src/services/categories.ts - Category management with caching
  • src/services/urlScraper.ts - Extract metadata from URLs
  • src/services/homeRefresh.ts - Refresh user home pages

Backend Services:

  • NotionClient.php - Low-level Notion API client
  • NotionKnowledgeService.php - Knowledge operations in Notion
  • NotionSyncService.php - Bidirectional sync logic
  • SlackHomeRefreshService.php - Trigger Slack home refreshes

10. Contributing

10.1 Development Guidelines

Code Style:

  • TypeScript: 2-space indentation, ESM modules
  • PHP: PSR-12 standard, 4-space indentation
  • Use async/await for asynchronous operations
  • Add JSDoc/PHPDoc comments for public functions

Commit Messages:

feat: add AI summary generation
fix: resolve category display bug
docs: update setup instructions
test: add unit tests for URL scraper

10.2 Adding New Features

1. Create Feature Branch:

bash
git checkout -b feature/feature-name

2. Implement Feature:

  • Add code to appropriate service/handler
  • Write unit tests
  • Update documentation

3. Test Thoroughly:

bash
npm test
cd backend && ./vendor/bin/phpunit

4. Commit and Push:

bash
git add .
git commit -m "feat: description"
git push origin feature/feature-name

10.3 Adding New Slack Commands

1. Update Slack Manifest:

yaml
# slack-app-manifest.yaml
slash_commands:
  - command: /your-command
    description: Command description
    usage_hint: "[arguments]"

2. Add Handler:

typescript
// src/handlers/commands.ts
app.command('/your-command', async ({ command, ack, client }) => {
  await ack();
  // Implementation
});

3. Reinstall Slack App:

  • Update manifest in Slack App settings
  • Reinstall to workspace

10.4 Adding New API Endpoints

1. Create Controller:

php
// backend/src/Controller/YourController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;

#[Route('/api/your-endpoint')]
class YourController extends AbstractController
{
    #[Route('', methods: ['GET'])]
    public function index(): JsonResponse
    {
        return $this->json(['status' => 'ok']);
    }
}

2. Add Service (if needed):

php
// backend/src/Service/YourService.php
namespace App\Service;

class YourService
{
    public function doSomething(): void
    {
        // Implementation
    }
}

3. Test Endpoint:

bash
curl http://localhost:8000/api/your-endpoint

11. Deployment

11.1 Production Environment Setup

Install PM2:

bash
npm install -g pm2

Start Services with PM2:

bash
cd /home/ubuntu/yappa-knowledge-hub

# Start Slack bot
pm2 start dist/app.js --name yappa-bot

# Save PM2 configuration
pm2 save

# Setup PM2 to start on boot
pm2 startup

Start Symfony Backend:

bash
cd /home/ubuntu/yappa-knowledge-hub/backend

# Using Symfony CLI (recommended)
symfony server:start -d

# Or using systemd service
sudo systemctl start yappa-backend

11.2 Configure Auto-Sync

Create Cron Job:

bash
crontab -e

Add Sync Schedule:

bash
# Sync every 2 minutes
*/2 * * * * curl -X POST http://localhost:8000/api/notion/sync/from-notion -H "Content-Type: application/json" -d '{"force": false}' >> /tmp/notion-sync.log 2>&1

Verify Cron Job:

bash
crontab -l

11.3 Production Checklist

  • [ ] Environment variables set correctly
  • [ ] Database migrations applied
  • [ ] Services running with PM2/systemd
  • [ ] Auto-sync cron job configured
  • [ ] Logs rotating properly
  • [ ] Health endpoints responding
  • [ ] Slack app in production mode (HTTP mode, not Socket Mode)
  • [ ] Notion webhooks configured (optional)
  • [ ] SSL certificates installed
  • [ ] Firewall rules configured
  • [ ] Monitoring alerts set up

11.4 Monitoring

Check Service Status:

bash
# PM2 status
pm2 status

# View logs
pm2 logs yappa-bot

# Restart service
pm2 restart yappa-bot

Health Checks:

bash
# Slack bot
curl http://localhost:3001/health

# Backend
curl http://localhost:8000/api/notion/verify

Log Rotation:

bash
# Setup logrotate for sync logs
sudo nano /etc/logrotate.d/yappa-sync

# Add configuration:
/tmp/notion-sync.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}

12. Troubleshooting

12.1 Slack Bot Issues

Problem: Bot not responding to commands

Solutions:

  1. Check bot is running: pm2 status or ps aux | grep node
  2. Verify tokens in .env are correct
  3. Check Slack app is installed to workspace
  4. View logs: pm2 logs yappa-bot
  5. Test Socket Mode connection

Problem: "Port already in use" error

Solutions:

bash
# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
PORT=3002 npm start

Problem: Modal not opening

Solutions:

  1. Check Slack app manifest includes interactivity
  2. Verify shortcut IDs match in code
  3. Check logs for errors
  4. Test with simple modal first

12.2 Backend Issues

Problem: Notion API errors

Solutions:

  1. Verify API key: curl http://localhost:8000/api/notion/verify
  2. Check database IDs are correct
  3. Ensure databases are shared with integration
  4. Check rate limits (3 req/sec)
  5. View Symfony logs: tail -f backend/var/log/dev.log

Problem: Database errors

Solutions:

bash
# Recreate database
cd backend
rm var/data.db
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate

# Validate schema
php bin/console doctrine:schema:validate

Problem: Sync not working

Solutions:

  1. Test sync manually: curl -X POST http://localhost:8000/api/notion/sync/from-notion -d '{"force": true}'
  2. Check cron job: crontab -l
  3. View sync logs: tail -f /tmp/notion-sync.log
  4. Verify Notion connection
  5. Check database permissions

12.3 Common Error Messages

"Invalid token" from Slack

  • Token expired or incorrect
  • Regenerate tokens in Slack app settings
  • Update .env file

"Database not found" from Notion

  • Database ID incorrect
  • Database not shared with integration
  • Check NOTION_DATABASE_* variables

"Connection refused" errors

  • Service not running
  • Wrong port number
  • Firewall blocking connection

"Module not found" errors

  • Dependencies not installed
  • Run npm install or composer install
  • Clear cache and rebuild

12.4 Performance Issues

Slow response times:

  1. Check Notion API rate limits
  2. Enable caching (categories already cached)
  3. Optimize database queries
  4. Use pagination for large lists

High memory usage:

  1. Restart services: pm2 restart yappa-bot
  2. Check for memory leaks in logs
  3. Limit concurrent operations
  4. Increase server resources

Known Issues

Current Limitations

  1. User Tracking Not Implemented

    • Impact: Home refresh won't reach all users automatically
    • Workaround: Users manually refresh by opening Home tab
    • Status: Planned for MVP
  2. Socket Mode Only

    • Impact: Not suitable for production at scale
    • Workaround: Switch to HTTP mode for production
    • Status: HTTP mode configuration needed
  3. No Rate Limiting

    • Impact: Potential API abuse
    • Workaround: Monitor usage manually
    • Status: Planned for MVP
  4. AI Summaries Disabled

    • Impact: No automatic content summarization
    • Workaround: Manual summaries or add OpenAI key
    • Status: Service implemented, needs API key
  5. Digest Generation Manual

    • Impact: No automated periodic reports
    • Workaround: Generate manually via API
    • Status: Planned for MVP

Platform Constraints

Slack Limitations:

  • Modal limit: 10 input blocks per view
  • private_metadata: 3000 bytes max
  • Static select: 100 options max
  • Socket Mode: Development only

Notion Limitations:

  • Rate limit: 3 requests/second
  • Rich text: 2000 chars per block
  • Query results: 100 per request
  • Webhook delay: 1-5 seconds

Workarounds

Large Category Lists:

  • Use external select with search
  • Implement pagination
  • Cache frequently used categories

Modal Size Limits:

  • Split into multiple modals
  • Use external data sources
  • Minimize private_metadata usage

Notion Rate Limits:

  • Implement request queuing
  • Add retry logic with backoff
  • Batch operations where possible

Additional Resources

Documentation

Project Documentation

  • /project/PRD.md - Product Requirements
  • /home/ubuntu/yappa-knowledge-hub/readme.md - Project README
  • /DEPLOYMENT.md - Deployment Guide

Support

  • GitHub Issues: Create issue for bugs or feature requests
  • Project Maintainer: Check readme.md for contact info

Document Version: 2.0 Last Updated: 2026-02-20 Maintained By: Yappa Development Team