Windsurf Architecture Variants

Overview

How you structure your Windsurf workspace directly impacts Cascade's effectiveness. Large monorepos, multi-service setups, polyglot codebases, and different team sizes each require different approaches. This skill covers workspace strategies from solo projects to 100+ developer organizations.

Prerequisites

• Windsurf installed
• Understanding of Cascade's workspace indexing model
• Git workflow established

Instructions

Variant 1: Single Project (Solo / Small Team)

Best for: 1-3 developers, single service, <10K files.

my-project/
├── .windsurfrules          # Full project context
├── .codeiumignore          # Exclude build artifacts
├── src/
├── tests/
├── package.json
└── README.md

Configuration:

• Open entire project as workspace
• Cascade indexes everything — no partitioning needed
• .windsurfrules contains complete stack and architecture details

Variant 2: Focused Monorepo Windows (Medium Team)

Best for: 3-15 developers, monorepo with 2-10 packages.

monorepo/
├── .windsurfrules          # Brief shared conventions
├── .codeiumignore          # Aggressive exclusions at root
├── packages/
│   ├── api/
│   │   ├── .windsurfrules  # API-specific rules
│   │   └── .codeiumignore
│   ├── web/
│   │   ├── .windsurfrules  # Frontend-specific rules
│   │   └── .codeiumignore
│   └── shared/
│       ├── .windsurfrules  # Library conventions
│       └── .codeiumignore
└── .windsurf/
    └── workflows/          # Shared workflows

Strategy:

# Each developer opens their package directory:
windsurf packages/api/        # Backend dev
windsurf packages/web/        # Frontend dev
windsurf packages/shared/     # Library maintainer

# NOT: windsurf monorepo/     # Too broad!

Variant 3: Multi-Window Team Workflow (Large Team)

Best for: 15+ developers, microservices, 50K+ total files.

Developer A: Windsurf → services/auth/        (auth service)
Developer B: Windsurf → services/payments/    (payments)
Developer C: Windsurf → services/notifications/ (notifications)
Developer D: Windsurf → shared/libs/          (shared libraries)

Each developer gets focused Cascade context per workspace window.

Team conventions:

1. One Windsurf window per service/package
2. Every service has its own .windsurfrules and .codeiumignore
3. Cascade tasks scoped to current workspace only
4. Cross-service changes: open both workspaces side by side
5. Tag cascade commits: git commit -m "[cascade] description"
6. Use shared workflows from central config repo

Variant 4: Polyglot / Multi-Language

Best for: Projects with multiple languages (TypeScript + Python + Go).

# Each language has different .windsurfrules
services/
├── ts-api/
│   └── .windsurfrules     # TypeScript patterns, Fastify, Vitest
├── python-ml/
│   └── .windsurfrules     # Python patterns, FastAPI, pytest
└── go-gateway/
    └── .windsurfrules     # Go patterns, chi router, go test

<!-- .windsurfrules for Python service -->
# Project: ML Pipeline

## Stack
- Language: Python 3.11
- Framework: FastAPI
- ML: scikit-learn, pandas
- Testing: pytest with fixtures
- Type checking: mypy (strict)

## Conventions
- Use pydantic for all data models
- Async endpoints with asyncio
- Type hints on all functions
- No print() — use logging module

Variant 5: Frontend-Heavy (Design System)

Best for: UI-heavy projects with design system, Storybook, component library.

<!-- .windsurfrules for design system -->
# Project: Design System

## Stack
- Framework: React 18 + Next.js 14
- Styling: Tailwind CSS + custom tokens
- Components: Radix UI primitives
- Docs: Storybook 8
- Testing: Vitest + Testing Library

## Component Conventions
- One component per file (ComponentName.tsx)
- Co-located tests: ComponentName.test.tsx
- Co-located stories: ComponentName.stories.tsx
- Props interface exported: ComponentNameProps
- Use forwardRef for all components
- Use CVA (class-variance-authority) for variants

## Design Tokens
- Colors: use design-system/tokens, never raw Tailwind colors
- Spacing: use space-* scale (4px base)
- Typography: use text-* presets

Cascade integration: Use Previews to iterate on UI components:

"Preview the Button component with all variants"
Click elements in Preview → send to Cascade for refinement

Decision Matrix

Error Handling

Examples

Optimized .codeiumignore (Universal)

node_modules/
dist/
build/
.next/
coverage/
*.min.js
*.map
__pycache__/
.venv/
target/
vendor/
*.log
*.sqlite

Workspace Health Check

set -euo pipefail
FILE_COUNT=$(find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | wc -l)
echo "Indexed files: ~$FILE_COUNT"
[ "$FILE_COUNT" -gt 10000 ] && echo "WARNING: Consider opening a subdirectory"
[ -f .windsurfrules ] && echo "Rules: $(wc -c < .windsurfrules) chars" || echo "Rules: MISSING"
[ -f .codeiumignore ] && echo "Ignore: $(wc -l < .codeiumignore) patterns" || echo "Ignore: MISSING"

Resources

• Windsurf Context Awareness
• Windsurf Ignore

Next Steps

For known pitfalls and anti-patterns, see windsurf-known-pitfalls.