Yappa Knowledge Hub - Implementation Guide

Last Updated: 2026-05-15 Version: 4.0 Status: MVP Complete

Quick reference for local development after initial setup. For first-time setup (Notion databases, Slack app, environment configuration), see the Complete Setup Guide.

---

1. Prerequisites

Software	Version	Purpose
Node.js	18.0.0+	Slack bot runtime
PHP	8.2+	Symfony backend
Composer	Latest	PHP dependency manager
npm	Latest	Node package manager
SQLite3	3.x	Database engine

Accounts Required

• Slack workspace with admin permissions
• Notion workspace with admin access
• OpenAI API key for AI summaries

---

2. Environment Setup

2.1 Clone and Install

cd /home/ubuntu/yappa-knowledge-hub
npm install
cd backend && composer install && cd ..

2.2 Configure Environment Variables

Two .env files are required. See the Complete Setup Guide for full details on obtaining tokens and database IDs.

backend/.env — Backend configuration:

APP_ENV=dev
APP_SECRET=generate-random-32-char-string
DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"
DEFAULT_URI=http://localhost:8001

# Notion API
NOTION_API_KEY=ntn_your-notion-key
NOTION_VERSION=2022-06-28
NOTION_DATABASE_KNOWLEDGE=your-knowledge-db-id
NOTION_DATABASE_CATEGORIES=your-categories-db-id
NOTION_DATABASE_DIGESTS=your-digests-db-id
NOTION_DATABASE_SUBSCRIPTIONS=your-subscriptions-db-id

# AI
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4o-mini

# Auth — must match BACKEND_API_TOKEN in slack/.env
SYNC_API_TOKEN=your-sync-token

slack/.env — Slack bot configuration:

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-level-token

PORT=4000
API_PORT=4001

API_BASE_URL=http://localhost:8001/api
BACKEND_API_TOKEN=your-sync-token    # Must match SYNC_API_TOKEN above

NODE_ENV=development

2.3 Initialize Database

cd backend
php bin/console doctrine:database:create
php bin/console doctrine:schema:create
php bin/console doctrine:schema:validate

Expected: [Mapping] OK and [Database] OK.

---

3. Start Development Servers

Terminal 1 — Symfony Backend:

cd backend && php -S 0.0.0.0:8001 -t public

Terminal 2 — Slack Bot:

cd slack && npm run dev

Or use the combined script from the project root:

./start_servers.sh

Verify

curl http://localhost:8001/api/categories -H "Authorization: Bearer $BACKEND_API_TOKEN"

Ports

Port	Service	Purpose
8001	Symfony	REST API (/api/*)
4000	Bolt	Socket Mode WebSocket to Slack
4001	Express	Digest delivery from backend

---

4. Development Commands

Slack Bot

cd slack
npm run dev          # Watch mode (tsx --watch)
npm run build        # Compile TypeScript
npm run typecheck    # Type checking
npm test             # Jest tests

Backend

cd backend
php bin/console cache:clear
./vendor/bin/phpunit # PHPUnit tests

E2E Tests

./scripts/ensure-test-env.sh  # MUST run first
cd e2e-tests && npx playwright test

E2E tests require mock mode (NOTION_MOCK=true, OPENAI_MOCK=true) and a test database (data_test.db).

---

5. Project Structure

yappa-knowledge-hub/
├── slack/                    # Slack Bot (TypeScript/Node.js)
│   └── src/
│       ├── app.ts            # Entry point, Bolt app init
│       ├── handlers/         # Event, action, submission, shortcut handlers
│       │   ├── actions/      # categorySettings, distribution, subscription
│       │   ├── home/         # Dynamic App Home rendering
│       │   ├── submissions/  # digestHandler
│       │   └── api/          # sendDigest (Express endpoint)
│       ├── views/            # Block Kit view builders
│       │   ├── home/         # dynamicHomeTab, categoriesView
│       │   └── modals/       # knowledge, categories, digest modals
│       ├── services/         # Backend API clients
│       ├── constants/        # All IDs and strings centralized
│       ├── utils/            # API client, logger, helpers
│       ├── middleware/       # Error handler
│       ├── i18n/             # Dutch translations
│       └── types/            # TypeScript type definitions
├── backend/                  # Symfony Backend (PHP)
│   └── src/
│       ├── Controller/       # REST controllers
│       ├── Entity/           # Doctrine entities
│       ├── Repository/       # Doctrine repositories
│       ├── Service/          # Domain services
│       └── Constants/        # No magic strings
├── e2e-tests/                # Playwright E2E tests
├── docs/                     # VitePress documentation
└── scripts/                  # Utility scripts

---

6. Troubleshooting

Slack Bot Issues

• Bot not responding: Check tokens in slack/.env, verify app is installed
• "server explicit disconnect": SLACK_APP_TOKEN expired — regenerate from Settings > Basic Information > App-Level Tokens
• Port in use: lsof -i :4000 (Bolt) or lsof -i :4001 (Express API)
• Categories not loading: Verify backend is running and API_BASE_URL is correct

Backend Issues

• Notion API errors: Verify API key, database IDs, database sharing
• Database errors: cd backend && php bin/console doctrine:schema:validate
• Auth errors (401): Check SYNC_API_TOKEN matches BACKEND_API_TOKEN in slack/.env

Reset Database

cd backend
php bin/console doctrine:database:drop --force
php bin/console doctrine:database:create
php bin/console doctrine:schema:create

---

Additional Resources

• Complete Setup Guide — Notion, Slack, backend, env vars
• Slack API Documentation
• Notion API Documentation
• Symfony Documentation