Skip to content

CLAUDE.md

Latest commit

 

History

History
69 lines (50 loc) · 1.97 KB

CLAUDE.md

File metadata and controls

69 lines (50 loc) · 1.97 KB
Raw

IPTU Agent - Claude Context

Project Overview

IPTU Agent is an AI-powered assistant for Brazilian real estate data (IPTU - Property Tax), built on Google's ADK-Go framework. It demonstrates production-ready AI agent development with hexagonal architecture.

Architecture

Pattern: Hexagonal Architecture (Ports & Adapters)

cmd/agent/          → Application entry point, DI wiring
internal/
  config/           → Centralized configuration (env vars)
  domain/
    entity/         → Domain entities (Property, MarketAnalysis)
    port/           → Interfaces (PropertyRepository)
    service/        → Business logic (PropertyService)
  infrastructure/
    api/            → HTTP client implementation (adapter)
  interfaces/
    tool/           → ADK tool implementations (adapter)
pkg/errors/         → Typed errors with codes

Key Design Decisions

  1. Hexagonal Architecture: Domain logic isolated from infrastructure
  2. Interface-based DI: Easy testing with mock implementations
  3. Centralized Config: Single source of truth, fail-fast validation
  4. Typed Errors: Error codes for proper handling and API responses
  5. Value Objects: Money, Area, Address as value objects

Commands

# Run with mock data
GOOGLE_API_KEY=xxx IPTU_USE_MOCK=true go run ./cmd/agent --console

# Run tests
go test ./... -v -cover

# Build
go build -o iptu-agent ./cmd/agent

Configuration

All config via environment variables. Required: GOOGLE_API_KEY. See .env.example for full list.

ADK Integration

  • Uses llmagent.New() for LLM-powered agent
  • Custom tools via functiontool.New()
  • Launcher for CLI/Web/API modes

Domain Model

  • Property: Main entity with Address, Area, Valuation, Classification
  • MarketAnalysis: Neighborhood statistics
  • Money: Value object for currency formatting

Testing Strategy

  • Unit tests colocated with packages
  • Mock repository for service tests
  • Table-driven tests
  • Coverage target: 80%+