billai/AGENTS.md

AGENTS.md - AI Coding Agent Guidelines

This document provides guidelines for AI coding agents working on the BillAI project.

Project Overview

BillAI is a microservices-based personal bill analysis system supporting WeChat and Alipay bill parsing, intelligent categorization, and visualization.

Architecture:

• web/ - Frontend (SvelteKit 5 + TailwindCSS 4.x + TypeScript)
• server/ - Backend API (Go 1.21 + Gin + MongoDB)
• analyzer/ - Python analysis service (Python 3.12 + FastAPI)

Build, Lint, and Test Commands

Frontend (web/)

# Development
npm run dev              # Start dev server (Vite)

# Build
npm run build            # Production build
npm run preview          # Preview production build

# Type checking
npm run check            # svelte-check with TypeScript
npm run check:watch      # Watch mode

# Linting and formatting
npm run lint             # Prettier check + ESLint
npm run format           # Format with Prettier

# Testing
npm run test             # Run all tests once
npm run test:unit        # Run tests in watch mode
npx vitest run src/demo.spec.ts              # Run single test file
npx vitest run -t "sum test"                 # Run tests matching name
npx vitest run src/routes/page.svelte.spec.ts  # Run component test

Backend (server/)

# Run
go run .                 # Start development server

# Build
go build .               # Build binary

# Dependencies
go mod download          # Install dependencies
go mod tidy              # Clean up dependencies

# Testing (if tests exist)
go test ./...            # Run all tests
go test ./handler/...    # Run tests in specific package
go test -run TestName    # Run single test by name

Analyzer (analyzer/)

# Setup
python -m venv venv
pip install -r requirements.txt

# Run
python server.py         # Start FastAPI server

# Testing (if tests exist)
pytest                   # Run all tests
pytest test_file.py      # Run single test file
pytest -k "test_name"    # Run tests matching name

Docker

docker-compose up -d --build   # Start all services
docker-compose ps              # Check service status
docker-compose down            # Stop all services
docker-compose logs -f web     # Follow logs for specific service

Code Style Guidelines

TypeScript/Svelte (Frontend)

Formatting (Prettier):

• Use tabs for indentation
• Single quotes for strings
• No trailing commas
• Print width: 100 characters

Imports:

• Use $lib/ alias for imports from src/lib/
• Use $app/ for SvelteKit internals
• Group imports: external packages, then internal modules

import { browser } from '$app/environment';
import { auth } from '$lib/stores/auth';
import type { UIBill } from '$lib/models/bill';

Types:

• Define interfaces for API responses and requests
• Use type for unions and simple type aliases
• Export types from dedicated files in $lib/types/ or alongside models

export interface UploadResponse {
  result: boolean;
  message: string;
  data?: UploadData;
}

Naming Conventions:

• PascalCase: Components, interfaces, types
• camelCase: Functions, variables, properties
• Use descriptive names: fetchBills, UIBill, checkHealth

Error Handling:

• Wrap API calls in try/catch
• Throw Error with HTTP status for API failures
• Handle 401 responses with logout redirect

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}

Go (Backend)

Project Structure:

• handler/ - HTTP request handlers
• service/ - Business logic
• repository/ - Data access layer
• model/ - Data structures
• adapter/ - External service integrations
• config/ - Configuration management
• middleware/ - Auth and other middleware

Naming Conventions:

• PascalCase: Exported types, functions, constants
• camelCase: Unexported functions, variables
• Use descriptive names: UpdateBillRequest, parseBillTime

Error Handling:

• Define sentinel errors in repository/errors.go
• Return errors up the call stack
• Use structured JSON responses for HTTP errors

if err == repository.ErrNotFound {
    c.JSON(http.StatusNotFound, Response{Result: false, Message: "not found"})
    return
}

JSON Tags:

• Use snake_case for JSON field names
• Use omitempty for optional fields
• Match frontend API expectations

type UpdateBillRequest struct {
    Category *string `json:"category,omitempty"`
    Amount   *float64 `json:"amount,omitempty"`
}

Response Format:

• All API responses use consistent structure:

type Response struct {
    Result  bool        `json:"result"`
    Message string      `json:"message,omitempty"`
    Data    interface{} `json:"data,omitempty"`
}

Python (Analyzer)

Style:

• Follow PEP 8
• Use type hints for function signatures
• Use Pydantic models for request/response validation

def do_clean(
    input_path: str,
    output_path: str,
    bill_type: str = "auto"
) -> tuple[bool, str, str]:

Error Handling:

• Raise HTTPException for API errors
• Use try/except for file operations
• Return structured responses

if not success:
    raise HTTPException(status_code=400, detail=message)

Testing Guidelines

Frontend Tests:

• Use Vitest with Playwright for browser testing
• Component tests: *.svelte.spec.ts
• Unit tests: *.spec.ts
• Tests require assertions: expect.assertions() or explicit expects

import { describe, it, expect } from 'vitest';
import { render } from 'vitest-browser-svelte';

describe('/+page.svelte', () => {
  it('should render h1', async () => {
    render(Page);
    await expect.element(page.getByRole('heading')).toBeInTheDocument();
  });
});

Important Patterns

API Communication:

• Frontend proxies API calls through SvelteKit to avoid CORS
• Backend uses Gin framework with JSON responses
• Analyzer communicates via HTTP (preferred) or subprocess

Data Flow:

• Frontend (SvelteKit) -> Backend (Go/Gin) -> MongoDB
• Backend -> Analyzer (Python/FastAPI) for bill parsing

Authentication:

• JWT tokens stored in frontend auth store
• Bearer token sent in Authorization header
• 401 responses trigger logout and redirect

File Locations

• API types: web/src/lib/api.ts
• UI models: web/src/lib/models/
• Go handlers: server/handler/
• Go models: server/model/
• Python API: analyzer/server.py