Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Fuzzy Architecture Pattern

What Is Fuzzy Architecture?

Traditional architecture: Detailed upfront design, rigid boundaries, specific technologies.

Traditional: “Because iteration is expensive while specification/conceptualization is cheap”

  • You can write detailed docs, diagrams, interfaces relatively cheaply
  • But changing the actual implementation is costly

Fuzzy architecture: Intentionally vague starting point that crystallizes through implementation.

Like sculpture - you start with a rough shape and refine by removing what doesn’t belong.

Fuzzy/Vibe: “Because iteration is expensive while specification is expensive”

  • Writing precise specs is hard/time-consuming when you don’t know what you need
  • You are probably not experienced with architecture so picking a one without knowing what works well is problematic.
  • Also there is good chnance you dont know the full reqirements yet. And missing one core requirement means architecture should be recreated. Which is costly.
  • Better to build something rough and refine it.

The core trade-off seems to be about when you pay the cost - upfront planning/specification vs. during implementation/discovery. With AI/vibe coding, you’re betting that discovering the right architecture through building is more efficient than trying to specify it perfectly beforehand.

Why Fuzzy Works with AI

The Overspecification Trap

Detailed architecture upfront:

"Use PostgreSQL with Redis cache, implement Repository pattern 
with Unit of Work, deploy on Kubernetes with Istio service mesh..."

Result: Overengineered before you write a line of code.

The Underspecification Trap

No architecture:

"Build me an app"

Result: AI makes random choices, inconsistent patterns.

The Fuzzy Sweet Spot

Just enough structure:

"Web app with database persistence and API.
Start simple, we'll refine as we build."

Result: Room to discover the right architecture.

Core Principles of Fuzzy Architecture

1. Boundaries Not Implementations

Define what, not how:

# Initial Architecture

## Components
- User Interface (how users interact)
- Business Logic (what the app does)
- Data Storage (where information lives)
- External Services (what we integrate with)

## Rules
- UI never talks directly to database
- Business logic owns all rules
- Data layer handles persistence only

No specifics about React vs Vue, SQL vs NoSQL, REST vs GraphQL.

2. Principles Over Patterns

State principles that guide decisions:

## Architectural Principles

1. **Simplicity First**: Choose boring technology
2. **Local First**: Everything works offline
3. **Privacy First**: Data stays on device
4. **Performance**: Sub-second response times
5. **Maintainability**: New developer productive in 1 hour

These principles shape choices naturally.

3. Evolution Points

Mark where architecture will likely change:

## Evolution Points

- Storage: Start with JSON files → SQLite → PostgreSQL
- API: Start with function calls → REST → GraphQL if needed
- Auth: Start with none → Basic → OAuth when required
- Deploy: Start local → Single server → Scale when needed

This prevents AI from optimizing prematurely.

Implementing Fuzzy Architecture

Phase 1: Sketch the Shape

Create initial architecture.md:

# Architecture Overview

## High-Level Structure

[User Interface] ↓ [Application Logic] ↓ [Data Layer]


## Component Responsibilities

**User Interface**
- Display information
- Collect user input
- Handle user interactions

**Application Logic**  
- Process business rules
- Coordinate between layers
- Maintain application state

**Data Layer**
- Store and retrieve data
- Ensure data integrity
- Handle persistence

## Key Decisions Deferred
- Specific UI framework
- Database technology
- API protocol
- Deployment method

Phase 2: First Implementation

Let AI propose concrete choices:

"Based on this architecture and our requirements,
what would be good technology choices for a first implementation?
Keep it simple."

AI might suggest:

  • UI: Plain HTML + Alpine.js
  • Logic: Python Flask
  • Data: SQLite

Phase 3: Refinement Cycles

As you build, architecture solidifies:

# Architecture Overview (Updated)

## Technology Stack
- Frontend: Alpine.js for reactivity (chose for simplicity)
- Backend: Flask (lightweight, perfect for our needs)
- Database: SQLite (portable, no setup required)

## Patterns Discovered
- Service layer pattern emerged naturally
- Event system for loose coupling
- Command pattern for user actions

The Architecture Dialogue

Starting Fuzzy

Human: "I need an expense tracker"
AI: "What architecture should we use?"
Human: "Let's start fuzzy - separate UI, logic, and data. 
        We'll refine as we build."

