Yappa Knowledge Hub - Project Structure

Last Updated: 2026-02-15

Directory Structure

yappa-knowledge-hub/
|-- .env                          # Environment variables (Slack bot)
|-- .env.example                   # Environment template
|-- .gitignore                    # Git ignore rules
|-- slack-app-manifest.yaml       # Slack app configuration
|-- package.json                  # Node.js dependencies
|-- package-lock.json             # Node.js lock file
|
|-- README.md                     # Main documentation (quick start)
|-- ARCHITECTURE.md               # System architecture & database schema
|-- STATUS.md                     # Current project status
|-- CHANGELOG.md                  # Changelog of fixes/changes
|-- TESTING.md                    # Testing guide
|-- NOTION_INTEGRATION.md         # Notion API setup & configuration
|-- POC_COMPLETE_SUMMARY.md       # POC completion summary
|-- poc-guide.md                  # Complete POC documentation
|
|-- docs/                         # Documentation & internship reports
|   |-- index.md                 # Documentation navigation
|   |-- setup.md                 # Setup instructions
|   |-- slack-app-setup.md        # Slack configuration guide
|   |-- testing.md               # Testing scenarios
|   |-- weekly/                  # Weekly internship reports
|   |   |-- week-01.md
|   |   |-- week-02.md
|   |   |-- ...
|   |-- report/                  # Internship final report
|       |-- index.md
|   |-- Project/                 # Project planning docs
|       |-- PRD.md
|       |-- overview.md
|       |-- backlog.md
|       |-- roadmap.md
|   |-- archive/                 # Archived documentation
|
|-- src/                          # Slack Bot (TypeScript)
|   |-- app.ts                   # Main entry point
|   |-- types/                   # TypeScript type definitions
|   |   |-- index.ts             # Core types and interfaces
|   |-- config/                  # Configuration management
|   |   |-- index.ts             # App configuration
|   |-- utils/                   # Utility functions
|   |   |-- logger.ts            # Logging utility
|   |   |-- helpers.ts           # Common helpers
|   |-- handlers/                # Slack event handlers
|   |   |-- commands.ts          # Slash command handlers
|   |   |-- events.ts            # Event handlers (URL/file detection)
|   |   |-- actions.ts           # Button and menu actions
|   |   |-- submissions.ts       # Modal form submissions
|   |   |-- shortcuts.ts         # Message & global shortcuts
|   |   |-- home.ts              # App Home tab handler
|   |   |-- reactions.ts         # Emoji reaction handlers
|   |   |-- searchModal.ts       # Search modal handler
|   |   |-- dashboard.ts         # Dashboard rendering
|   |   |-- items.ts             # Knowledge item operations
|   |   |-- lists.ts             # Category/list management
|   |   |-- saveModals.ts        # Save modal handlers
|   |   |-- helpers.ts           # Handler utilities
|   |   |-- index.ts             # Barrel exports
|   |-- services/                # Business logic
|   |   |-- knowledge.ts         # Knowledge CRUD operations
|   |   |-- categories.ts        # Category management
|   |   |-- targetGroups.ts      # Target group definitions
|   |   |-- knowledgeHelpers.ts  # Helper functions
|   |   |-- digestFormatter.ts   # Digest formatting
|   |   |-- digest.ts            # Digest generation
|   |   |-- aiSummary.ts         # AI summary generation
|   |   |-- urlScraper.ts        # URL metadata scraping
|   |   |-- homeRefresh.ts       # App Home refresh
|   |   |-- viewTracker.ts       # Modal view tracking
|   |-- api/                     # Express API routes
|   |   |-- slack.ts             # Slack API endpoints
|   |-- i18n/                    # Internationalization
|       |-- nl.ts                # Dutch (Nederlands) translations
|
|-- dist/                        # Compiled JavaScript output (from TypeScript)
|
|-- backend/                      # Symfony API (PHP 8.x)
|   |-- composer.json             # PHP dependencies
|   |-- .env                     # Backend environment variables
|   |-- public/                  # Web root
|   |-- src/
|   |   |-- Controller/           # REST API endpoints
|   |   |   |-- KnowledgeController.php
|   |   |   |-- CategoryController.php
|   |   |-- Service/
|   |   |   |-- Notion/         # Notion API integration
|   |   |   |   |-- NotionClient.php
|   |   |   |   |-- NotionKnowledgeService.php
|   |   |   |   |-- NotionCategoryService.php
|   |   |   |   |-- NotionDatabaseService.php
|   |   |   |   |-- NotionSyncService.php
|   |   |   |   |-- NotionPropertyMapper.php
|   |   |   |   |-- NotionException.php
|   |   |-- Knowledge/             # Knowledge entities (optional)
|   |-- config/                  # Symfony configuration
|   |-- var/                     # Runtime files (logs, cache)
|
|-- tests/                        # Jest tests (Node.js)
|   |-- unit/                    # Unit tests
|   |-- integration/             # Integration tests
|   |-- api/                     # API endpoint tests
|   |-- e2e/                    # End-to-end tests
|   |-- fixtures/                # Test data
|
|-- scripts/                      # Utility scripts
|   |-- check-services.sh        # Service status checker
|   |-- load-demo-data.sh        # Demo data loader
|   |-- setup-tests.sh           # Test environment setup
|   |-- start-bot.sh             # Bot startup script
|   |-- cleanup-project.sh       # Project cleanup script
|
|-- logs/                         # Application logs

