WealthWise/AGENTS.md

AGENTS.md - Coding Guidelines for WealthWise

Project Overview

WealthWise is a financial analytics platform with:

• Frontend: React + TypeScript + Vite + shadcn/ui + Tailwind CSS
• Backend: FastAPI + SQLModel + PostgreSQL + Poetry

Build & Development Commands

Frontend (Root Directory)

# Install dependencies
npm install

# Development server (runs on port 7863)
npm run dev

# Production build
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# Deploy to Vercel
npm run deploy      # Production
npm run deploy:dev  # Development

Backend (/backend Directory)

# Install dependencies
poetry install

# Run development server
poetry run uvicorn app.main:app --reload --port 8080

# Run production server
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8080

# Run tests
poetry run pytest
poetry run pytest -v                    # Verbose
poetry run pytest tests/test_auth.py    # Single test file
poetry run pytest -k "test_name"        # Single test by name
poetry run pytest --cov=app             # With coverage

# Format and lint
poetry run black .
poetry run isort .
poetry run flake8
poetry run mypy app/

# Database migrations
cd backend
poetry run alembic revision --autogenerate -m "description"
poetry run alembic upgrade head
poetry run alembic downgrade -1

Code Style Guidelines

Frontend - TypeScript/React

Imports

• Use @/ path aliases for all internal imports
• Group imports: React → External libraries → Internal (@/lib, @/components) → Relative
• Use single quotes for string literals

import React, { useState, useCallback } from 'react';
import { useQuery } from '@tanstack/react-query';
import { Button } from '@/components/ui/button';
import { cn } from '@/lib/utils';
import { useAuth } from '@/hooks/useAuth';

Components

• Use functional components with arrow functions
• Add displayName for forwarded ref components
• Use React.FC<Props> for typing components
• Destructure props in function parameters

interface ButtonProps {
  variant?: 'default' | 'outline';
  onClick?: () => void;
}

const Button: React.FC<ButtonProps> = ({ variant = 'default', onClick }) => {
  return <button onClick={onClick}>{children}</button>;
};

Button.displayName = 'Button';

Naming Conventions

• Components: PascalCase (e.g., Dashboard.tsx)
• Hooks: camelCase with use prefix (e.g., useAuth.ts)
• Utils: camelCase (e.g., utils.ts)
• Types/Interfaces: PascalCase (e.g., User, AuthState)
• CSS Classes: Use Tailwind utility classes with cn() helper

Styling (Tailwind + shadcn/ui)

• Use cn() from @/lib/utils for conditional classes
• Follow glassmorphic design with glass, widget classes
• Use CSS variables from index.css for theme colors
• Prefer rounded-xl, rounded-2xl for border radius

<div className={cn(
  "glass-card hover:scale-[1.02] transition-all",
  className
)}>

Error Handling

• Use try/catch with typed errors
• Check for err.response?.data?.detail for API errors
• Set user-friendly error messages in state

State Management

• Use React Query for server state
• Use useState for local UI state
• Use Context API for auth state

Backend - Python/FastAPI

Imports

• Group: Standard library → Third-party → Local app imports
• Use absolute imports for app modules

import time
from datetime import datetime

from fastapi import FastAPI, HTTPException
from sqlmodel import Session, select

from app.core.config import get_settings
from app.models.user import User

Naming Conventions

• Files: snake_case (e.g., auth_service.py)
• Classes: PascalCase (e.g., AuthService)
• Functions/Variables: snake_case (e.g., get_current_user)
• Constants: UPPER_SNAKE_CASE

Type Hints

• Use type hints on all function parameters and return types
• Use Optional[Type] for nullable values
• Use Pydantic models for request/response schemas

def create_user(
    email: str,
    password: str,
    db: Session
) -> Optional[User]:
    """Create a new user."""
    pass

Docstrings

• Use Google-style docstrings
• Document args, returns, and raises

def validate_token(token: str) -> TokenPayload:
    """Validate JWT token.
    
    Args:
        token: JWT token string
        
    Returns:
        TokenPayload with user information
        
    Raises:
        HTTPException: If token is invalid
    """

Error Handling

• Use FastAPI's HTTPException with appropriate status codes
• Handle exceptions at router level when possible
• Log errors with context

Testing

Frontend

No test framework configured yet. Consider adding Vitest for unit testing.

Backend

• Tests located in backend/tests/
• Use pytest with pytest-asyncio for async tests
• Use TestClient for FastAPI integration tests
• Use pytest.raises for exception testing

def test_login_success(client: TestClient):
    response = client.post("/api/v1/auth/login", json={...})
    assert response.status_code == 200

Project Structure

/                         # Frontend (Vite + React)
├── src/
│   ├── components/       # React components
│   │   ├── ui/          # shadcn/ui components
│   │   ├── features/    # Feature components
│   │   └── *.tsx        # Shared components
│   ├── hooks/           # Custom React hooks
│   ├── context/         # React context providers
│   ├── lib/             # Utilities, API clients
│   ├── types/           # TypeScript types
│   └── pages/           # Page components
├── public/              # Static assets
└── package.json

/backend/                # FastAPI backend
├── app/
│   ├── api/v1/         # API routes
│   ├── core/           # Config, db, deps
│   ├── models/         # SQLModel models
│   └── schemas/        # Pydantic schemas
├── tests/              # Test files
├── alembic/            # DB migrations
└── pyproject.toml      # Poetry dependencies

Environment Variables

Frontend (.env):

• VITE_API_URL: Backend API URL

Backend (.env):

• DATABASE_URL: PostgreSQL connection string
• SECRET_KEY: JWT signing key
• SUPABASE_JWT_SECRET: Supabase JWT secret
• DEBUG: Debug mode flag

Critical Rules

1. Never commit secrets or .env files
2. Always use TypeScript strict mode compliance
3. Always run npm run lint before committing frontend changes
4. Always run poetry run black && poetry run flake8 before committing backend changes
5. Use cn() for conditional Tailwind classes
6. Use React Query for all API calls
7. Use proper HTTP status codes in backend responses
8. Write docstrings for all public functions
9. Use Pydantic v2 patterns for validation