Initial commit: WealthWise financial analytics platform
This commit is contained in:
260
AGENTS.md
Normal file
260
AGENTS.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```tsx
|
||||
<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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```python
|
||||
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
|
||||
Reference in New Issue
Block a user