Stack Architecture Design

Design transport-agnostic handler systems with proper Result types and error taxonomy.

Process

Step 1: Understand Requirements

Gather information about:

• Transport surfaces — CLI, MCP, HTTP, or all?
• Domain operations — What actions does the system perform?
• Failure modes — What can go wrong? (maps to error taxonomy)
• External dependencies — APIs, databases, file system?

Step 2: Design Handler Layer

For each domain operation:

1. Define input type (Zod schema)
2. Define output type
3. Identify possible error types (from taxonomy)
4. Write handler signature: Handler<Input, Output, Error1 | Error2>

Example:

// Input schema
const CreateUserInputSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1),
});

// Output type
interface User {
  id: string;
  email: string;
  name: string;
}

// Handler signature
const createUser: Handler<unknown, User, ValidationError | ConflictError>;

Step 3: Map Errors to Taxonomy

Map domain errors to the 10 categories:

Step 4: Choose Packages

Packages are organized into three tiers:

Package Tiers

┌─────────────────────────────────────────────────────────────────┐
│                        TOOLING TIER                              │
│  Build-time, dev-time, test-time packages                       │
│  @outfitter/testing                                             │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ depends on
┌─────────────────────────────────────────────────────────────────┐
│                        RUNTIME TIER                              │
│  Application-specific packages for different deployment targets  │
│  @outfitter/cli    @outfitter/mcp    @outfitter/daemon          │
│  @outfitter/config @outfitter/logging @outfitter/file-ops       │
│  @outfitter/state                                               │
└─────────────────────────────────────────────────────────────────┘
                              ▲
                              │ depends on
┌─────────────────────────────────────────────────────────────────┐
│                       FOUNDATION TIER                            │
│  Zero-runtime-dependency core packages                          │
│  @outfitter/contracts    @outfitter/types                       │
└─────────────────────────────────────────────────────────────────┘

Package Selection

Selection criteria:

• All projects need @outfitter/contracts (foundation)
• CLI applications add @outfitter/cli (includes UI components)
• MCP servers add @outfitter/mcp
• File operations need both @outfitter/config (paths) and @outfitter/file-ops (safety)

Step 5: Design Context Flow

Determine:

• Entry points — Where is context created? (CLI main, MCP server, HTTP handler)
• Context contents — Logger, config, signal, workspaceRoot
• Tracing — How requestId flows through operations

Output Templates

Architecture Overview

Project: {PROJECT_NAME}
Transport Surfaces: {CLI | MCP | HTTP | ...}

Directory Structure:
├── src/
│   ├── handlers/           # Transport-agnostic business logic
│   │   ├── {handler-1}.ts
│   │   └── {handler-2}.ts
│   ├── commands/           # CLI adapter (if CLI)
│   ├── tools/              # MCP adapter (if MCP)
│   └── index.ts            # Entry point
└── tests/
    └── handlers/           # Handler tests

Dependencies:
├── @outfitter/contracts    # Foundation (always)
├── @outfitter/{package-2}  # {reason}
└── @outfitter/{package-3}  # {reason}

Handler Inventory

Error Strategy

Domain Errors → Stack Taxonomy:

{domain-error-1} → {stack-category} ({ErrorClass})
  - When: {condition}
  - Exit code: {code}

{domain-error-2} → {stack-category} ({ErrorClass})
  - When: {condition}
  - Exit code: {code}

Implementation Order

1. Foundation — Install packages, create types
2. Core handlers — Implement business logic with tests
3. Transport adapters — Wire up CLI/MCP/HTTP
4. Testing — Integration tests across transports

Constraints

Always:

• Recommend Result types over exceptions
• Map domain errors to taxonomy categories
• Design handlers as pure functions (input, context) → Result
• Consider all transport surfaces upfront
• Include error types in handler signatures

Never:

• Suggest throwing exceptions
• Design transport-specific logic in handlers
• Recommend hardcoded paths
• Skip error type planning
• Couple handlers to specific transports

Related Skills

• outfitter-stack:stack-patterns — Reference for all patterns
• outfitter:tdd — TDD implementation methodology
• outfitter-stack:stack-templates — Templates for components