YapHub

Appearance

Backend Documentation Index ​

Welcome to the Yappa Knowledge Hub backend documentation. This documentation provides comprehensive coverage of the Symfony 7.2 backend architecture, APIs, and database design.

Documentation Structure ​

1. Backend Overview ​

Complete overview of the backend architecture, technology stack, and design patterns.

Topics Covered:

  • Technology stack (Symfony 7.2, PHP 8.2, Doctrine, API Platform)
  • Architecture overview (dual-storage pattern with SQLite + Notion)
  • Directory structure
  • Key components (Controllers, Services, Entities, Repositories)
  • Design patterns (Repository, Service Layer, Data Mapper, Dependency Injection)
  • Configuration and environment variables
  • Performance considerations
  • Security best practices

2. Controllers Documentation ​

Detailed documentation of all 8 HTTP controllers with request/response examples.

Controllers Documented:

  • KnowledgeController - Main CRUD operations with Notion sync
  • LocalKnowledgeController - SQLite-only read operations
  • CategoryController - Category management with auto-sync
  • SummaryController - AI summary management
  • NotionSyncController - Manual sync operations
  • NotionWebhookController - Notion webhook handling
  • DigestController - Digest generation
  • NotionDigestController - Notion digest operations

Each controller includes:

  • Route definitions
  • Request/response formats
  • Example cURL commands
  • Error handling

3. Services Documentation ​

Complete documentation of all business logic services and external integrations.

Services Documented:

Notion Services:

  • NotionClient - Low-level HTTP client for Notion API
  • NotionKnowledgeService - Knowledge item operations
  • NotionCategoryService - Category operations with emoji support
  • NotionSyncService - Bidirectional sync between SQLite and Notion
  • NotionPropertyMapper - Property mapping utilities
  • NotionDatabaseService - Database-level operations
  • NotionDigestService - Digest operations

Application Services:

  • OpenAiService - AI completion generation with retry logic and mock mode
  • SummaryService - Summary generation and management
  • TargetGroupService - Target group management
  • SlackHomeRefreshService - Slack integration

Each service includes:

  • Constructor parameters
  • Method signatures
  • Usage examples
  • Configuration details

4. Entities Documentation ​

Comprehensive documentation of all 6 Doctrine entities with ER diagram.

Entities Documented:

  • Knowledge - Main knowledge items with Notion sync
  • Category - Knowledge categories with target groups
  • Resource - External resources (URLs, PDFs, etc.)
  • ResourceContent - Content extracted from resources
  • Summary - AI-generated summaries
  • Tag - Tags for resources

Includes:

  • Entity relationship diagram (Mermaid)
  • Property definitions with types
  • Relationship mappings
  • Method documentation
  • Usage examples
  • Repository patterns

5. Database Documentation ​

Complete database setup, migration, and management guide.

Topics Covered:

  • SQLite configuration
  • Database schema (8 tables)
  • Migrations guide (creating, running, rolling back)
  • Seeding data (fixtures and console commands)
  • Querying (Doctrine ORM, DQL, native SQL)
  • Backup and restore procedures
  • Performance optimization
  • Troubleshooting
  • Production considerations

6. API Reference ​

Complete REST API reference with examples in multiple languages.

API Endpoints Documented:

Knowledge Endpoints:

  • POST /api/knowledge - Create knowledge item
  • GET /api/knowledge - List/search knowledge items
  • GET /api/knowledge/{id} - Get knowledge item
  • PUT /api/knowledge/{id} - Update knowledge item
  • DELETE /api/knowledge/{id} - Archive knowledge item
  • POST /api/knowledge/search - Search knowledge items

Local Endpoints:

  • GET /api/local/knowledge - List from SQLite
  • GET /api/local/categories - List categories from SQLite

Category Endpoints:

  • POST /api/categories - Create category
  • GET /api/categories - List categories
  • GET /api/categories/{id} - Get category
  • PUT /api/categories/{id} - Update category
  • POST /api/categories/sync - Sync from Notion

Includes:

  • Request/response formats
  • HTTP status codes
  • Error handling
  • Client examples (JavaScript, PHP, Python)
  • Testing with cURL, HTTPie, Postman

Quick Start ​

Prerequisites ​

  • PHP 8.2 or higher
  • Composer
  • SQLite3

Installation ​

bash
# Navigate to backend directory
cd backend

# Install dependencies
composer install

# Configure environment
cp .env .env.local
# Edit .env.local with your Notion API keys

# Create database
php bin/console doctrine:database:create

# Run migrations
php bin/console doctrine:migrations:migrate

# Load sample data (optional)
php bin/console doctrine:fixtures:load

# Start development server
symfony server:start
# or
php -S localhost:8000 -t public

