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
| Software | Version | Purpose | Installation |
|---|---|---|---|
| Node.js | 18.0.0+ | Slack bot runtime | curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - && sudo apt-get install -y nodejs |
| PHP | 8.2+ | Symfony backend | sudo apt-get install php8.2 php8.2-cli php8.2-xml php8.2-mbstring php8.2-sqlite3 |
| Composer | Latest | PHP dependency manager | curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer |
| npm/pnpm | Latest | Node package manager | Included 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
# 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:
# 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-keyHow to get Slack tokens:
- Go to https://api.slack.com/apps
- Create new app or select existing
- Navigate to "OAuth & Permissions" Copy Bot User OAuth Token
- Navigate to "Basic Information" Copy Signing Secret
- Navigate to "Basic Information" App-Level Tokens Generate token with
connections:writescope
2.3 Configure Backend (backend/.env)
Create https://github.com/undead2146/KnowledgeHub/blob/main/backend/.env:
# 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-secretHow to get Notion credentials:
- Go to https://www.notion.so/my-integrations
- Create new integration Copy "Internal Integration Token"
- Create three databases (Knowledge, Categories, Digests)
- Share each database with your integration
- Copy database IDs from URLs (32-char hex after last slash)
3. Database Setup
3.1 Run Doctrine Migrations
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.db3.2 Verify Database Schema
# Check that tables were created
php bin/console doctrine:schema:validateExpected 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)
# Load sample knowledge items and categories
php bin/console app:seed-poc-data4. Notion Setup
4.1 Create Notion Integration
- Visit https://www.notion.so/my-integrations
- Click "New integration"
- Name: "Yappa Knowledge Hub"
- Associated workspace: Select your workspace
- Capabilities: Read content, Update content, Insert content
- Copy the "Internal Integration Token" (starts with
ntn_)
4.2 Create Notion Databases
Database 1: Knowledge Items
- Create new database in Notion
- Add these properties:
| Property Name | Type | Options |
|---|---|---|
| Title | Title | - |
| Content | Text | - |
| Status | Status | Draft, Review, Published, Archived |
| Tags | Multi-select | - |
| Categories | Relation | Link to Categories database |
| Target Groups | Multi-select | Developers, Marketers, CEO, Service Desk, Sales, HR |
| Source URL | URL | - |
| Slack ID | Text | - |
| AI Summary | Text | - |
| TS | Text | - |
| Channel | Text | - |
- Share database with integration (click "..." Add connections)
- Copy database ID from URL
Database 2: Categories
- Create new database
- Add properties:
| Property Name | Type | Options |
|---|---|---|
| Name | Title | - |
| Description | Text | - |
| Icon | Text | - |
| Default Target Groups | Multi-select | Same as Knowledge |
| Digest Frequency | Select | Daily, Weekly, Monthly |
| Active | Checkbox | - |
| Knowledge Count | Rollup | From Categories relation |
- Share with integration
- Copy database ID
Database 3: Digests
- Create new database
- Add properties:
| Property Name | Type | Options |
|---|---|---|
| Title | Title | - |
| Category | Relation | Link to Categories |
| Period Start | Date | - |
| Period End | Date | - |
| Items Count | Number | - |
| Target Groups | Multi-select | Same as Knowledge |
| Status | Status | Generating, Sent, Failed |
- Share with integration
- Copy database ID
4.3 Update Environment Variables
Add the three database IDs to backend/.env:
NOTION_DATABASE_KNOWLEDGE=your-knowledge-db-id
NOTION_DATABASE_CATEGORIES=your-categories-db-id
NOTION_DATABASE_DIGESTS=your-digests-db-id5. Slack Setup
5.1 Create Slack App
- Go to https://api.slack.com/apps
- Click "Create New App" "From an app manifest"
- Select your workspace
- Paste contents of
/home/ubuntu/yappa-knowledge-hub/slack-app-manifest.yaml - Review permissions and create app
5.2 Configure App Settings
OAuth & Permissions:
- Bot Token Scopes (should be set by manifest):
app_mentions:readchannels:historychannels:readchat:writecommandsfiles:readreactions:readusers:read
Event Subscriptions:
- Enable Events: On
- Subscribe to bot events:
app_home_openedapp_mentionmessage.channelsreaction_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
- Go to "Socket Mode" in sidebar
- Enable Socket Mode
- Generate App-Level Token with
connections:writescope - Copy token (starts with
xapp-)
5.4 Install App to Workspace
- Go to "Install App" in sidebar
- Click "Install to Workspace"
- Authorize the app
- Copy "Bot User OAuth Token" (starts with
xoxb-)
6. Local Development
6.1 Start Development Servers
Terminal 1 - Slack Bot:
cd /home/ubuntu/yappa-knowledge-hub
npm run devExpected output:
Bolt app is running on port 3000!
Express API running on port 3001Terminal 2 - Symfony Backend:
cd /home/ubuntu/yappa-knowledge-hub/backend
symfony server:startOr without Symfony CLI:
php -S localhost:8000 -t public/Expected output:
[OK] Web server listening on http://127.0.0.1:80006.2 Verify Services Are Running
# 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/verify6.3 Test Basic Functionality
- Open Slack workspace
- Find "Yappa Knowledge Hub" app in Apps section
- Click on app to open Home tab
- Try
/knowledgecommand - Test "Quick Add Knowledge" shortcut (lightning bolt icon)
6.4 Development Workflow
Watch Mode (TypeScript):
npm run devBuild TypeScript:
npm run buildType Checking:
npm run typecheckClear Symfony Cache:
cd backend
php bin/console cache:clear7. Testing
7.1 Run Test Suites
All Node.js Tests:
npm testSpecific Test Suites:
# 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:watchPHP Tests:
cd backend
./vendor/bin/phpunit7.2 Test Coverage
Generate Coverage Report:
npm run test:coverageView HTML report at coverage/index.html
PHP Coverage:
cd backend
./vendor/bin/phpunit --coverage-html coverage7.3 Manual Testing Checklist
- [ ]
/knowledgecommand 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:
# In .env
NODE_ENV=developmentSymfony:
# In backend/.env
APP_ENV=dev
APP_DEBUG=true8.2 View Logs
Slack Bot Logs:
# Console output when running npm run dev
# Or if using PM2:
pm2 logs yappa-botSymfony Logs:
tail -f https://github.com/undead2146/KnowledgeHub/blob/main/backend/var/log/dev.logNotion Sync Logs:
tail -f /tmp/notion-sync.log8.3 Common Debug Commands
Check running processes:
ps aux | grep node
ps aux | grep phpCheck port usage:
lsof -i :3000
lsof -i :3001
lsof -i :8000Test API endpoints:
# 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:
- Go to https://api.slack.com/apps
- Select your app
- Click "Event Subscriptions" or "Interactivity & Shortcuts"
- View recent requests and responses
Test Slack Payloads:
// 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 site9.2 Key Files
Configuration:
.env- Slack bot environment variablesbackend/.env- Symfony environment variablesslack-app-manifest.yaml- Slack app configurationtsconfig.json- TypeScript configurationbackend/config/services.yaml- Symfony services
Entry Points:
src/app.ts- Slack bot main filebackend/public/index.php- Symfony entry point
Database:
backend/migrations/- Doctrine migrationsbackend/var/data.db- SQLite database file
9.3 Important Services
Slack Bot Services:
src/services/knowledge.ts- CRUD operations for knowledgesrc/services/categories.ts- Category management with cachingsrc/services/urlScraper.ts- Extract metadata from URLssrc/services/homeRefresh.ts- Refresh user home pages
Backend Services:
NotionClient.php- Low-level Notion API clientNotionKnowledgeService.php- Knowledge operations in NotionNotionSyncService.php- Bidirectional sync logicSlackHomeRefreshService.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 scraper10.2 Adding New Features
1. Create Feature Branch:
git checkout -b feature/feature-name2. Implement Feature:
- Add code to appropriate service/handler
- Write unit tests
- Update documentation
3. Test Thoroughly:
npm test
cd backend && ./vendor/bin/phpunit4. Commit and Push:
git add .
git commit -m "feat: description"
git push origin feature/feature-name10.3 Adding New Slack Commands
1. Update Slack Manifest:
# slack-app-manifest.yaml
slash_commands:
- command: /your-command
description: Command description
usage_hint: "[arguments]"2. Add Handler:
// 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:
// 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):
// backend/src/Service/YourService.php
namespace App\Service;
class YourService
{
public function doSomething(): void
{
// Implementation
}
}3. Test Endpoint:
curl http://localhost:8000/api/your-endpoint11. Deployment
11.1 Production Environment Setup
Install PM2:
npm install -g pm2Start Services with PM2:
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 startupStart Symfony Backend:
cd /home/ubuntu/yappa-knowledge-hub/backend
# Using Symfony CLI (recommended)
symfony server:start -d
# Or using systemd service
sudo systemctl start yappa-backend11.2 Configure Auto-Sync
Create Cron Job:
crontab -eAdd Sync Schedule:
# 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>&1Verify Cron Job:
crontab -l11.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:
# PM2 status
pm2 status
# View logs
pm2 logs yappa-bot
# Restart service
pm2 restart yappa-botHealth Checks:
# Slack bot
curl http://localhost:3001/health
# Backend
curl http://localhost:8000/api/notion/verifyLog Rotation:
# 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:
- Check bot is running:
pm2 statusorps aux | grep node - Verify tokens in
.envare correct - Check Slack app is installed to workspace
- View logs:
pm2 logs yappa-bot - Test Socket Mode connection
Problem: "Port already in use" error
Solutions:
# Find process using port
lsof -i :3000
# Kill process
kill -9 <PID>
# Or use different port
PORT=3002 npm startProblem: Modal not opening
Solutions:
- Check Slack app manifest includes interactivity
- Verify shortcut IDs match in code
- Check logs for errors
- Test with simple modal first
12.2 Backend Issues
Problem: Notion API errors
Solutions:
- Verify API key:
curl http://localhost:8000/api/notion/verify - Check database IDs are correct
- Ensure databases are shared with integration
- Check rate limits (3 req/sec)
- View Symfony logs:
tail -f backend/var/log/dev.log
Problem: Database errors
Solutions:
# 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:validateProblem: Sync not working
Solutions:
- Test sync manually:
curl -X POST http://localhost:8000/api/notion/sync/from-notion -d '{"force": true}' - Check cron job:
crontab -l - View sync logs:
tail -f /tmp/notion-sync.log - Verify Notion connection
- Check database permissions
12.3 Common Error Messages
"Invalid token" from Slack
- Token expired or incorrect
- Regenerate tokens in Slack app settings
- Update
.envfile
"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 installorcomposer install - Clear cache and rebuild
12.4 Performance Issues
Slow response times:
- Check Notion API rate limits
- Enable caching (categories already cached)
- Optimize database queries
- Use pagination for large lists
High memory usage:
- Restart services:
pm2 restart yappa-bot - Check for memory leaks in logs
- Limit concurrent operations
- Increase server resources
Known Issues
Current Limitations
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
Socket Mode Only
- Impact: Not suitable for production at scale
- Workaround: Switch to HTTP mode for production
- Status: HTTP mode configuration needed
No Rate Limiting
- Impact: Potential API abuse
- Workaround: Monitor usage manually
- Status: Planned for MVP
AI Summaries Disabled
- Impact: No automatic content summarization
- Workaround: Manual summaries or add OpenAI key
- Status: Service implemented, needs API key
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_metadatausage
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