🇦🇺 Australian Tax Optimizer

AI-Powered Tax Recovery & Compliance Platform

Recover $200K-$500K in missed tax benefits per client through forensic Xero analysis

Getting Started • Documentation • API Reference • Architecture

🎯 What is ATO?

The Australian Tax Optimizer is an AI-powered platform that connects to your Xero accounting data (read-only) and performs forensic analysis to identify:

🏗 Architecture

flowchart TB
    subgraph Client["🖥️ Client Layer"]
        UI[Next.js Dashboard]
        Reports[PDF/Excel Reports]
    end

    subgraph API["⚡ API Layer"]
        Auth[OAuth 2.0 Auth]
        Audit[Audit Endpoints]
        Xero[Xero Proxy]
    end

    subgraph Core["🧠 Core Engine"]
        AI[Gemini AI Analyzer]
        RND[R&D Engine]
        DED[Deduction Engine]
        LOSS[Loss Engine]
        DIV7A[Division 7A Engine]
    end

    subgraph Agents["🤖 Agent Fleet"]
        A1[Tax Law Analyst]
        A2[Xero Auditor]
        A3[R&D Specialist]
        A4[Deduction Optimizer]
    end

    subgraph Data["💾 Data Layer"]
        SB[(Supabase)]
        XeroAPI[Xero API]
        Cache[Transaction Cache]
    end

    subgraph Validation["✅ Validation"]
        V1[Tax Calc Validator]
        V2[R&D Eligibility]
        V3[FY Validator]
    end

    UI --> Auth
    UI --> Audit
    Auth --> XeroAPI
    Audit --> AI
    AI --> RND & DED & LOSS & DIV7A
    RND & DED & LOSS & DIV7A --> Agents
    Agents --> SB
    XeroAPI --> Cache --> SB
    AI --> V1 & V2 & V3
    Reports --> SB

    style AI fill:#4285F4,color:#fff
    style SB fill:#3FCF8E,color:#fff
    style XeroAPI fill:#13B5EA,color:#fff

✨ Features

🤖 Multi-Agent Development Framework

This project employs a sophisticated multi-agent development framework that coordinates 4 specialist agents plus an orchestrator for structured, quality-gated development.

Agent Fleet

Framework Agents (Development Process):

• 🎯 Orchestrator - Task decomposition, work distribution, results synthesis, quality control
• 🏗️ Specialist A: Architect - System design, API schemas, database ERDs, architecture decision records (ADRs)
• 💻 Specialist B: Developer - Production code implementation, feature development, refactoring
• 🧪 Specialist C: Tester - Unit/integration/E2E testing, QA, coverage reports (≥80% target)
• 📚 Specialist D: Reviewer - Code review, technical documentation, API docs, user guides

Tax Domain Agents (Business Logic):

• 18 specialized agents for Australian tax analysis (R&D, deductions, losses, Division 7A, etc.)
• See .agent/AGENTS.md for complete agent registry

Development Workflow

graph TD
    A[👨‍💼 Developer] -->|Requirement| B[📊 Senior PM]
    B -->|Create Linear Issue| C[🎯 Orchestrator]
    C -->|Decompose & Assign| D[🏗️ Specialist A: Design]
    C -->|Decompose & Assign| E[💻 Specialist B: Implement]
    C -->|Decompose & Assign| F[🧪 Specialist C: Test]
    C -->|Decompose & Assign| G[📚 Specialist D: Document]
    D -->|Handoff Context| E
    E -->|Handoff Context| F
    F -->|Handoff Context| G
    G -->|Integrate Results| C
    C -->|Review & Report| B
    B -->|Approve & Deploy| A

    style A fill:#FFB74D,color:#000
    style B fill:#4FC3F7,color:#000
    style C fill:#BA68C8,color:#fff
    style D fill:#81C784,color:#000
    style E fill:#64B5F6,color:#000
    style F fill:#FFD54F,color:#000
    style G fill:#A1887F,color:#fff

Quality Gates

Every phase transition requires passing automated quality gates:

See lib/agents/quality-gates.ts for automated enforcement.

Linear Integration

All development work is tracked in Linear with automated updates:

• 📝 Task Creation - Parent issues created from Developer requests
• 🔄 Sub-Task Assignment - Specialists automatically assigned via Linear sub-issues
• 📊 Real-Time Updates - Status transitions (pending → in-progress → review → done)
• 🚫 Blocker Escalation - Automatic escalation with @mentions in comments
• 📈 Progress Tracking - Daily reports showing specialist workload and velocity

Quick Commands:

npm run agent:orchestrator -- --task "Add feature" --priority High
npm run agent:daily-report                         # View daily status
npm run agent:quality-gate -- --gate <name>        # Check quality gate
npm run linear:sync                                # Sync with Linear
npm run linear:report                              # Generate comprehensive report

See MULTI_AGENT_ARCHITECTURE.md for complete framework specification.

🚀 Quick Start

# Clone the repository
git clone https://github.com/CleanExpo/ATO.git
cd ATO

# Install dependencies
npm install

# Copy environment template
cp .env.example .env.local

# Configure your environment variables (see below)

# Supabase (Required)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Xero OAuth (Required)
XERO_CLIENT_ID=your-xero-client-id
XERO_CLIENT_SECRET=your-xero-client-secret
XERO_REDIRECT_URI=https://your-domain.com/api/auth/xero/callback

# Google AI (Required for analysis)
GOOGLE_AI_API_KEY=your-gemini-api-key

# Security (Required for production)
TOKEN_ENCRYPTION_KEY=your-32-byte-hex-key  # Generate: openssl rand -hex 32

# Run migrations via Supabase Dashboard SQL Editor
# Or use the migration script:
npm run db:migrate

# Development
npm run dev

# Production build
npm run build
npm start

# Run tests
npm test

📚 Documentation

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- tests/unit/tax-calculations.test.ts

# Interactive UI
npm run test:ui

Current test coverage: 23 tests passing across tax calculations, financial year validation, and core business logic.

📁 Project Structure

ATO/
├── app/                    # Next.js App Router
│   ├── api/               # 40 API endpoints
│   └── dashboard/         # Dashboard pages
├── lib/                   # Core business logic
│   ├── ai/               # Gemini AI integration
│   ├── analysis/         # Tax engines (R&D, deductions, losses)
│   ├── auth/             # Authentication middleware
│   ├── crypto/           # Token encryption
│   ├── validation/       # Zod schemas
│   └── xero/             # Xero client
├── .agent/               # 16 AI agents
├── .claude/              # Claude configuration & validators
├── scripts/              # Utility scripts
├── supabase/             # Database migrations
└── tests/                # Test suites

🔒 Security

📜 Key Tax Legislation

⚖️ Disclaimer

This software provides tax analysis and recommendations for informational purposes only.
It does not constitute tax advice. All recommendations should be reviewed by a qualified
tax professional before implementation. The software operates in READ-ONLY mode and
will never modify your Xero data or submit ATO filings.

🔗 Links

• Xero Developer Portal
• Australian Taxation Office
• R&D Tax Incentive Guide
• Division 7A Calculator