Testing the API ​

bash
# List knowledge items
curl http://localhost:8000/api/knowledge

# Create knowledge item
curl -X POST http://localhost:8000/api/knowledge \
  -H "Content-Type: application/json" \
  -d '{"title": "Test", "content": "Test content"}'

Key Features ​

Dual-Storage Architecture ​

The backend implements a unique dual-storage pattern:

  1. SQLite Database - Local persistent storage for fast queries
  2. Notion API - Cloud-based knowledge management with rich UI

Benefits:

  • Fast local queries without network latency
  • Rich collaborative features from Notion
  • Automatic bidirectional synchronization
  • Resilience (works even if Notion is unavailable)

Notion Integration ​

Full integration with Notion API:

  • Create, read, update pages
  • Query databases with filters and sorting
  • Automatic pagination for large datasets
  • Property mapping between Notion and PHP
  • Emoji icon support (Slack format Unicode)
  • Webhook support for real-time updates

AI Summaries ​

OpenAI integration for generating summaries:

  • Automatic retry logic with exponential backoff
  • Mock mode for development/testing
  • Configurable model and parameters
  • Target group-aware summaries

RESTful API ​

Clean RESTful JSON API:

  • Standard HTTP methods (GET, POST, PUT, DELETE)
  • JSON request/response format
  • Proper HTTP status codes
  • Comprehensive error handling

Architecture Highlights ​

Design Patterns ​

  1. Repository Pattern - Clean data access abstraction
  2. Service Layer Pattern - Business logic encapsulation
  3. Data Mapper Pattern - Notion API response mapping
  4. Dependency Injection - Managed by Symfony container
  5. Dual-Storage Pattern - Custom pattern for SQLite + Notion

Technology Stack ​

  • Framework: Symfony 7.2
  • PHP: 8.2+ with modern features (enums, attributes, typed properties)
  • ORM: Doctrine 3.6+ with migrations
  • API: API Platform 4.1+ for REST capabilities
  • Database: SQLite for local storage
  • HTTP Client: Symfony HTTP Client + Guzzle
  • Testing: PHPUnit 11.5+

Environment Variables ​

Required environment variables:

bash
# Database
DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"

# Notion API
NOTION_API_KEY="secret_xxx"
NOTION_KNOWLEDGE_DATABASE_ID="xxx"
NOTION_CATEGORIES_DATABASE_ID="xxx"

# OpenAI API
OPENAI_API_KEY="sk-xxx"
OPENAI_MODEL="gpt-4"
OPENAI_MOCK_MODE="false"

Common Tasks ​

Create a New Entity ​

bash
php bin/console make:entity

Generate Migration ​

bash
php bin/console make:migration

Run Migrations ​

bash
php bin/console doctrine:migrations:migrate

Create Controller ​

bash
php bin/console make:controller

Run Tests ​

bash
composer test

Clear Cache ​

bash
php bin/console cache:clear

Troubleshooting ​

Database Issues ​

See Database Documentation for:

  • Database locked errors
  • Schema out of sync
  • Migration failures
  • Database corruption

Notion API Issues ​

Common issues:

  • Invalid API key: Check NOTION_API_KEY in .env.local
  • Invalid database ID: Verify NOTION_KNOWLEDGE_DATABASE_ID
  • Rate limiting: Notion API has rate limits
  • Property validation: Ensure properties match Notion schema

Performance Issues ​

Optimization tips:

  • Use local endpoints (/api/local/*) for read operations
  • Enable query result caching
  • Add indexes to frequently queried columns
  • Use pagination for large datasets

Contributing ​

Code Style ​

Follow Symfony coding standards:

bash
# Check code style
vendor/bin/php-cs-fixer fix --dry-run

# Fix code style
vendor/bin/php-cs-fixer fix

Testing ​

Write tests for new features:

bash
# Run all tests
composer test

# Run specific test
vendor/bin/phpunit tests/Service/OpenAiServiceTest.php

# Generate coverage report
composer test:coverage

Additional Resources ​

Symfony Documentation ​

Notion API ​

OpenAI API ​

Support ​

For questions or issues:

  1. Check the relevant documentation section
  2. Review the troubleshooting guides
  3. Check Symfony/Doctrine/Notion API documentation
  4. Contact the development team

License ​

Proprietary - All rights reserved

Changelog ​

Version 1.0.0 (2026-02-19) ​

  • Initial documentation release
  • Complete coverage of all controllers, services, and entities
  • Database schema and migration guide
  • Comprehensive API reference
  • Architecture overview and design patterns

Last Updated: 2026-02-19

Documentation Version: 1.0.0

Backend Version: Symfony 7.2, PHP 8.2