ATO Tax Optimizer Banner # ๐Ÿ‡ฆ๐Ÿ‡บ Australian Tax Optimizer ### AI-Powered Tax Recovery & Compliance Platform [![Next.js](https://img.shields.io/badge/Next.js-16.1-black?style=for-the-badge&logo=next.js)](https://nextjs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Supabase](https://img.shields.io/badge/Supabase-PostgreSQL-3FCF8E?style=for-the-badge&logo=supabase&logoColor=white)](https://supabase.com/) [![Xero](https://img.shields.io/badge/Xero-OAuth_2.0-13B5EA?style=for-the-badge&logo=xero&logoColor=white)](https://developer.xero.com/) [![Gemini AI](https://img.shields.io/badge/Gemini-AI_Analysis-4285F4?style=for-the-badge&logo=google&logoColor=white)](https://ai.google.dev/) [![License](https://img.shields.io/badge/License-Proprietary-red?style=flat-square)]() [![Tests](https://img.shields.io/badge/Tests-23_Passing-brightgreen?style=flat-square)]() [![Coverage](https://img.shields.io/badge/Coverage-80%25-yellow?style=flat-square)]() **Recover $200K-$500K in missed tax benefits per client through forensic Xero analysis** [Getting Started](#-quick-start) โ€ข [Documentation](#-documentation) โ€ข [API Reference](API_DOCUMENTATION.md) โ€ข [Architecture](#-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: | Recovery Area | Potential Savings | Legislation | |--------------|-------------------|-------------| | ๐Ÿ”ฌ **R&D Tax Incentive** | Up to 43.5% offset | Division 355 ITAA 1997 | | ๐Ÿ“Š **Unclaimed Deductions** | Variable | Section 8-1 ITAA 1997 | | ๐Ÿ’ฐ **Carry-Forward Losses** | Tax offset on profits | Subdivision 36-A | | ๐Ÿฆ **Division 7A Compliance** | Avoid deemed dividends | Division 7A ITAA 1936 | | ๐ŸŽ **FBT Optimisation** | Reduce FBT liability | FBTAA 1986 | --- ## ๐Ÿ— Architecture ```mermaid 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
### ๐Ÿ” Forensic Analysis - AI-powered transaction scanning - Pattern recognition for R&D activities - Misclassification detection - Multi-year analysis (FY2020-25) ### ๐Ÿ›ก๏ธ Enterprise Security - Read-only Xero access - AES-256-GCM token encryption - Multi-tenant isolation - Row-level security (RLS)
### ๐Ÿค– 16 Specialised Agents - Tax Law Analyst - R&D Tax Specialist - Deduction Optimizer - Loss Recovery Agent - Division 7A Compliance - And 11 more... ### ๐Ÿ“Š Validation System - 10 specialised validators - 90-95% confidence scores - Automatic fix instructions - Compliance verification
--- ## ๐Ÿค– 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](.agent/AGENTS.md) for complete agent registry ### Development Workflow ```mermaid 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: | Gate | Criteria | Blocks Phase | |------|----------|--------------| | โœ… Design Complete | ADR created, diagrams complete, risks documented | Implementation | | โœ… Implementation Complete | Code compiles, linting passes, basic functionality works | Testing | | โœ… Testing Complete | โ‰ฅ80% coverage, all tests pass, no critical bugs | Documentation | | โœ… Documentation Complete | API docs, changelog updated, examples provided | Integration | | โœ… Integration Complete | All outputs merged, system functional, no conflicts | Final Approval | | โœ… Final Approval | PM + Developer sign-off, ready for deployment | Deployment | 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**: ```bash npm run agent:orchestrator -- --task "Add feature" --priority High npm run agent:daily-report # View daily status npm run agent:quality-gate -- --gate # Check quality gate npm run linear:sync # Sync with Linear npm run linear:report # Generate comprehensive report ``` See [MULTI_AGENT_ARCHITECTURE.md](MULTI_AGENT_ARCHITECTURE.md) for complete framework specification. --- ## ๐Ÿš€ Quick Start
๐Ÿ“‹ Prerequisites - Node.js 20.x or higher - npm 10.x or higher - Xero Developer Account - Supabase Project - Google AI API Key (for Gemini)
โš™๏ธ Installation ```bash # 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) ```
๐Ÿ”‘ Environment Variables ```env # 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 ```
๐Ÿ—„๏ธ Database Setup ```bash # Run migrations via Supabase Dashboard SQL Editor # Or use the migration script: npm run db:migrate ``` Migration files are located in `supabase/migrations/`.
โ–ถ๏ธ Running the App ```bash # Development npm run dev # Production build npm run build npm start # Run tests npm test ```
--- ## ๐Ÿ“š Documentation | Document | Description | |----------|-------------| | [CLAUDE.md](CLAUDE.md) | AI development guidelines (RTCC pattern) | | [MULTI_AGENT_ARCHITECTURE.md](MULTI_AGENT_ARCHITECTURE.md) | Multi-agent framework specification | | [spec.md](spec.md) | Technical specification | | [API_DOCUMENTATION.md](API_DOCUMENTATION.md) | Complete API reference | | [FORENSIC_AUDIT_GUIDE.md](FORENSIC_AUDIT_GUIDE.md) | User guide for audits | | [AGENTS_README.md](AGENTS_README.md) | Agent system documentation | | [DATABASE_MIGRATIONS.md](DATABASE_MIGRATIONS.md) | Migration instructions | --- ## ๐Ÿงช Testing ```bash # 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 | Feature | Implementation | |---------|---------------| | **Authentication** | Supabase Auth with JWT | | **Authorisation** | Per-tenant access control | | **Token Storage** | AES-256-GCM encryption | | **API Security** | Rate limiting, input validation | | **Xero Access** | Read-only scopes only | | **Data Protection** | Row-level security (RLS) | --- ## ๐Ÿ“œ Key Tax Legislation | Legislation | Purpose | Key Rates (FY2024-25) | |-------------|---------|----------------------| | Division 355 ITAA 1997 | R&D Tax Incentive | 43.5% offset | | Division 7A ITAA 1936 | Private Company Loans | 8.77% benchmark | | Section 8-1 ITAA 1997 | General Deductions | Business purpose test | | Subdivision 36-A ITAA 1997 | Tax Losses | COT/SBT compliance | | Subdivision 328-D ITAA 1997 | Instant Asset Write-Off | $20,000 threshold | | FBTAA 1986 | Fringe Benefits Tax | 47% rate | --- ## โš–๏ธ 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](https://developer.xero.com/) - [Australian Taxation Office](https://www.ato.gov.au/) - [R&D Tax Incentive Guide](https://www.ato.gov.au/businesses-and-organisations/income-deductions-and-concessions/research-and-development-tax-incentive) - [Division 7A Calculator](https://www.ato.gov.au/calculators-and-tools/division-7a-calculator) ---
**Built with โค๏ธ for Australian Businesses** [![Vercel](https://img.shields.io/badge/Deployed_on-Vercel-black?style=flat-square&logo=vercel)](https://vercel.com)