File Purposes

Root Documentation Files

File	Purpose
`README.md`	Quick start guide and overview
`ARCHITECTURE.md`	System architecture, database schema, API endpoints
`STATUS.md`	Current project status, features, next steps
`CHANGELOG.md`	All fixes and implementations during POC
`TESTING.md`	Manual and automated testing guide
`NOTION_INTEGRATION.md`	Notion API configuration and bug fixes
`poc-guide.md`	Complete POC documentation
`slack-app-manifest.yaml`	Slack app configuration for installation

Slack Bot (`src/`) - TypeScript

File	Purpose
`app.ts`	Main entry point, initializes Slack app
`types/index.ts`	Core TypeScript type definitions
`config/index.ts`	Configuration management
`utils/logger.ts`	Logging utility
`utils/helpers.ts`	Common utility functions
`handlers/commands.ts`	`/knowledge` slash command handler
`handlers/events.ts`	Message events, URL/file detection
`handlers/actions.ts`	Button and menu action handlers
`handlers/submissions.ts`	Modal form submissions
`handlers/shortcuts.ts`	Message shortcuts, global shortcuts
`handlers/home.ts`	App Home tab display
`handlers/reactions.ts`	Emoji reaction handlers
`handlers/searchModal.ts`	Search modal display
`handlers/dashboard.ts`	Dashboard rendering and pagination
`handlers/items.ts`	Knowledge item CRUD operations
`handlers/lists.ts`	Category/list management
`handlers/saveModals.ts`	Save modal handlers
`handlers/helpers.ts`	Handler utility functions
`handlers/index.ts`	Barrel exports for handlers
`services/knowledge.ts`	Knowledge CRUD operations
`services/categories.ts`	Category management
`services/targetGroups.ts`	Target group definitions
`services/knowledgeHelpers.ts`	Helper functions
`services/digestFormatter.ts`	Digest formatting logic
`services/digest.ts`	Digest generation logic
`services/aiSummary.ts`	AI summary generation
`services/urlScraper.ts`	URL metadata scraping
`services/homeRefresh.ts`	App Home refresh service
`services/viewTracker.ts`	Modal view tracking
`api/slack.ts`	Express API routes
`i18n/nl.ts`	Dutch (NL) translations

Backend (`backend/`)

