Skip to content

ARCHITECTURE_DIFF.md

Latest commit

 

History

History
393 lines (323 loc) · 13 KB

ARCHITECTURE_DIFF.md

File metadata and controls

393 lines (323 loc) · 13 KB

HUMMBL MCP Server: OLD vs NEW Architecture

Date: 2026-01-21 Status: NEW architecture implemented, enhancements planned

Quick Summary

Aspect OLD Version NEW Version
Purpose Stateless mental models lookup Stateful sessions + observability
Storage None (ephemeral) Redis (cache) + D1 (persistent)
Observability None Full stack (logs, metrics, traces)
Complexity ~500 LOC ~2,000+ LOC
Deployment stdio only stdio + potential HTTP/SSE
State None Session + History tracking

Architecture Comparison

OLD Version: Minimal MCP Server

┌─────────────────────────────────────┐
│         MCP Client (Claude)          │
└─────────────────┬───────────────────┘
                  │ stdio
                  ▼
┌─────────────────────────────────────┐
│          HUMMBL MCP Server           │
│  ┌───────────────────────────────┐  │
│  │   Tools Layer (6 tools)       │  │
│  ├───────────────────────────────┤  │
│  │   Resources (3 URIs)          │  │
│  ├───────────────────────────────┤  │
│  │   Base120 Framework (data)    │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘

Characteristics:

  • ✅ Simple, fast, reliable
  • ✅ Perfect for read-only mental models
  • ❌ No state persistence
  • ❌ No usage tracking
  • ❌ Can't build on previous interactions

NEW Version: Production-Ready with Persistence

┌─────────────────────────────────────┐
│         MCP Client (Claude)          │
└─────────────────┬───────────────────┘
                  │ stdio
                  ▼
┌─────────────────────────────────────────────────────┐
│               HUMMBL MCP Server                      │
│  ┌───────────────────────────────────────────────┐  │
│  │          Tools Layer (6 + new)                │  │
│  │    • get_model                                │  │
│  │    • search_models                            │  │
│  │    • recommend_models                         │  │
│  │    • [future: guided workflows]               │  │
│  └───────────────────────────────────────────────┘  │
│                           │                          │
│  ┌────────────────────────┴──────────────────────┐  │
│  │          Storage Layer                        │  │
│  │    ┌──────────────┐    ┌──────────────┐     │  │
│  │    │ Session Mgr  │    │ History Mgr  │     │  │
│  │    └──────┬───────┘    └──────┬───────┘     │  │
│  │           │                     │             │  │
│  │    ┌──────▼───────┐    ┌──────▼───────┐     │  │
│  │    │ Redis Client │    │  D1 Client   │     │  │
│  │    │  (cache)     │    │ (durable)    │     │  │
│  │    └──────────────┘    └──────────────┘     │  │
│  └───────────────────────────────────────────────┘  │
│                           │                          │
│  ┌────────────────────────┴──────────────────────┐  │
│  │       Observability Layer                     │  │
│  │    ┌────────┐  ┌─────────┐  ┌──────────┐    │  │
│  │    │ Logger │  │ Metrics │  │ Tracing  │    │  │
│  │    │(struct)│  │(Prom)   │  │ (OTEL)   │    │  │
│  │    └────────┘  └─────────┘  └──────────┘    │  │
│  └───────────────────────────────────────────────┘  │
│                           │                          │
│  ┌────────────────────────┴──────────────────────┐  │
│  │          Base120 Framework                    │  │
│  │         (120 Mental Models)                   │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
           │                    │
           ▼                    ▼
     ┌──────────┐        ┌────────────┐
     │  Redis   │        │ Cloudflare │
     │  Cache   │        │     D1     │
     └──────────┘        └────────────┘

Characteristics:

  • ✅ All benefits of OLD version
  • ✅ State persistence across conversations
  • ✅ Multi-turn workflows possible
  • ✅ Production observability (logs, metrics, traces)
  • ✅ Usage analytics capability
  • ✅ Scalable architecture (cache + database)

Detailed Component Comparison

1. Tools Layer

OLD

// 6 basic tools, no state
- get_model(code)
- list_all_models(filter?)
- search_models(query)
- recommend_models(problem)
- get_transformation(key)
- search_problem_patterns(query)

NEW

// Same 6 tools + infrastructure for stateful tools
- [All above tools] ✅
- [PLANNED] apply_guided_workflow(problem, type)
- [PLANNED] get_my_usage_stats(period)

2. Storage Layer

OLD

❌ None - fully stateless

NEW

✅ SessionManager
   - Redis cache (hot data, 24h TTL)
   - D1 database (cold storage, permanent)
   - Session versioning (optimistic locking)
   - Activity tracking

✅ HistoryManager
   - Message history per session
   - Conversation context preservation
   - Replay capabilities

Storage Flow:

Request → SessionManager.get(sessionId)
            ↓
        Redis Check
            ├── HIT → return from Redis
            └── MISS → fetch from D1 → cache in Redis

Update → SessionManager.update(session)
            ↓
         Write to Redis (immediate)
            ↓
         Write to D1 (async, durable)

3. Observability Layer

