Yappa Knowledge Hub - POC Documentation

Version: 1.0 Status: Proof of Concept Purpose: Validate Slack integration patterns before building the full MVP

What is This POC?

This is a working prototype of the Yappa Knowledge Hub - a Slack-integrated knowledge management system. The POC demonstrates the complete workflow from knowledge capture through AI-powered digest delivery, validating the concept before investing in the full 12-week/6-sprint MVP.

This is NOT production software. It's designed to:

Test user experience and interaction patterns
Validate technical architecture decisions
Gather feedback on features and workflows
Identify which features resonate with users
Inform MVP prioritization

Architecture


                      INPUT LAYER (Slack)

   Slash commands (/knowledge)
   Message shortcuts (right-click menu)
   Global shortcuts ( lightning menu)
   URL detection (automatic scraping)
   File upload detection
   Emoji reactions (   )
   App Home tab



                   PROCESSING LAYER

  Node.js Bot (@slack/bolt)    Symfony API (REST)
   Event handlers                 Knowledge CRUD
   Modal logic                    Category management
   URL scraping                   AI summary generation
   Socket Mode                    Digest generation
                                   Doctrine ORM



                   DATA LAYER (SQLite)

   knowledge (items with content, tags, metadata)
   category (thematic lists with icons)
   Target groups, URLs, summaries



                    OUTPUT LAYER (Slack)

   Direct messages (confirmations)
   Ephemeral messages (search results, prompts)
   Channel messages (shared knowledge)
   Modals (dashboards, forms)
   Digests (AI-summarized, target-group-specific)

Technology Stack

Frontend (Slack Interface)

Slack Bolt SDK (Node.js) v3.17.1
Socket Mode (no webhooks needed)
Block Kit (rich UI components)

Backend API

Symfony 7.2 (PHP 8.2+)
API Platform 4.1 (REST with auto-docs)
Doctrine ORM 3.6

Database

SQLite (file-based, perfect for POC)
Location: backend/var/data.db

Additional Services

Axios (HTTP client)
Cheerio (web scraping)
Mock AI summaries (OpenAI-compatible)

Quick Start

New to the project? Follow the complete setup guide: /setup/setup

Quick Setup (5 minutes)

Install dependencies:

bash

npm install
cd backend && composer install

Configure environment:

bash

cp .env.example .env
# Add your Slack tokens (see [/setup/setup](/setup/setup.md) for details)

Initialize database:

bash

cd backend
php bin/console doctrine:database:create
php bin/console doctrine:migrations:migrate --no-interaction
php bin/console app:seed-poc-data

Start services:

bash

# Terminal 1: Symfony backend
cd backend && symfony server:start

# Terminal 2: Node.js bot
./start-bot.sh

Detailed instructions: See /setup/setup for complete setup with Slack app configuration.

Demo Workflow

1. Knowledge Capture (7 Input Methods)

Method 1: Slash Command

/knowledge add

Opens modal with form for title, content, category, target groups, and tags.

Method 2: Message Shortcut

Right-click any message "Opslaan in Kennishub"
Modal opens with message pre-filled

Method 3: Global Shortcut

Click lightning bolt "Snel Kennis Toevoegen"
Quick add form opens

Method 4: URL Detection

Post a URL in any channel (bot must be present)
Bot scrapes metadata and offers to save

Method 5: File Upload

Upload a file to a channel
Bot detects and prompts to save

Method 6: Emoji Reaction

React to any message with , , , or
Bot prompts to save message

Method 7: App Home

Go to App Home tab "Kennis Toevoegen"

2. Knowledge Management

Browse Dashboard:

/knowledge

View all items with edit, delete, and share actions.

Search:

/knowledge search <query>

Full-text search across title and content.

Browse by Category:

App Home Click "Bekijken" on any thematic list

Manage Lists:

App Home "Lijsten Beheren"

3. AI-Powered Digests

Generate Digest:

/knowledge digest

Select options:

Target Group (required): Ontwikkelaars, Marketeers, CEO, Service Desk, Sales, HR, Design, Iedereen
Category Filter (optional): Filter by thematic list
Date Range (optional): "laatste 7 dagen", "laatste maand", etc.

Digest is delivered via DM with:

Statistics (total items, categories, tags)
Items grouped by category
AI summaries tailored to target group
Tags and metadata

Example Digest Format:

 Knowledge Digest - Ontwikkelaars
Period: Laatste 30 dagen

 Statistics
 8 items totaal
 3 categorien
 15 unieke tags

 Technische Documentatie

 REST API Documentatie v2.0
De nieuwe REST API biedt verbeterde endpoints...

 AI Summary (Ontwikkelaars):
Technical implementation details: New authentication flow uses OAuth 2.0
with JWT tokens. Breaking changes in v2.0 require migration...