File	Purpose
`composer.json`	PHP dependencies
`src/Controller/KnowledgeController.php`	Knowledge API endpoints
`src/Controller/CategoryController.php`	Category API endpoints
`src/Service/Notion/NotionClient.php`	HTTP client for Notion API
`src/Service/Notion/NotionKnowledgeService.php`	Knowledge CRUD in Notion
`src/Service/Notion/NotionCategoryService.php`	Category CRUD in Notion
`src/Service/Notion/NotionDatabaseService.php`	Database service abstraction
`src/Service/Notion/NotionSyncService.php`	Sync operations
`src/Service/Notion/NotionPropertyMapper.php`	Notion <-> PHP mapping
`src/Service/Notion/NotionException.php`	Custom exception class

Scripts (`scripts/`)

Script	Purpose
`check-services.sh`	Check if services are running
`load-demo-data.sh`	Load demo knowledge data
`setup-tests.sh`	Set up test environment
`start-bot.sh`	Start the Slack bot
`cleanup-project.sh`	Clean up test files

Import Path Guidelines

Node.js (Slack Bot)

From handlers:

javascript

// Services
import { listKnowledge } from '../services/knowledge.js';
import { listCategories } from '../services/categories.js';
import { getTargetGroupOptions } from '../services/targetGroups.js';
import { formatDigest } from '../services/digestFormatter.js';

// i18n
import nl from '../i18n/nl.js';

// Other handlers
import { handleAppHomeOpened } from './home.js';

From app.js:

javascript

// Handlers
import { handleKnowledgeCommand } from './handlers/commands.js';
import { handleMessageEvent } from './handlers/events.js';
import { handleViewSubmission } from './handlers/interactions.js';
import { handleSaveMessageShortcut } from './handlers/shortcuts.js';
import { handleAppHomeOpened } from './handlers/home.js';

PHP (Symfony)

From Controllers:

php

use App\Service\Notion\NotionClient;
use App\Service\Notion\NotionKnowledgeService;
use App\Service\Notion\NotionCategoryService;

From Services:

php

use App\Service\Notion\NotionClient;
use App\Service\Notion\NotionException;
use Psr\Log\LoggerInterface;

Environment Configuration

Slack Bot (.env)

bash

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=...
SLACK_APP_TOKEN=xapp-...
API_BASE_URL=http://localhost:8000
PORT=3000

Backend (backend/.env)

bash

NOTION_API_KEY=ntn_...
NOTION_VERSION=2022-06-28
NOTION_DATABASE_KNOWLEDGE=306e292a15d58004a8cbc222dcd48bb2
NOTION_DATABASE_CATEGORIES=306e292a15d5805dae13e64bed8519c5
NOTION_DATABASE_DIGESTS=306e292a15d580d7a0f6fe8421baff10

Running the Application

Start Slack Bot

bash

cd /home/ubuntu/yappa-knowledge-hub
npm start
# Bot runs on port 3000 (Socket Mode)

Start Backend API

bash

cd /home/ubuntu/yappa-knowledge-hub/backend
php -S localhost:8000 -t public
# API runs on port 8000

Check Services

bash

./scripts/check-services.sh

Yappa Knowledge Hub - Project Structure ​

Directory Structure ​

File Purposes ​

Root Documentation Files ​

Slack Bot (src/) - TypeScript ​

Backend (backend/) ​

Scripts (scripts/) ​

Import Path Guidelines ​

Node.js (Slack Bot) ​

PHP (Symfony) ​

Environment Configuration ​

Slack Bot (.env) ​

Backend (backend/.env) ​

Running the Application ​

Start Slack Bot ​

Start Backend API ​

Check Services ​

Yappa Knowledge Hub - Project Structure

Directory Structure

File Purposes

Root Documentation Files

Slack Bot (`src/`) - TypeScript

Backend (`backend/`)

Scripts (`scripts/`)

Import Path Guidelines

Node.js (Slack Bot)

PHP (Symfony)

Environment Configuration

Slack Bot (.env)

Backend (backend/.env)

Running the Application

Start Slack Bot

Start Backend API

Check Services