Hexagonal Lite & DDD Implementation

Relevant source files

The following files were used as context for generating this wiki page:

• GEMINI.md
• README.md
• CLAUDE.md
• design-system/HEX-YT-INTEL Design System (1)/README.md/README.md)
• design-system/HEX-YT-INTEL Design System (1)/SKILL.md/SKILL.md)

The hex-yt-intel project enforces a Hexagonal Lite (Ports & Adapters) architectural pattern combined with Domain-Driven Design (DDD). This approach is designed to separate core business logic—such as the YouTube content synthesis engine—from external infrastructure concerns like Supabase, Upstash, or specific LLM providers. By utilizing "Lite" hexagonal principles, the system reduces boilerplate while maintaining strict boundaries for complex domain services.

Sources: GEMINI.md:214-219, CLAUDE.md:5-22

Architectural Fundamentals

The architecture is divided into three primary layers: Ports, Adapters, and Use Cases. The "Lite" variation allows domain objects to be used directly in ports to reduce mapping overhead, while read-only operations that bypass business logic may occasionally skip ports for efficiency.

Core Architectural Layers

Layer	Directory	Description
Ports	/web/lib/ports	Abstract interfaces defining application requirements (e.g., PersistencePort).
Adapters	/web/lib/adapters	Concrete implementations for external systems (e.g., SupabasePersistenceAdapter).
Use Cases	/web/lib/usecases	Application Services orchestrating business logic and ports.
Domain Services	/worker/src/services	Core logic that doesn't fit a single entity (e.g., ReasoningEngine).

Sources: GEMINI.md:221-236

Component Relationship Diagram

The following diagram illustrates the flow of control and dependency between the architectural layers.

Domain-Driven Design (DDD) Implementation

The heart of the system lies in its Domain Services and Use Cases. Domain services located in the worker directory (e.g., ReasoningEngine, LLMCascade) represent the core competitive advantage of the project and are explicitly categorized as domain logic rather than infrastructure adapters.

Key Domain Services

• ReasoningEngine: Orchestrates the complex logic of content deconstruction and synthesis.
• LLMCascade: Manages the fallback logic between different LLM models (e.g., Nemotron to Haiku).
• PromptBuilder: Constructs the highly structured UCIS v5.1 prompts.
• ValidationService: Ensures the output conforms to the required JSON schema and quality gates.

Sources: GEMINI.md:231-236, CLAUDE.md:31-35

Critical Architectural Rules

To maintain the integrity of the DDD implementation, the following rules are enforced:

1. Components in worker/src/services/ MUST NOT be moved to /adapters/ or renamed with an Adapter suffix.
2. Logic governing the reasoning cascade or prompt building is considered core domain logic, even if it interacts with external APIs like OpenRouter.
3. Only pure database or infrastructure connectors (e.g., UpstashCacheAdapter) belong in the adapters layer.

Sources: GEMINI.md:232-236

Hexagonal Lite for Presentation

The presentation layer also follows hexagonal principles. Every UI component is treated as a stateless adapter. This ensures that the design system remains decoupled from the application state and side effects.

Presentation Adapter Flow

Hybrid Edge Symphony (ADR 005)

The implementation leverages a hybrid infrastructure to solve serverless execution limits while maintaining architectural boundaries. This flow coordinates between Vercel and Cloudflare Workers.

Execution Lifecycle

1. Vercel Bouncer: Handles high-security authentication and atomic quota enforcement (~8s).
2. Cloudflare Streaming: Manages direct browser-to-edge SSE connections for high-latency LLM synthesis (~58s).
3. HMAC Persistence: Uses cryptographically signed server-to-server (S2S) writes to guarantee data integrity when the worker saves results back to the database.

Sources: README.md:22-26, CLAUDE.md:17-22

Hybrid Flow Diagram

Conclusion

The "Hexagonal Lite & DDD" implementation provides a robust framework for managing the complexity of the HEX-YT-INTEL synthesis engine. By strictly separating domain services from infrastructure adapters and enforcing stateless presentation patterns, the project ensures long-term maintainability and high performance across its hybrid edge infrastructure.