YapHub

Appearance

Backend Architecture Deep Dive ​

The YAPPA Knowledge Hub backend is built with Symfony 7.2 and follows a strictly Layered Architecture to ensure a clean separation between external interfaces, business logic, and infrastructure.

Architecture Layers ​

Backend Architecture Overview ​

Last Updated: 2026-03-09 Version: 2.0 (Consolidated)

The Yappa Knowledge Hub backend is a Symfony-based application designed for high performance, bidirectional synchronization with Notion, and role-based AI summarization.

πŸ—οΈ The Dual-Storage Pattern ​

The core architectural decision is our Dual-Storage approach. We combine the collaborative power of Notion with the speed and reliability of a local SQLite database.

  • SQLite: Serves as a high-performance cache. All reads for the Slack Bot and API come from here.
  • Notion: Serves as the master "UI" and persistent cloud storage. All collaborative editing and long-term storage happen here.
  • Sync Engine: A specialized service layer that ensures consistency between both worlds.

πŸ“‚ Project Structure ​

The backend follows standard Symfony structure with domain-specific concentrations:

text
backend/
 β”œβ”€ migrations/      # Database schema history
 β”œβ”€ src/
 β”‚   β”œβ”€ Command/     # Maintenance & Sync CLI tools
 β”‚   β”œβ”€ Controller/  # HTTP Entry points
 β”‚   β”œβ”€ Entity/      # Doctrine models (Knowledge, Category, Role, etc.)
 β”‚   β”œβ”€ Repository/  # Database query logic
 β”‚   └─ Service/     # Business logic (The "Braid")
 β”‚       β”œβ”€ AiSummary/  # AI Orchestration
 β”‚       β”œβ”€ Notion/     # Notion API & Mapping
 β”‚       └─ Slack/      # Slack-specific logic
 └─ tests/           # Unit & Functional test suites

μΈ΅ Layers of Responsibility ​

We employ a strict layered architecture to ensure maintainability:

1. The Interface Layer (Controllers/Commands) ​

Handles raw input from HTTP requests or the CLI. It validates the basic request structure but delegates all business logic to the services.

  • Notable: NotionSyncController, AiSummaryController.

2. The Service Layer (Domain Logic) ​

The "Braid" where our unique logic lives. Services are stateless and orchestrate interactions between entities and external APIs.

  • Notable: AiSummaryService, NotionSyncService.

3. The Entity Layer (Data Model) ​

Rich domain models that encapsulate their own state and internal validation.

  • Notable: Knowledge (The source item), AiSummary (The versioned output).

4. The Infrastructure Layer (Persistence/API) ​

Handles communication with the "Outside World" (SQLite, OpenAI, Notion).

  • Notable: OpenAiClient, NotionClient.

πŸ”„ Core Lifecycles ​

Knowledge Capture ​

  1. Slack Bot receives message β†’ Calls KnowledgeService.
  2. KnowledgeService persists to SQLite β†’ Triggers AiSummaryService.
  3. AiSummaryService calls GPT-4 β†’ Persists AiSummary.
  4. NotionSyncService pushed the new item + summaries to Notion.

Periodic Digest ​

  1. Scheduled task triggers NotionDigestService.
  2. Service aggregates recent Knowledge + AiSummaries for a specific Role.
  3. Formats content for Notion and creates a "Digest Page".

Technical Context ​

  • Framework: Symfony 7.2
  • Runtime: PHP 8.2
  • ORM: Doctrine 3.x
  • Database: SQLite 3

TIP

For a deep dive into how data is mapped between Notion and SQLite, see the Notion Integration Guide.