Tags: api, documentatie, backend, oauth
Doelgroepen: Ontwikkelaars, Service Desk

Slack App Setup

Complete setup instructions: See /setup/setup

Quick summary:

Create app at https://api.slack.com/apps using slack-app-manifest.yaml
Enable Socket Mode and generate app-level token
Install to workspace and copy bot token
Add tokens to .env file

Troubleshooting: See /setup/slack-app-setup for detailed troubleshooting.

Testing the POC

Scenario 1: Developer Digest

Seed data: php bin/console app:seed-poc-data
In Slack: /knowledge digest
Select: Ontwikkelaars, Technische Documentatie, laatste 7 dagen
Check DM for technical digest

Scenario 2: Marketing Digest

In Slack: /knowledge digest
Select: Marketeers, Marketing, laatste maand
Check DM for customer-focused digest

Scenario 3: CEO Overview

In Slack: /knowledge digest
Select: CEO/Directie, (all categories), laatste maand
Check DM for high-level strategic digest

What to Test

Discoverability: Can users find features without instructions?
Speed: Are interactions fast enough?
Clarity: Are labels and error messages clear?
Usefulness: Do AI summaries add value?
Adoption: Which input methods do users prefer?

Mock AI Summaries

The POC uses mock AI summaries (OPENAI_MOCK=true) that generate realistic summaries without API costs:

Developers: Technical focus, implementation details, bullet points
Marketers: Customer impact, business value, brief style
CEO: Strategic impact, high-level insights, brief style
Service Desk: Support focus, troubleshooting steps, bullet points
Sales: Product benefits, competitive advantages, brief style
HR: Team impact, policy details, detailed style
Design: UX focus, user experience, brief style
All: General accessible language, brief style

To enable real OpenAI API:

bash

# backend/.env
OPENAI_API_KEY=sk-your-key
OPENAI_MODEL=gpt-4
OPENAI_MOCK=false

Cost estimate: ~$0.03 per item with GPT-4, ~$0.002 with GPT-3.5-turbo

API Endpoints

Knowledge:

GET /api/knowledge - List all
GET /api/knowledge?search=query - Search
GET /api/knowledge/{id} - Get one
POST /api/knowledge - Create
PUT /api/knowledge/{id} - Update
DELETE /api/knowledge/{id} - Delete

Categories:

GET /api/categories - List all
POST /api/categories - Create

AI Summaries:

POST /api/knowledge/{id}/generate-summaries - Generate for all target groups

Digests:

POST /api/digests/generate - Generate digest

json

{
  "targetGroup": "developers",
  "categoryId": 2,
  "dateRange": "laatste 7 dagen"
}

How This POC Informs the MVP

Validated Patterns

The POC validates these patterns for the 12-week/6-sprint MVP:

Sprint 1-2: Foundation

Slack integration architecture (Socket Mode vs webhooks)
Modal-based workflows
Category/thematic list structure
Target group concept

Sprint 3-4: Core Features

Multiple input methods (which ones users prefer)
Knowledge CRUD operations
Search and filtering patterns
URL scraping approach

Sprint 5-6: AI & Digests

AI summary generation flow
Target-group-specific prompts
Digest formatting and delivery
Date range filtering

Key Learnings to Capture

During POC testing, document:

Feature Adoption
- Which input methods are used most?
- Which are ignored or confusing?
- What's missing?
User Behavior
- How often do users add knowledge?
- Do they use categories and tags effectively?
- Are digests read and useful?
Technical Performance
- Response times acceptable?
- Any reliability issues?
- Database performance with SQLite?
Content Quality
- Are AI summaries useful?
- Is URL scraping accurate?
- Do users fill in all fields?

MVP Roadmap (Post-POC)

Phase 1: Production Foundation (Weeks 1-2)

Migrate SQLite PostgreSQL
Add authentication & permissions
Set up production hosting
Implement proper logging & monitoring

Phase 2: Core Features (Weeks 3-6)

Refine based on POC feedback
Add advanced search (filters, facets)
Implement versioning
Add scheduled digests (cron)

Phase 3: Advanced Features (Weeks 7-10)

Real OpenAI integration
Email digest delivery
Web dashboard (Symfony Twig)
Analytics and reporting

Phase 4: Polish & Launch (Weeks 11-12)

User testing & extra story
Documentation
Training materials
Rollout plan

Known Limitations

Technical:

SQLite not suitable for production (no concurrent writes)
No authentication (API is open)
No rate limiting
Socket Mode requires bot running continuously

Features:

No full-text search (basic string matching)
No file storage (only references)
No versioning or edit history
No permissions (everyone can edit/delete)
No scheduled digests (manual only)
No analytics or usage tracking

UX:

Dutch only (no language switching yet)
No undo for deletes
No drafts or templates

