Architecture Overview

The digitalNXT Agency framework is built on a modular, extensible architecture designed for scalability, maintainability, and ease of integration. This section provides a comprehensive overview of the system's core components and their interactions.

Core Architecture Principles

🏗️ Modular Design

• Separation of Concerns: Each component has a single, well-defined responsibility
• Loose Coupling: Components interact through well-defined interfaces
• High Cohesion: Related functionality is grouped together

🔧 Extensibility

• Plugin Architecture: Easy to add new strategies, processors, and tools
• Configuration-Driven: Behavior can be modified without code changes
• Override Support: Default implementations can be replaced

📊 Observability

• Comprehensive Logging: Structured logging throughout the system
• Tracing Support: Integration with Langfuse for execution tracing
• Performance Monitoring: Execution time tracking and metrics

💾 Memory Management

• Persistent Sessions: SQLite-based conversation storage
• Factory Patterns: Consistent object creation and configuration
• Conversation APIs: High-level conversation management

System Architecture

graph TB
    User[👤 User] --> Agency[🏛️ Agency]

    Agency --> Strategy[📋 Strategy]
    Agency --> Processor[⚙️ Processor]
    Agency --> Session[💾 SQLiteSession]

    Strategy --> |implements| BaseStrategy[📝 Base Strategy]
    Strategy --> Agent1[🤖 Agent 1]
    Strategy --> Agent2[🤖 Agent 2]
    Strategy --> AgentN[🤖 Agent N]

    Processor --> AsyncExec[🔄 Async Executor]
    Processor --> SyncExec[⏱️ Sync Executor]
    Processor --> Langfuse[📈 Langfuse Client]

    AsyncExec --> OpenAI[🧠 OpenAI API]
    SyncExec --> OpenAI

    Strategy --> |returns| StrategyResult[📊 Strategy Result]
    StrategyResult --> Agency
    Agency --> User

    subgraph "Memory Management"
        SessionFactory[🏭 SessionFactory] --> Session
        ConversationManager[💬 ConversationManager] --> ConversationStorage[💾 Storage]
        AgencyFactory[🏭 AgencyFactory] --> Agency
        Session --> |memory| InMemory[🧠 In-Memory]
        Session --> |persistent| FileDB[💾 File Database]
    end

    subgraph "Observability Stack"
        Langfuse --> Traces[📋 Traces]
        Processor --> Logger[📝 Logger]
    end

    subgraph "Configuration"
        Config[⚙️ Config]
        Config --> Agency
        Config --> Strategy
        Config --> Processor
    end

    classDef userClass fill:#e1f5fe
    classDef coreClass fill:#f3e5f5
    classDef strategyClass fill:#e8f5e8
    classDef processorClass fill:#fff3e0
    classDef observabilityClass fill:#fce4ec
    classDef memoryClass fill:#f1f8e9

    class User userClass
    class Agency,StrategyResult coreClass
    class Strategy,BaseStrategy,Agent1,Agent2,AgentN strategyClass
    class Processor,AsyncExec,SyncExec processorClass
    class Langfuse,Traces,Logger observabilityClass
    class SessionFactory,ConversationManager,ConversationStorage,AgencyFactory,Session,InMemory,FileDB memoryClass

Component Overview

🏛️ Agency (Core Orchestrator)

The central coordinator that manages the entire workflow: - Initializes and configures strategies and processors - Provides unified logging and observability - Manages session and user context - Integrates persistent memory through SQLiteSession - Handles error propagation and recovery

📋 Strategy (Execution Logic)

Encapsulates the business logic for agent coordination: - Router Strategy: Routes requests to appropriate specialist agents - Sequential Strategy: Executes agents in sequence - Parallel Strategy: Executes agents concurrently - Custom Strategies: User-defined execution patterns

⚙️ Processor (Execution Engine)

Handles the low-level execution of agents: - Async/Sync Execution: Support for both execution modes - Observability Integration: Langfuse tracing and logging - Error Handling: Comprehensive error capture and reporting - Performance Monitoring: Execution time tracking

💾 Memory Management

Persistent conversation and session management: - SessionFactory: Creates configured SQLiteSession instances - ConversationManager: High-level conversation management API - AgencyFactory: Factory pattern for agency creation with memory

📊 Models (Data Structures)

Standardized data structures for communication: - StrategyResult: Standardized output format - Configuration Models: Type-safe configuration - Message Models: Structured communication - Conversation Models: Chat messages and session metadata

Data Flow

sequenceDiagram
    participant User
    participant Agency
    participant Strategy
    participant Processor
    participant Agent
    participant OpenAI
    participant Langfuse

    User->>Agency: run("user input", context)
    Agency->>Agency: Setup logging & context
    Agency->>Strategy: execute(input, merged_context)

    Strategy->>Strategy: Initialize execution path
    Strategy->>Processor: run(agent, input, context)

    Processor->>Langfuse: start_span("Agency - Strategy")
    Processor->>Agent: OpenAI Runner.run()
    Agent->>OpenAI: API Call
    OpenAI-->>Agent: Response
    Agent-->>Processor: Result

    Processor->>Langfuse: update_span(input, output, metadata)
    Processor->>Langfuse: flush() [if auto_flush]
    Processor-->>Strategy: Execution Result

    Strategy->>Strategy: Process result & update execution path
    Strategy-->>Agency: StrategyResult

    Agency->>Agency: Add processor info to result
    Agency-->>User: Final StrategyResult

Key Features

🔄 Flexible Execution Modes

• Async-First: Native async/await support throughout
• Sync Compatibility: Synchronous execution when needed
• Background Processing: Long-running tasks support

🎯 Strategy Patterns

• Template Method: Base strategy with customizable steps
• Factory Pattern: Dynamic strategy selection
• Observer Pattern: Event-driven execution monitoring

🛡️ Error Handling

• Graceful Degradation: System continues operating despite partial failures
• Error Propagation: Clear error reporting up the stack
• Recovery Mechanisms: Automatic retry and fallback strategies

📈 Performance

• Lazy Loading: Components loaded only when needed
• Connection Pooling: Efficient resource utilization
• Caching: Strategic caching for improved performance

Integration Points

🔌 OpenAI Integration

• Native support for OpenAI Agent framework
• Automatic API instrumentation
• Token usage tracking and optimization

📊 Langfuse Integration

• Automatic trace generation
• Custom span creation for detailed monitoring
• Performance analytics and insights

☁️ Azure Integration

• Azure OpenAI service support
• Azure deployment patterns
• Cloud-native observability

Next Steps

• Agency Framework: Deep dive into the core Agency class
• Memory Management: Session and conversation memory overview
• Strategies: Understanding strategy patterns and implementation
• Processors: Execution engine details and configuration
• Integration Patterns: Common integration scenarios