Windsurf Rules for Portfolione Project

# Windsurf Rules for Portfolione Project

## Project Overview
- Next.js 14 with App Router
- TypeScript + React
- shadcn/ui components (New York style)
- Tailwind CSS with CSS variables
- Account Kit integration for wallet functionality



## Project Description

This project aims to develop a modern, responsive portfolio management application built on Next.js 14, leveraging the App Router, TypeScript, and shadcn/ui components. The core functionality revolves around enabling users to view and rebalance their cryptocurrency portfolios. Initially, the application will focus on **single-chain operations on Base**, utilizing 1inch Fusion Swap for efficient token exchanges. A key architectural principle is the design of highly composable and modular swap functionality, ensuring a clear and straightforward upgrade path to **cross-chain rebalancing** using 1inch Fusion+ in the future.

At its heart, the application integrates **Alchemy Account Kit** for a seamless and abstracted wallet experience, supporting both traditional connected wallets (like MetaMask) and potentially email/social logins. This integration is crucial for enabling advanced features such as **transaction batching** for multiple swaps within a single user operation and **gas sponsorship**, significantly enhancing the user experience by abstracting away complex blockchain interactions and gas fees. The application will guide users on how to manage funds from their Externally Owned Accounts (EOAs) within the smart account context to fully leverage these benefits.

---
## Code Standards

### Web3 aspects

- Refer to [Alchemy docs](https://www.alchemy.com/docs) when making any changes related to web3 and blockchain configuration. Specifically, for wallet functionality and smart account interactions, consult the [Alchemy Account Kit documentation](https://www.alchemy.com/docs/wallets/react/quickstart/new-project).
- The application will primarily use **1inch Fusion Swap** for on-chain token swaps on the Base network. The integration will leverage the 1inch API for fetching quotes and constructing swap transactions. For detailed API specifications, refer to the [1inch API Portal](https://portal.1inch.dev/documentation/apis/) and more specifically the classic swap api [here](https://portal.1inch.dev/documentation/apis/swap/classic-swap/quick-start).
- **Transaction Batching & Gas Sponsorship:** The application will utilize Alchemy Account Kit's capabilities to batch multiple swap transactions into a single user operation, providing a smoother user experience for portfolio rebalancing. Gas for these batched transactions will be sponsored via a configured Alchemy gas policy, abstracting gas fees from the end-user. This functionality is enabled by the underlying smart account architecture provided by Alchemy Account Kit. For more details on how this works with connected wallets (e.g., MetaMask) and gas policies, refer to the [Alchemy documentation on sending user operations](https://www.alchemy.com/docs/wallets/react/send-user-operations) and [gas sponsorship](https://www.alchemy.com/docs/wallets/react/sponsor-gas).
- **Future Cross-Chain Expansion:** The swap functionality is designed with composability in mind. While starting on Base with 1inch Fusion Swap, the architecture will allow for a straightforward transition to **cross-chain rebalancing** using the [1inch Fusion+ SDK](https://portal.1inch.dev/documentation/apis/swap/fusion-plus/fusion-plus-sdk/for-integrators/sdk-overview). The `api.md` document provides comprehensive details on both Classic Swap and Fusion+ SDK implementations, including endpoint usage and transaction flows, which will be critical for this modular upgrade.
- **Detailed Documentation:** For in-depth design decisions and comprehensive API usage, refer to the Markdown files located in the `docs/` directory. This includes the detailed application design (`rebalancing_app_design_enhanced.md`) and the exhaustive 1inch API documentation (`1inch API Documentation for React_Next.js dApps.md`).


### File Organization
- Use `app/` directory for pages and layouts
- Components in `components/` with UI components in `components/ui/`
- Utilities in `lib/` directory
- Use TypeScript for all files (.tsx, .ts)

### Naming Conventions
- Components: PascalCase (e.g., `UserProfile.tsx`)
- Files: kebab-case for pages, PascalCase for components
- Variables: camelCase
- Constants: UPPER_SNAKE_CASE

### Component Patterns
- Prefer function components with hooks
- Use shadcn/ui components when available before creating custom ones
- Import shadcn components from `@/components/ui/`
- Use Tailwind classes for styling, prefer CSS variables from shadcn theme

### shadcn/ui Guidelines
- Always use existing shadcn components when possible
- Follow the "New York" style variant
- Use `cn()` utility for conditional classes
- Maintain consistent spacing and typography scale

### TypeScript
- Use strict TypeScript settings
- Define proper interfaces for props and data structures
- Avoid `any` type, use proper typing
- Use type imports when importing only types

### Imports
- Use path aliases: `@/components`, `@/lib`, `@/app`
- Group imports: React/Next, third-party, local components, utilities
- Use named imports when possible

### Styling
- Use Tailwind CSS classes
- Follow mobile-first responsive design
- Use CSS variables for theming (already configured)
- Prefer utility classes over custom CSS

## Account Kit Integration
- Use existing Account Kit setup for wallet functionality
- Follow patterns established in the current codebase
- Maintain proper error handling for wallet operations

## Performance
- Use Next.js Image component for images
- Implement proper loading states
- Use React.memo() for expensive components when needed
- Lazy load components when appropriate

## Accessibility
- Use semantic HTML elements
- Ensure proper ARIA labels
- Maintain keyboard navigation support
- Follow shadcn/ui accessibility patterns

## Error Handling
- Use proper error boundaries
- Implement user-friendly error messages
- Log errors appropriately for debugging

## Testing
- Write unit tests for utility functions
- Test component rendering and interactions
- Mock external dependencies properly