Yappa Knowledge Hub - Project Structure

Last Updated: 2026-05-08

---

Directory Structure

yappa-knowledge-hub/
├── backend/                # Symfony API (PHP 8.2)
│   ├── bin/                # CLI entry points (console)
│   ├── config/             # Symfony configuration (bundles, routes, packages)
│   ├── migrations/         # Database migrations (unused - schema via create)
│   ├── public/             # Web root (index.php)
│   ├── src/                # Application source code (see detailed breakdown below)
│   ├── tests/              # PHPUnit tests
│   ├── var/                # SQLite database, logs, cache
│   └── composer.json       # PHP dependencies (Symfony 7.3, Doctrine ORM)
├── slack/                  # Slack Bot (TypeScript / @slack/bolt)
│   ├── src/                # Bot source code (detailed breakdown below)
│   ├── package.json        # Node.js dependencies
│   └── tsconfig.json       # TypeScript configuration
├── docs/                   # VitePress Documentation Hub
│   ├── architecture/       # System architecture (layered, flows, slack-bot)
│   ├── setup/            # Complete setup guide
│   ├── development/      # Implementation & documentation guides
│   ├── backend/          # Backend technical documentation
│   ├── weekly/           # Weekly internship and progress reports
│   ├── project/          # Planning, backlog, and strategy
│   └── mvp-presentation/ # MVP feature guides and demonstrations
├── e2e-tests/              # Playwright E2E Test Suite
│   ├── tests/              # Test scenarios (API, knowledge, digest, Slack UI, etc.)
│   ├── playwright.config.ts # Playwright configuration
│   └── package.json        # E2E dependencies
├── scripts/                # Utility and automation scripts
├── package.json            # Monorepo root and documentation scripts
├── pnpm-workspace.yaml     # pnpm workspace definition
├── wrangler.toml           # Cloudflare Pages configuration
└── readme.md               # Project overview and quick start

---

Detailed Source Breakdown

Backend API (backend/src/) - Symfony PHP

Directory	Purpose
Command/	CLI commands for scheduled digest processing
Constants/	Centralized constants organized by domain (Digest, Notion, Entity, etc.)
Controller/	REST API endpoints — 21 routes across 7 controllers
DTO/	Data Transfer Objects for validated request/response shapes
Entity/	Doctrine ORM entities (5: Category, Knowledge, Digest, DigestDelivery, Subscription)
Enum/	PHP 8.1+ Enums (DigestFrequency, KnowledgeStatus, SourceType, etc.)
Exception/	Domain-specific custom exceptions
Factory/	Entity factories (e.g., DigestDeliveryFactory)
Mapper/	Entity-DTO and entity-Notion page mappers
Repository/	Doctrine repository classes with DatabaseResolverInterface
Security/	AccessTokenHandler for bearer token authentication
Service/	Business logic — 38 files across 12 directories (see below)
ValueObject/	Immutable domain value objects

Backend Services (backend/src/Service/) - 38 files

Directory	Files	Purpose
Ai/	2	AiProviderInterface + OpenAIService (OpenAI/OpenRouter)
Content/	1	ContentExtractionService
Content/Extractor/	1	HtmlContentExtractor (Readability-based HTML parser)
Digest/	11	Full digest pipeline (generation, formatting, distribution, scheduling, delivery tracking)
Knowledge/	3	Creation, persistence, query services
Notion/	10	Sync, 4 repositories, page builder, property extractor, markdown content service
Orchestrator/	2	DigestOrchestrator + KnowledgeOrchestrator
Slack/	1	SlackDigestDeliveryService (Markdown → mrkdwn)
Subscription/	3	Facade + query/persistence split
Transport/	2	MessageTransportInterface + SlackMessageTransport
Root	2	CategoryService + EmojiConverter

Slack Bot (slack/src/) - Node.js TypeScript

Directory	Purpose
handlers/	Event listeners, actions, shortcuts, view submissions, and Express API route handlers (handlers/api/)
services/	API client services (knowledge, categories, digest, subscriptions, settings)
utils/	API client with retry logic, shared helpers
views/	Block Kit UI components (Home tab, modals for knowledge, categories, digest, distribution)
app.ts	Entry point — initializes Bolt app + Express API server (defines health, refresh-home, and send-digest routes)

E2E Tests (e2e-tests/tests/) - Playwright TS

Path	Purpose
tests/api/	REST API tests
tests/knowledge/	Knowledge CRUD tests
tests/notion/	Notion sync and connection tests
tests/digests/	Digest generation tests
tests/categories/	Category management tests
tests/workflows/	End-to-end workflow tests
tests/slack-ui/	Slack UI interaction tests (dashboard, modals, overflow, subscriptions)
tests/slack-bot/	Complete production flow test
tests/slack-integration/	AI summary, target group inheritance, edge cases

---

Key Configuration Files

File	Purpose
backend/.env.example	Backend environment variables (Notion keys, OpenAI key, database)
slack/.env.example	Slack bot environment variables (bot token, signing secret, app token)
slack/slack-app-manifest.yaml	Full Slack app manifest (scopes, events, shortcuts, commands)
backend/composer.json	PHP dependencies (Symfony 7.3, Doctrine ORM)
package.json	Root: VitePress docs + Slack scripts
pnpm-workspace.yaml	Monorepo workspace (slack + backend packages)
wrangler.toml	Cloudflare Pages deployment for docs

---

How to Keep Updated

To keep this file accurate:

# Quick directory overview
find . -maxdepth 2 -not -path '*/.*' -not -path './node_modules*' -not -path './vendor*' -not -path './var*'

TIP

Always update this file after significant architectural changes or when adding new top-level components.