Guided Evolution

AI: "Should we add caching?"
Human: "Is performance a problem?"
AI: "Not yet"
Human: "Then no caching. Keep it simple."

Natural Boundaries

AI: "This function is getting complex"
Human: "What pattern is emerging?"
AI: "Looks like command processing"
Human: "Let's extract a command handler pattern"

Fuzzy Architecture Artifacts

The Living Architecture Document

Update architecture.md as patterns emerge:

# Architecture (Living Document)

## Current State (Week 3)
- Clear MVC separation has emerged
- Service layer handles business logic
- Repository pattern for data access
- Event bus for loose coupling

## Decisions Made
- SQLite over PostgreSQL (simplicity won)
- Server-side rendering over SPA (speed won)
- Monolith over microservices (maintainability won)

## Future Considerations
- May need job queue for reports
- Might add caching if user base grows
- Could extract analytics into service

Decision Records

Document why architecture evolved:

# ADR-001: Use SQLite instead of PostgreSQL

## Status: Accepted

## Context
Initially kept database choice fuzzy. Now need to decide.

## Decision  
Use SQLite for local-first architecture.

## Consequences
- ✓ Zero configuration
- ✓ Portable data files
- ✓ Perfect for single-user app
- ✗ Limited concurrent writes
- ✗ No advanced SQL features

Can migrate to PostgreSQL later if needed.

Anti-Patterns to Avoid

Premature Crystallization

Don’t lock in too early:

Week 1: "We'll definitely need microservices"
Week 4: "Actually, a monolith is perfect"

Fuzzy Forever

Eventually commit:

Month 6: "We still haven't decided on a database"

Fuzzy is for discovery, not procrastination.

Architecture Astronauting

Don’t add complexity for future scenarios:

"We might need to scale to millions of users"
"Let's solve that when we have thousands"

Benefits of Fuzzy Architecture

1. Faster Start

Less upfront planning = quicker first version

2. Better Fit

Architecture matches actual needs, not imagined ones

3. Less Waste

Don’t build infrastructure you don’t need

4. Natural Patterns

Right abstractions emerge from real use

5. AI Alignment

AI proposes solutions that fit current state

The Fuzzy Lifecycle

Fuzzy (Week 1-2)
    ↓
Emerging (Week 3-4)
    ↓
Solidifying (Week 5-8)
    ↓
Stable (Week 9+)

Each phase has different flexibility.

Practical Fuzzy Techniques

The Proxy Pattern

Start with simplest version:

class DataStore:
    """Fuzzy data layer - might be JSON, SQLite, or PostgreSQL"""
    
    def save(self, data):
        # Start with JSON
        with open("data.json", "w") as f:
            json.dump(data, f)
    
    def load(self):
        # Easy to swap later
        with open("data.json") as f:
            return json.load(f)

The Feature Flag Evolution

# Week 1: Direct implementation
if user.is_premium:
    show_advanced_features()

# Week 4: Pattern emerges
if feature_enabled("advanced_features", user):
    show_advanced_features()

# Week 8: Full feature system
if feature_flag.check("advanced_features", context=user):
    show_advanced_features()

The Gradual Extraction

Week 1: Everything in app.py
Week 2: Extract models.py
Week 3: Extract services.py
Week 4: Extract repositories.py
Week 5: Clear architecture emerged

When to Stop Being Fuzzy

Signs It’s Time to Solidify

  1. Same patterns appearing repeatedly
  2. Team needs clear structure
  3. Performance requires specific choices
  4. Integration demands concrete interfaces

The Crystallization Moment

"Our fuzzy architecture has revealed these patterns:
- Service layer for business logic
- Repository pattern for data access  
- Event system for integrations

Let's formalize these as our architecture."

Fuzzy Architecture with AI

Setting Context

"We're using fuzzy architecture. Start simple,
we'll refine based on what we learn."

Guiding Evolution

"Given what we've built so far,
what architectural pattern is emerging?"

Preventing Premature Optimization

"That's a good idea for later.
For now, what's the simplest thing that works?"

The Meta-Pattern

Fuzzy architecture is itself fuzzy. Don’t over-formalize the informality. Let it guide you naturally toward the right structure.

Start fuzzy. Build. Learn. Solidify. This is the way.

Next: Part IV - The Vibe Coding Method →