Oil & Gas Tax Planner

A production-quality web application that helps users estimate oil & gas tax write-off deductions, specifically focusing on Intangible Drilling Costs (IDCs) and their impact on federal and state tax savings.

⚠️ Important Disclaimer

This tool is for educational and illustrative purposes only and does not constitute tax, legal, or investment advice. Please consult a qualified CPA or tax professional before making decisions.

All calculations are estimates, not guarantees. Actual tax outcomes depend on many factors including at-risk rules, passive activity loss limitations, AMT, and your complete tax situation.

Features

• Multi-Step Questionnaire: Adaptive, agentic questionnaire that collects user tax profile, investment details, and tax rates
• Deterministic Tax Calculations: Core calculation engine (no AI) for:
  • IDC deduction calculations
  • Federal and state tax savings
  • Taxable income before/after
  • Effective net cost of investment
  • 7-year TDC depreciation schedule
• AI-Powered Explanations: Claude integration for:
  • Plain-English narrative explanation of results
  • Summary for accountant/CPA review
• Modern UI: Clean, responsive interface built with Next.js, Tailwind CSS, and shadcn/ui

Tech Stack

• Framework: Next.js 16 (App Router) with TypeScript
• UI: React, Tailwind CSS, shadcn/ui components
• Forms: react-hook-form + Zod validation
• AI: Anthropic Claude API (for explanations only)
• Testing: Vitest + React Testing Library
• Charts: Recharts (for future enhancements)

Architecture

Core Calculation Logic (lib/calculations/taxPlanner.ts)

All tax calculations are deterministic and implemented in pure TypeScript functions:

• calculateOilGasTaxPlan(): Main calculation function
• IDC amount = investment × IDC percentage
• Tax savings = IDC amount × tax rates
• TDC depreciation = 7-year straight-line (simplified)

No AI is used for calculations - only for generating explanations.

AI Integration (lib/ai/anthropicClient.ts)

Claude API is used only for:

• Generating user-friendly narrative explanations
• Creating accountant summaries

The AI receives pre-calculated results and explains them - it does not perform any math.

Tax Bracket Approximation (lib/config/taxBrackets.ts)

Simplified 2024 federal tax bracket lookup based on income and filing status. This is for demonstration purposes only.

Setup Instructions

1. Install Dependencies

npm install
# or
pnpm install

2. Environment Variables

Create a .env.local file:

# Anthropic Claude API
ANTHROPIC_API_KEY=your-api-key-here
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

Get your API key from: https://console.anthropic.com/

3. Run Development Server

npm run dev

Open http://localhost:3000

4. Run Tests

npm test

For UI testing:

npm run test:ui

Project Structure

og-tax-planner/
├── app/
│   ├── page.tsx              # Landing page
│   ├── plan/
│   │   └── page.tsx          # Multi-step questionnaire
│   ├── results/
│   │   └── page.tsx          # Results dashboard
│   └── api/
│       └── explain/
│           └── route.ts      # AI explanation endpoint
├── components/
│   ├── forms/                # Questionnaire step components
│   ├── layout/               # Layout components
│   └── ui/                   # shadcn/ui components
├── lib/
│   ├── calculations/
│   │   ├── taxPlanner.ts     # Core tax calculation logic
│   │   └── taxPlanner.test.ts
│   ├── ai/
│   │   └── anthropicClient.ts # Claude API integration
│   ├── config/
│   │   └── taxBrackets.ts    # Tax bracket lookup
│   └── validation/
│       └── schemas.ts        # Zod validation schemas
└── types/
    └── planner.ts            # TypeScript type definitions

Tax Calculation Assumptions

IDC (Intangible Drilling Costs)

• Typically 70-85% of investment (user-configurable)
• Deductible in the year incurred (Year 1)
• Provides immediate tax benefit

TDC (Tangible Drilling Costs)

• Remaining percentage of investment (100% - IDC%)
• Depreciated over 7 years using straight-line method (simplified)
• Provides ongoing tax benefits

Tax Rates

• Federal rate: User-provided or approximated from income/filing status
• State rate: User-provided or approximated from state lookup
• Rates applied to IDC deduction for Year 1 savings
• Only federal rate applied to TDC depreciation (simplified)

Limitations & Simplifications

This tool does NOT account for:

• At-risk rules
• Passive activity loss limitations
• Alternative Minimum Tax (AMT)
• State-specific deduction rules
• Timing differences
• Phase-outs and other complexities

This is illustrative only. Real tax calculations require professional analysis.

Development

Code Quality

• TypeScript strict mode: All code is fully typed
• ESLint + Prettier: Enforced code style
• Unit tests: Core calculation logic is tested
• Component tests: Critical UI flows are tested

Adding Features

1. New calculation logic: Add to lib/calculations/taxPlanner.ts
2. New form step: Create component in components/forms/
3. New API endpoint: Add route handler in app/api/
4. New UI component: Use shadcn/ui or create in components/

Testing

# Run all tests
npm test

# Run with UI
npm run test:ui

# Run with coverage
npm run test:coverage

Building for Production

npm run build
npm start

License

[Your License Here]

Support

For questions about:

• Tax calculations: Consult a qualified CPA or tax professional
• Technical issues: Check the code comments and test files
• IRS rules: See IRS Publication 535 (Business Expenses) and consult a tax professional

---

Remember: This tool provides educational estimates only. Always consult a qualified tax professional before making tax planning decisions.