These limitations are intentional for the POC and will be addressed in the MVP.

Project Structure

yappa-knowledge-hub/
 src/                      # Node.js Slack bot
    app.js               # Main entry point
    handlers/            # Event, command, interaction handlers
    services/            # Business logic (knowledge, categories, etc.)
    i18n/                # Dutch translations
 backend/                  # Symfony API
    src/
       Controller/      # REST API controllers
       Entity/          # Doctrine entities
       Service/         # AI summary, digest services
    config/              # Symfony configuration
    var/data.db          # SQLite database
 tests/                    # Jest tests for bot
    unit/
    integration/
    api/
 docs/                     # Documentation
    Project/PRD.md       # Product requirements
    weekly/              # Weekly progress updates
 slack-app-manifest.yaml  # Slack app configuration
 POC_README.md            # This file

Running Tests

Node.js tests:

bash

npm test                  # All tests
npm run test:unit         # Unit tests only
npm run test:integration  # Integration tests
npm run test:coverage     # With coverage report

Symfony tests:

bash

cd backend
./vendor/bin/phpunit

See testing guide for comprehensive testing documentation.

Troubleshooting

Bot not responding:

bash

# Check bot is running
ps aux | grep "node src/app.js"

# Check logs
tail -f /tmp/slack-bot.log

# Restart
./start-bot.sh

API errors:

bash

# Check Symfony is running
curl http://localhost:8000/api/categories

# Check logs
tail -f backend/var/log/dev.log

# Restart
cd backend && symfony server:start

No summaries generated:

bash

# Check OPENAI_MOCK is enabled
grep OPENAI_MOCK backend/.env

# Test API directly
curl -X POST http://localhost:8000/api/knowledge/1/generate-summaries

Digest empty:

bash

# Check knowledge items exist
curl http://localhost:8000/api/knowledge | jq length

# Seed data if needed
cd backend && php bin/console app:seed-poc-data

Additional Documentation

Documentation Index - Complete guide to all documentation

Key documents:

Setup Guide - Complete setup instructions with troubleshooting
Slack App Setup - Detailed Slack configuration
Testing Guide - Comprehensive test documentation
Product Requirements - Full PRD with MVP roadmap
Project Overview - Project overview and goals

Feedback & Support

How to Provide Feedback

Include:

Feature: Which feature are you commenting on?
Issue: What's the problem or suggestion?
Context: When/where did this happen?
Impact: How important is this?
Ideas: Suggestions for improvement?

Example Feedback

Feature: URL detection
Issue: Bot detects URLs in code snippets and prompts to save them
Context: Happens in #engineering when sharing code
Impact: High - very annoying
Ideas: Ignore URLs in code blocks or add "Don't ask again" option

Summary

This POC demonstrates:

Complete input layer (7 capture methods)
Processing layer (API + mock AI)
Output layer (digests with target-group summaries)
20 realistic Dutch knowledge items
Professional Slack Block Kit formatting
Ready for stakeholder demo and user testing

Next step: Gather feedback to inform the 12-week MVP development plan.

Version: 1.0 Last Updated: 2026-02-12 Status: Ready for Testing

Yappa Knowledge Hub - POC Documentation ​

What is This POC? ​

Architecture ​

Technology Stack ​

Quick Start ​

Quick Setup (5 minutes) ​

Demo Workflow ​

1. Knowledge Capture (7 Input Methods) ​

2. Knowledge Management ​

3. AI-Powered Digests ​

Slack App Setup ​

Testing the POC ​

Scenario 1: Developer Digest ​

Scenario 2: Marketing Digest ​

Scenario 3: CEO Overview ​

What to Test ​

Mock AI Summaries ​

API Endpoints ​

How This POC Informs the MVP ​

Validated Patterns ​

Key Learnings to Capture ​

MVP Roadmap (Post-POC) ​

Known Limitations ​

Project Structure ​

Running Tests ​

Troubleshooting ​

Additional Documentation ​

Feedback & Support ​

How to Provide Feedback ​

Example Feedback ​

Summary ​

Yappa Knowledge Hub - POC Documentation

What is This POC?

Architecture

Technology Stack

Quick Start

Quick Setup (5 minutes)

Demo Workflow

1. Knowledge Capture (7 Input Methods)

2. Knowledge Management

3. AI-Powered Digests

Slack App Setup

Testing the POC

Scenario 1: Developer Digest

Scenario 2: Marketing Digest

Scenario 3: CEO Overview

What to Test

Mock AI Summaries

API Endpoints

How This POC Informs the MVP

Validated Patterns

Key Learnings to Capture

MVP Roadmap (Post-POC)

Known Limitations

Project Structure

Running Tests

Troubleshooting

Additional Documentation

Feedback & Support

How to Provide Feedback

Example Feedback

Summary