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 (Frontend Proxy & UI)
• server/ - Go 1.21 + Gin + MongoDB (Main API & Data Storage)
• analyzer/ - Python 3.12 + FastAPI (Data Cleaning & Analysis Service)

Build/Lint/Test Commands

Frontend (web/)

Working Directory: /Users/clz/Projects/BillAI/web

npm run dev                           # Start dev server
npm run build                         # Production build
npm run check                         # TypeScript check (svelte-check)
npm run lint                          # Prettier + ESLint
npm run format                        # Format code (Prettier)
npm run test:unit                     # Run all unit tests (Vitest)
npx vitest run src/routes/+page.spec.ts  # Run single test file
npx vitest run -t "test name"         # Run test by name pattern

Backend (server/)

Working Directory: /Users/clz/Projects/BillAI/server

go run .                              # Start server
go build -o server .                  # Build binary
go mod tidy                           # Clean dependencies
go test ./...                         # Run all tests
go test ./handler/...                 # Run package tests
go test -run TestName                 # Run single test function
go test -v ./handler/...              # Run tests with verbose output

Analyzer (analyzer/)

Working Directory: /Users/clz/Projects/BillAI/analyzer

python server.py                      # Start FastAPI server directly
uvicorn server:app --reload           # Start with hot reload
pytest                                # Run all tests
pytest test_file.py                   # Run single test file
pytest -k "test_name"                 # Run test by name pattern
pip install -r requirements.txt       # Install dependencies

Docker

Working Directory: /Users/clz/Projects/BillAI

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

Code Style

General

• Comments: Existing comments often use Chinese for business logic explanations. Maintain this style where appropriate, but English is also acceptable for technical explanations.
• Conventions: Follow existing patterns strictly. Do not introduce new frameworks or libraries without checking package.json/go.mod/requirements.txt.

TypeScript/Svelte (web/)

• Formatting: Prettier (Tabs, single quotes, no trailing commas, printWidth 100).
• Naming: PascalCase for types/components/interfaces, camelCase for variables/functions.
• Imports: Use $lib alias for internal imports.

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

• Types: Define interfaces for data models. Use export interface.
• Error Handling: Check response.ok. Throw Error with status for UI to catch.

Go Backend (server/)

• Structure: handler (HTTP) → service (Logic) → repository (DB) → model (Structs).
• Tags: Use json (snake_case) and form tags. Use omitempty for optional fields.

  type UpdateBillRequest struct {
      Category *string `json:"category,omitempty" form:"category"`
  }
  

• Error Handling: Return 500 for DB errors, 400 for bad requests. Wrap errors with context.

  if err != nil {
      c.JSON(http.StatusInternalServerError, Response{Result: false, Message: err.Error()})
      return
  }
  

Python Analyzer (analyzer/)

• Style: PEP 8. Use snake_case for variables/functions.
• Type Hints: Mandatory for function arguments and return types.
• Models: Use pydantic.BaseModel for API schemas.

  class CleanRequest(BaseModel):
      input_path: str
      bill_type: Optional[str] = "auto"
  

• Docstrings: Use triple quotes. Chinese descriptions are common for API docs.

Key Patterns

• API Flow:

  • Frontend talks to server (Go) via /api proxy.
  • server handles auth, DB operations, and delegates complex file processing to analyzer (Python).
  • analyzer cleanses CSV/Excel files and returns structured JSON/CSV to server.

• Authentication:

  • JWT based. Token stored in frontend.
  • Header: Authorization: Bearer <token>.
  • Backend middleware checks token. 401 triggers logout/redirect.

• File Processing:

  • Flow: Upload (ZIP/XLSX) -> Extract/Convert (to UTF-8 CSV) -> Clean (normalize columns) -> Import to DB.
  • analyzer uses openpyxl for Excel and regex for cleaning text.

Important Files

• web/src/lib/api.ts - Centralized API client methods.
• web/src/lib/models/*.ts - Frontend data models (should match backend JSON).
• server/handler/*.go - HTTP endpoint definitions.
• server/repository/mongo.go - MongoDB connection and queries.
• analyzer/server.py - FastAPI entry point and routing.
• analyzer/cleaners/*.py - Specific logic for Alipay/Wechat/JD bills.