Windsurf Reference Architecture

Overview

Project architecture optimized for Windsurf (Codeium) AI-assisted development. Covers workspace configuration, Cascade AI flow optimization, rules files for context, and team standardization patterns.

Prerequisites

• Windsurf IDE installed
• Team agreement on coding standards
• Repository with consistent project structure
• Understanding of Cascade AI flows

Architecture Diagram

┌──────────────────────────────────────────────────────┐
│              Windsurf Workspace                       │
│  ┌───────────────┐  ┌────────────────────────────┐    │
│  │ .windsurfrules│  │ .windsurf/settings.json    │    │
│  │ (AI context)  │  │ (IDE configuration)        │    │
│  └───────────────┘  └────────────────────────────┘    │
├──────────────────────────────────────────────────────┤
│              Cascade AI Engine                        │
│  ┌───────────┐  ┌───────────┐  ┌─────────────────┐   │
│  │ Inline    │  │ Chat      │  │ Multi-file      │   │
│  │ Complete  │  │ (Cascade) │  │ Edit            │   │
│  └───────────┘  └───────────┘  └─────────────────┘   │
├──────────────────────────────────────────────────────┤
│              Project Structure                        │
│  src/ │ tests/ │ docs/ │ .windsurf/ │ .windsurfrules │
├──────────────────────────────────────────────────────┤
│              Indexing Engine                           │
│  Semantic Index │ File Cache │ Dependency Graph       │
└──────────────────────────────────────────────────────┘

Instructions

Step 1: Create Windsurf Rules File

<!-- .windsurfrules - Project context for Cascade AI -->

# Project: MyApp

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS v3
- State: Zustand
- Testing: Vitest + React Testing Library
- Database: PostgreSQL with Drizzle ORM

## Architecture Patterns
- Server Components by default, Client Components only when needed
- API routes in app/api/ using Route Handlers
- Shared types in types/ directory
- Business logic in services/ directory
- Database queries in db/ directory

## Coding Standards
- Named exports only, never default exports
- Use async/await, never raw Promises
- All functions must have JSDoc comments
- Error handling: use Result pattern, never throw in services
- Use zod for all runtime validation

Step 2: Configure Workspace Settings

{
  "codeium.indexing.excludePatterns": [
    "node_modules/**",
    ".next/**",
    "dist/**",
    "coverage/**",
    "*.min.js",
    "**/*.map"
  ],
  "codeium.autocomplete.enable": true,
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "typescript.tsdk": "node_modules/typescript/lib",
  "files.associations": {
    "*.css": "tailwindcss"
  }
}

Step 3: Team Configuration Template

// .windsurf/team-config.json - Shared team settings
{
  "cascade": {
    "preferredModels": ["claude-sonnet", "gpt-4o"],
    "contextRules": {
      "maxContextFiles": 15,
      "preferOpenTabs": true,
      "includeTestFiles": true,
      "includeTypeDefinitions": true
    },
    "codeGeneration": {
      "language": "typescript",
      "strictMode": true,
      "includeTypes": true,
      "includeTests": false
    }
  },
  "formatting": {
    "tabSize": 2,
    "useTabs": false,
    "trailingComma": "all",
    "singleQuote": true,
    "printWidth": 100
  }
}

Step 4: Project-Specific Context Files

// .windsurf/patterns.md - Common patterns for Cascade
/**
 * API Route Pattern:
 * ```typescript
 * export async function GET(req: NextRequest) {
 *   const params = searchParamsSchema.parse(Object.fromEntries(req.nextUrl.searchParams));
 *   const result = await service.find(params);
 *   return NextResponse.json(result);
 * }
 * ```
 *
 * Service Pattern:
 * ```typescript
 * export async function findById(id: string): Promise<Result<Entity, AppError>> {
 *   const entity = await db.query.entities.findFirst({ where: eq(entities.id, id) });
 *   if (!entity) return err(new NotFoundError('Entity', id));
 *   return ok(entity);
 * }
 * ```
 */

Error Handling

Examples

Monorepo Rules File

<!-- .windsurfrules for monorepo -->
# Monorepo Structure
- packages/api - Express REST API (Node.js)
- packages/web - Next.js frontend
- packages/shared - Shared TypeScript types and utilities
- packages/db - Database schema and migrations (Drizzle)

When editing files in packages/api, use Express patterns.
When editing files in packages/web, use Next.js App Router patterns.
Always import from @repo/shared for shared types.

Resources

• Windsurf Documentation
• Cascade AI Guide
• Windsurf Rules Reference

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale