billai/AGENTS.md

AGENTS.md - AI Coding Agent Guidelines

Guidelines for AI coding agents working on BillAI - a microservices bill analysis system.

Architecture

• web/ - SvelteKit 5 + TailwindCSS 4 + TypeScript
• server/ - Go 1.21 + Gin + MongoDB
• analyzer/ - Python 3.12 + FastAPI

Build/Lint/Test Commands

Frontend (web/)

npm run dev                           # Start dev server
npm run build                         # Production build
npm run check                         # TypeScript check
npm run lint                          # Prettier + ESLint
npm run format                        # Format code
npm run test                          # Run all tests
npx vitest run src/routes/+page.spec.ts  # Single test file
npx vitest run -t "test name"         # Test by name

Backend (server/)

go run .                              # Start server
go build .                            # Build binary
go mod tidy                           # Clean dependencies
go test ./...                         # All tests
go test ./handler/...                 # Package tests
go test -run TestName                 # Single test

Analyzer (analyzer/)

python server.py                      # Start FastAPI server
pytest                                # All tests
pytest test_file.py                   # Single file
pytest -k "test_name"                 # Test by pattern

Docker

docker-compose up -d --build          # Start/rebuild all
docker-compose logs -f server         # Follow service logs

Code Style

TypeScript/Svelte

Prettier config: Tabs, single quotes, no trailing commas, width 100

Imports:

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

Types:

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

Naming: PascalCase (types, components), camelCase (functions, variables)

Error handling:

if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
// Handle 401 -> logout redirect

Go Backend

Structure: handler/ → service/ → repository/ → MongoDB

JSON tags: snake_case, omitempty for optional fields

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

Response format:

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

Error handling:

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

Python Analyzer

Style: PEP 8, type hints, Pydantic models

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

Error handling:

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

Key Patterns

API Flow: Frontend (SvelteKit proxy) → Go API → MongoDB + Python analyzer

Auth: JWT tokens, Bearer header, 401 → logout redirect

File Processing: ZIP → extract → convert (GBK→UTF-8, xlsx→csv) → clean → import

Testing: Vitest + Playwright for frontend, Go test for backend

Important Files

• web/src/lib/api.ts - API client
• web/src/lib/models/ - UI data models
• server/handler/ - HTTP handlers
• server/service/ - Business logic
• server/model/ - Go data structures
• analyzer/cleaners/ - Bill processing
• mock_data/*.zip - Test data (password: 123456)