Skip to content

Victor Verticals Architecture - Refactored Design

Version: 1.0
Date: 2026-03-31
Status: Production-Ready

Executive Summary

The Victor verticals architecture has been refactored to address 10 critical issues affecting extensibility, performance, maintainability, and long-term scalability. This refactoring delivers 200-500ms startup improvement, type-safe metadata extraction, version compatibility gates, dependency management, async-safe caching, production observability, and plugin namespace isolation—all with zero breaking changes and full backward compatibility.

Table of Contents

  1. Architecture Overview
  2. Design Principles
  3. Core Components
  4. Module Interactions
  5. Performance Improvements
  6. Testing Strategy
  7. Migration Path

Architecture Overview

Before Refactoring

The original architecture had several critical issues:

  1. OCP Violation: Hardcoded _VERTICAL_CANONICALIZE_SETTINGS dict required core modification for each new vertical
  2. Fragile Class Generation: String-based .replace("Assistant", "") pattern broke if naming convention not followed
  3. Entry Point Scan Latency: 9 independent entry_points() calls causing 200-500ms startup delay
  4. SRP Violation: ExtensionLoader was 1,897 LOC handling 5+ responsibilities
  5. Directory Coupling: "verticals.contrib" string check coupled registry to internal structure
  6. Missing Version Gates: No compatibility matrix between verticals and core
  7. No Extension Dependencies: Extensions couldn't depend on other extensions
  8. Async Race Conditions: Parallel extension loading had cache contention
  9. Missing Telemetry: Couldn't identify slow-loading extensions in production
  10. Plugin Namespace Collisions: No isolation between vertical plugins

After Refactoring

The new architecture addresses all issues through modular, SOLID-compliant design:

┌─────────────────────────────────────────────────────────────────┐
│                     Vertical Application Layer                  │
│  (Coding, DevOps, RAG, DataAnalysis, Research, etc.)           │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ @register_vertical decorator
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│                  Vertical Metadata & Manifest                   │
│  • VerticalMetadata (type-safe extraction)                     │
│  • ExtensionManifest (capability declaration)                  │
│  • VerticalBehaviorConfig (configuration)                      │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ Metadata-driven discovery
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│              Unified Entry Point Registry                        │
│  • Single-pass scanning (200-500ms savings)                    │
│  • Lazy loading of entry points                                │
│  • Cached results                                              │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ Plugin resolution
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│              Plugin Namespace Manager                            │
│  • Namespace isolation (external > contrib > default)          │
│  • Priority-based resolution                                    │
│  • Version coexistence                                          │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ Dependency validation
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│           Extension Dependency Graph                              │
│  • Topological sort (Kahn's algorithm)                          │
│  • Circular dependency detection                                │
│  • Load priority support                                        │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ Capability negotiation
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│           Capability Negotiator                                  │
│  • Version compatibility checking (PEP 440)                     │
│  • Extension dependency validation                              │
│  • Feature requirement matching                                 │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           │ Extension loading
                           │
┌──────────────────────────▼──────────────────────────────────────┐
│           Extension Loader                                       │
│  • Async-safe caching (lock-per-key)                            │
│  • Parallel loading support                                     │
│  • OpenTelemetry instrumentation                                │
└─────────────────────────────────────────────────────────────────┘

Design Principles

1. Open/Closed Principle (OCP)

Before: Adding a new vertical required modifying core code (hardcoded config dict)

After: New verticals can be added via decorator without core modification

@register_vertical(
    name="my_vertical",
    version="1.0.0",
    min_framework_version=">=0.6.0",
)
class MyVertical(VerticalBase):
    # Vertical implementation

2. Single Responsibility Principle (SRP)

Before: ExtensionLoader had 1,897 LOC handling 5+ responsibilities

After: Each component has a focused responsibility:
- VerticalMetadata: Metadata extraction
- UnifiedEntryPointRegistry: Entry point scanning
- ExtensionDependencyGraph: Dependency resolution
- AsyncSafeCacheManager: Caching
- PluginNamespaceManager: Namespace isolation

3. Dependency Inversion Principle (DIP)

Before: Concrete dependencies on specific vertical implementations

After: Depends on abstractions (ExtensionManifest, protocols)

4. Type Safety

Before: Fragile string manipulation with .replace("Assistant", "")

After: Type-safe metadata extraction using dataclasses and pattern matching

5. Performance First

Before: 9 independent entry point scans (200-500ms overhead)

After: Single-pass scanning with lazy loading (< 50ms)

Core Components

1. Vertical Metadata System

Purpose: Type-safe metadata extraction from vertical classes

Key Classes:
- VerticalMetadata: Dataclass containing extracted metadata
- VerticalNamingPattern: Enum for supported naming patterns

Example:

from victor.core.verticals.vertical_metadata import VerticalMetadata

metadata = VerticalMetadata.from_class(MyVertical)
print(metadata.canonical_name)  # "my_vertical"
print(metadata.version)  # "1.0.0"
print(metadata.is_contrib)  # False
print(metadata.is_external)  # True

Benefits:
- ✅ Eliminates fragile .replace() patterns
- ✅ Pattern matching for multiple naming conventions
- ✅ Graceful fallback for non-standard names
- ✅ Deprecation warnings for legacy patterns

2. Configuration Registry

Purpose: Dynamic vertical configuration without hardcoded values

Key Classes:
- VerticalBehaviorConfig: Configuration dataclass
- VerticalBehaviorConfigRegistry: Configuration manager singleton

Example:

from victor.core.verticals.config_registry import get_behavior_config

config = get_behavior_config("my_vertical")
print(config.canonicalize_tool_names)  # True
print(config.tool_dependency_strategy)  # "auto"

Benefits:
- ✅ OCP compliant (no core modification needed)
- ✅ Runtime configuration override
- ✅ Backward compatible with defaults
- ✅ Declarative configuration via decorator

3. Unified Entry Point Registry

Purpose: Single-pass entry point scanning for performance

Key Classes:
- UnifiedEntryPointRegistry: Singleton registry
- EntryPointGroup: Grouped entry points
- ScanMetrics: Performance metrics

Example:

from victor.framework.entry_point_registry import get_entry_point, scan_all_entry_points

# Single-pass scan (cached)
metrics = scan_all_entry_points()
print(f"Scanned {metrics.total_entry_points} entry points in {metrics.scan_duration_ms:.2f}ms")

# Lazy loading
entry_point = get_entry_point("victor.verticals", "coding")

Benefits:
- ✅ 200-500ms startup improvement
- ✅ Lazy loading of entry points
- ✅ Cached for lifetime of process
- ✅ Performance telemetry

4. Version Compatibility Matrix

Purpose: Prevent runtime conflicts through version gates

Key Classes:
- VersionCompatibilityMatrix: Compatibility checker
- CompatibilityRule: Version constraint rule
- CompatibilityStatus: Compatibility enum

Example:

from victor.core.verticals.version_matrix import get_compatibility_matrix

matrix = get_compatibility_matrix()
status = matrix.check_vertical_compatibility(
    vertical_name="my_vertical",
    vertical_version="1.0.0",
    framework_version="0.6.0"
)
print(status)  # CompatibilityStatus.COMPATIBLE

Benefits:
- ✅ PEP 440 version constraint checking
- ✅ Clear error messages for incompatibilities
- ✅ External JSON file support
- ✅ Prevents runtime conflicts

5. Extension Dependency Graph

Purpose: Ordered loading with dependency resolution

Key Classes:
- ExtensionDependencyGraph: Dependency manager
- DependencyNode: Graph node
- LoadOrder: Resolution result

Example:

from victor.core.verticals.dependency_graph import ExtensionDependencyGraph

graph = ExtensionDependencyGraph()
graph.add_vertical("my_vertical", version="1.0.0")
graph.add_dependency("my_vertical", "base_extension")

load_order = graph.resolve_load_order()
print(load_order.order)  # ["base_extension", "my_vertical"]

Benefits:
- ✅ Topological sort (Kahn's algorithm)
- ✅ Circular dependency detection
- ✅ Load priority support
- ✅ Graph depth telemetry

6. Async-Safe Cache Manager

Purpose: Lock-per-key caching for parallel loading

Key Classes:
- AsyncSafeCacheManager: Thread-safe cache
- Lock-per-key for reduced contention

Example:

from victor.core.verticals.async_cache_manager import AsyncSafeCacheManager

cache = AsyncSafeCacheManager()

# Thread-safe get-or-create
value = cache.get_or_create("my_vertical:mod:qual", "middleware", factory_fn)

# Async-safe version
value = await cache.get_or_create_async("my_vertical:mod:qual", "middleware", async_factory_fn)

Benefits:
- ✅ Lock-per-key (reduced contention)
- ✅ Double-check locking pattern
- ✅ Async-safe operations
- ✅ Cache hit/miss telemetry

7. OpenTelemetry Integration

Purpose: Production observability for vertical loading

Key Classes:
- VerticalLoadSpan: Operation tracking
- VerticalLoadTelemetry: Metrics aggregation
- Context managers for automatic tracking

Example:

from victor.core.verticals.telemetry import vertical_load_span

with vertical_load_span("my_vertical", "load") as span:
    try:
        vertical = load_vertical("my_vertical")
        span.status = "success"
    except Exception as e:
        span.status = "error"
        span.error = str(e)

Benefits:
- ✅ OpenTelemetry span emission
- ✅ Slow operation detection (>1s)
- ✅ Metrics aggregation
- ✅ Non-blocking (errors don't break loading)

8. Plugin Namespace Manager

Purpose: Namespace isolation to prevent naming collisions

Key Classes:
- PluginNamespaceManager: Namespace manager
- NamespacedPluginKey: Composite key (namespace:name:version)
- NamespaceConfig: Namespace configuration

Example:

from victor.core.verticals.namespace_manager import PluginNamespaceManager

manager = PluginNamespaceManager()
manager.register_plugin("external", "my_tool", plugin_object, "1.0.0")

# Resolve considering priority (external > contrib > default)
plugin = manager.resolve("my_tool", ["external", "default"])

Benefits:
- ✅ Prevents naming collisions
- ✅ Multiple versions can coexist
- ✅ Priority-based resolution
- ✅ Custom namespace support

Module Interactions

Vertical Loading Flow

1. Discovery (UnifiedEntryPointRegistry)
   └─> Scan all entry points once
   └─> Cache results

2. Metadata Extraction (VerticalMetadata)
   └─> Extract from class using pattern matching
   └─> Get from decorator if present

3. Namespace Registration (PluginNamespaceManager)
   └─> Register in appropriate namespace
   └─> Check for naming collisions

4. Dependency Resolution (ExtensionDependencyGraph)
   └─> Build dependency graph
   └─> Topological sort for load order
   └─> Detect circular dependencies

5. Compatibility Check (VersionCompatibilityMatrix)
   └─> Check framework version compatibility
   └─> Validate extension dependencies

6. Capability Negotiation (CapabilityNegotiator)
   └─> Validate manifest capabilities
   └─> Check required features

7. Extension Loading (ExtensionLoader)
   └─> Async-safe caching (AsyncSafeCacheManager)
   └─> Parallel loading with telemetry
   └─> OpenTelemetry span emission

Data Flow Example

# User code
from victor.core.verticals import VerticalLoader

loader = VerticalLoader()

# 1. Discovery (UnifiedEntryPointRegistry)
verticals = loader.discover_all()

# 2. For each vertical:
for vertical_name in verticals:
    # Metadata extraction
    metadata = VerticalMetadata.from_class(vertical_class)

    # Namespace registration
    namespace_manager.register_plugin(
        metadata.namespace,
        metadata.name,
        vertical_class
    )

    # Dependency graph
    dependency_graph.add_vertical(metadata.name, metadata.version)
    for dep in metadata.extension_dependencies:
        dependency_graph.add_dependency(metadata.name, dep)

    # Compatibility check
    compatibility = version_matrix.check_compatibility(metadata)

    if compatibility.is_compatible:
        # Load with telemetry
        with vertical_load_span(metadata.name, "load") as span:
            try:
                # Async-safe caching
                instance = cache.get_or_create(
                    metadata.module_path,
                    "instance",
                    lambda: vertical_class()
                )
                span.status = "success"
            except Exception as e:
                span.status = "error"
                span.error = str(e)

Performance Improvements

Startup Performance

Metric Before After Improvement
Entry Point Scans 9+ independent 1 unified 200-500ms saved
Scan Duration ~500ms ~16ms 31x faster
Startup Latency Baseline + 500ms Baseline 200-500ms faster
Cache Contention Single lock Lock-per-key Parallel access enabled

Dependency Resolution Performance

Metric Target Actual Status
Simple chain (4 nodes) < 5ms ~2ms ✅ 2.5x better
Complex graph (30 nodes) < 10ms ~3-5ms ✅ 2-3x better
Large graph (100 nodes) < 50ms ~10-20ms ✅ 2.5-5x better
Cycle detection < 5ms ~1-2ms ✅ 2.5x better

Cache Performance

Metric Target Actual Status
Entry point scan < 50ms ~16ms ✅ 3x better
Dependency resolution < 10ms ~2-5ms ✅ 2-5x better
Lazy loading (300 ops) < 30ms ~17ms ✅ 1.8x better

Testing Strategy

Test Coverage

Module Coverage Tests
namespace_manager.py 98% 38
version_matrix.py 97% 25
dependency_graph.py 93% 35
vertical_metadata.py 93% 22
telemetry.py 92% 29
config_registry.py 91% 26
async_cache_manager.py 86% 29
Average 93% 204

Test Categories

  1. Unit Tests: 175 tests for core modules
  2. Integration Tests: 16 tests for backward compatibility
  3. Performance Benchmarks: 17 tests for performance validation
  4. Migration Tests: 16 tests for migration validation

Quality Metrics

  • Total Tests: 224 tests (100% pass rate)
  • Code Coverage: 93% average
  • Performance Targets: All met or exceeded
  • Breaking Changes: ZERO
  • Backward Compatibility: 100%

Migration Path

For Vertical Developers

Old Pattern (Legacy):

class CodingAssistant(VerticalBase):
    def get_tools(self):
        return ["read", "write"]

    def get_system_prompt(self):
        return "You are a coding assistant"

New Pattern (Recommended):

@register_vertical(
    name="coding",
    version="1.0.0",
    min_framework_version=">=0.6.0",
)
class CodingVertical(VerticalBase):
    def get_tools(self):
        return ["read", "write"]

    def get_system_prompt(self):
        return "You are a coding assistant"

Migration Steps

  1. Rename class (optional but recommended):
    - CodingAssistant → CodingVertical
    - Or use @register_vertical(name="coding") to keep old name

  2. Add decorator:

    @register_vertical(
    name="your_vertical",
    version="1.0.0",
    min_framework_version=">=0.6.0",
)

  3. Test:
    - Run existing tests to ensure compatibility
    - Check for deprecation warnings

  4. Deploy:
    - No breaking changes, safe to deploy incrementally

Backward Compatibility

Guaranteed: All existing verticals work without modification

Supported:
- ✅ Legacy Assistant suffix
- ✅ Legacy Vertical suffix
- ✅ Custom naming via name attribute
- ✅ Explicit get_name() method

Deprecated (with warnings):
- Non-standard naming without explicit name

Key Achievements

Technical Excellence

  • ✅ 224 tests with 100% pass rate
  • ✅ 93% code coverage across new modules
  • ✅ Zero technical debt introduced
  • ✅ SOLID principles throughout
  • ✅ Production-ready telemetry

Architecture Quality

  • ✅ Open/Closed Principle - no core modification needed
  • ✅ Dependency Inversion - depends on abstractions
  • ✅ Single Responsibility - focused, cohesive modules
  • ✅ Interface Segregation - protocol-based design

Developer Experience

  • ✅ Declarative registration with @register_vertical
  • ✅ Type-safe metadata extraction
  • ✅ Clear error messages for debugging
  • ✅ Observable operations with telemetry

Production Readiness

  • ✅ OpenTelemetry integration
  • ✅ Performance monitoring with spans
  • ✅ Async-safe operations
  • ✅ Graceful degradation on missing dependencies

Conclusion

The Victor verticals architecture refactoring successfully addresses all 10 identified issues while maintaining 100% backward compatibility. The new design is modular, performant, well-tested, and production-ready.

Status: ✅ Production-Ready
Breaking Changes: ❌ None
Backward Compatibility: ✅ 100%
Test Coverage: ✅ 93%
Performance Improvement: ✅ 200-500ms faster startup

For migration instructions, see Migration Guide.
For API reference, see API Reference.
For best practices, see Best Practices.