OLD

❌ None - no visibility into usage

NEW

✅ Logger (src/observability/logger.ts)
   - Structured JSON logs
   - Contextual data (userId, sessionId)
   - Log levels (debug, info, warn, error)
   - Timer decorators for performance

✅ Metrics (src/observability/metrics.ts)
   - Counter: session create/get/update counts
   - Gauge: active sessions
   - Histogram: operation durations
   - Cache hit/miss rates

✅ Tracing (src/observability/tracing.ts)
   - OpenTelemetry instrumentation
   - Span creation with @trace decorator
   - Distributed tracing ready
   - Performance profiling

Metrics Available:

- session_create_total
- session_create_duration_seconds
- cache_hit_total / cache_miss_total
- active_sessions_count
- d1_write_total / d1_read_total

4. Type System

OLD

// Basic types only
- MentalModel
- Transformation
- ProblemPattern
- Result<T, E>

NEW

// Enhanced type coverage
- [All OLD types] ✅
- Session (with metadata)
- SessionMetadata (tracking)
- DomainState (flexible state)
- Message (conversation history)
- MessageRole (user/assistant/system)

Code Organization

OLD Structure

src/
├── index.ts          (80 LOC)
├── server.ts         (27 LOC)
├── framework/
│   └── base120.ts    (~1500 LOC - data)
├── tools/
│   └── models.ts     (405 LOC)
├── resources/
│   └── models.ts     (109 LOC)
├── types/
│   └── domain.ts     (70 LOC)
└── utils/
    └── result.ts     (25 LOC)

Total: ~2,200 LOC (mostly data)

NEW Structure

src/
├── index.ts                      (26 LOC)
├── server.ts                     (27 LOC)
├── framework/
│   └── base120.ts                (~1500 LOC - data)
├── tools/
│   └── models.ts                 (405 LOC)
├── resources/
│   └── models.ts                 (109 LOC)
├── storage/                      ⭐ NEW
│   ├── session-manager.ts        (350 LOC)
│   ├── history-manager.ts        (280 LOC)
│   ├── redis-client.ts           (100 LOC)
│   └── d1-client.ts             (120 LOC)
├── observability/                ⭐ NEW
│   ├── logger.ts                 (180 LOC)
│   ├── metrics.ts                (200 LOC)
│   └── tracing.ts                (180 LOC)
├── types/
│   ├── domain.ts                 (70 LOC)
│   ├── session.ts                ⭐ NEW (80 LOC)
│   └── message.ts                ⭐ NEW (60 LOC)
└── utils/
    ├── result.ts                 (25 LOC)
    └── sanitize.ts               ⭐ NEW (120 LOC)

Total: ~3,800 LOC (+73% code, infrastructure)

Performance Characteristics

Operation OLD NEW (Cache Hit) NEW (Cache Miss)
Get Model ~2ms ~2ms ~2ms
Search ~5ms ~5ms ~5ms
Create Session N/A ~15ms (Redis) ~50ms (Redis+D1)
Get Session N/A ~3ms (Redis) ~20ms (D1)
Update Session N/A ~8ms (Redis) ~30ms (Redis+D1)

Memory:

  • OLD: ~10MB (data only)
  • NEW: ~15MB (data + Redis client + OTEL)

Migration Path

If you're on OLD version:

# No breaking changes - NEW is backward compatible
npm install @hummbl/mcp-server@latest

# Optional: Enable storage (requires env vars)
REDIS_URL=redis://localhost:6379
D1_DATABASE_ID=your-d1-id

# Optional: Enable observability
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

If you don't need persistence:

  • NEW version works exactly like OLD (stateless mode)
  • Storage only activates when Redis URL is configured
  • Zero performance penalty if not used

Use Case Fit

When to use OLD architecture:

  • ✅ Simple mental model lookup
  • ✅ One-off queries
  • ✅ No need for history
  • ✅ Minimal dependencies
  • ✅ Learning/experimentation

When to use NEW architecture:

  • ✅ Multi-turn problem solving
  • ✅ Guided workflows
  • ✅ Usage analytics needed
  • ✅ Production deployment
  • ✅ Team/organization rollout
  • ✅ Continuous improvement based on data

What This Enables

With the NEW architecture, we can now build:

  1. Guided Workflows ✨

    • Multi-step problem solving
    • Session-based state tracking
    • Resume interrupted analysis

  2. User Analytics 📊

    • Which models are most useful
    • Common problem patterns
    • Workflow success rates

  3. Personalization 🎯

    • Recommend models based on user history
    • Adapt to user expertise level
    • Custom workflow templates

  4. Collaboration 🤝

    • Share analysis sessions
    • Team-wide usage patterns
    • Organizational learning

  5. Production Operations 🚀

    • Monitor health and performance
    • Debug issues with traces
    • Scale based on metrics

Summary

The NEW version is backward compatible but adds a production-grade foundation for:

  • State persistence
  • Multi-turn interactions
  • Usage analytics
  • Operational visibility

The mental models are the same. The capabilities are vastly expanded.

Ready for enhancement implementation. See ENHANCEMENT_PLAN.md for next steps.