Aegis Accountant 🛡️

Your AI Accountant That Never Sleeps

An autonomous, continuously improving AI accountant that audits, reconciles, categorizes, forecasts, and manages financial records for SMBs — without human bookkeeping overhead.

🚀 Features

• Automated Auditing: Detects duplicates, unused subscriptions, and categorization errors automatically
• Find Hidden Savings: Identifies wasted spend on tools you don't use - save $100s per month
• Weekly Reports: Get clear, AI-generated audit reports with actionable insights
• Multi-Platform Support: Connect QuickBooks, Xero, or Sage Accounting
• AI-Powered Categorization: Smart transaction categorization that learns your business
• Anomaly Detection: Get notified of unusual spending patterns and potential issues

🛠️ Tech Stack

Frontend

• Next.js 14 (App Router)
• TypeScript
• TailwindCSS
• Supabase (Authentication & Database)

Backend

• FastAPI (Python)
• OpenAI API (GPT-4 for AI analysis)
• Supabase (PostgreSQL database)
• SendGrid (Email delivery)

Integrations

• QuickBooks Online API
• Xero API
• Sage Accounting API
• Plaid (optional, for bank connections)

📋 Prerequisites

• Node.js 18+ and npm/yarn
• Python 3.9+
• Supabase account (free tier works)
• OpenAI API key
• SendGrid account (free tier works)
• (Optional) QuickBooks, Xero, or Sage developer accounts

🏗️ Project Structure

AEGIS/
├── app/                    # Next.js app directory
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Landing page
├── components/            # React components
│   └── ConnectAccountingButtons.tsx
├── lib/                   # Utility libraries
│   └── supabase.ts       # Supabase client
├── backend/              # FastAPI backend
│   ├── main.py          # FastAPI app entry point
│   ├── config.py        # Configuration management
│   ├── routers/         # API route handlers
│   │   ├── auth.py      # Authentication routes
│   │   ├── quickbooks.py # QuickBooks integration
│   │   ├── xero.py      # Xero integration
│   │   ├── sage.py      # Sage integration
│   │   ├── audit.py     # Audit logic
│   │   └── reports.py   # Report generation
│   └── services/        # Business logic services
│       ├── ai_service.py     # AI analysis
│       ├── email_service.py  # Email delivery
│       └── database.py       # Database operations
├── supabase/
│   └── schema.sql       # Database schema
└── README.md

🚀 Getting Started

1. Clone the Repository

git clone <your-repo-url>
cd AEGIS

2. Set Up Environment Variables

Frontend (.env.local)

cp .env.local.example .env.local

Then edit .env.local with your credentials:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

QUICKBOOKS_CLIENT_ID=your_quickbooks_client_id
QUICKBOOKS_CLIENT_SECRET=your_quickbooks_client_secret
QUICKBOOKS_REDIRECT_URI=http://localhost:3000/api/auth/quickbooks/callback

XERO_CLIENT_ID=your_xero_client_id
XERO_CLIENT_SECRET=your_xero_client_secret
XERO_REDIRECT_URI=http://localhost:3000/api/auth/xero/callback

SAGE_CLIENT_ID=your_sage_client_id
SAGE_CLIENT_SECRET=your_sage_client_secret
SAGE_REDIRECT_URI=http://localhost:3000/api/auth/sage/callback

GEMINI_API_KEY=your_gemini_api_key
SENDGRID_API_KEY=your_sendgrid_api_key
NEXT_PUBLIC_API_URL=http://localhost:8000

Backend (.env)

cd backend
cp .env.example .env

Then edit backend/.env with your credentials.

3. Set Up Supabase Database

1. Create a new project on Supabase
2. Go to the SQL Editor in your Supabase dashboard
3. Run the SQL script from supabase/schema.sql
4. Copy your project URL and anon key to your .env.local file

4. Install Dependencies

Frontend

npm install

Backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

5. Run the Development Servers

Terminal 1 - Frontend (Next.js)

npm run dev

The frontend will be available at http://localhost:3000

Terminal 2 - Backend (FastAPI)

cd backend
source venv/bin/activate  # On Windows: venv\Scripts\activate
uvicorn main:app --reload --port 8000

The backend API will be available at http://localhost:8000

You can view the API documentation at http://localhost:8000/docs

🔧 API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/signup - User registration
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user

QuickBooks

• GET /api/quickbooks/connect - Initialize OAuth flow
• GET /api/quickbooks/callback - OAuth callback
• GET /api/quickbooks/transactions - Fetch transactions
• GET /api/quickbooks/vendors - Fetch vendors
• POST /api/quickbooks/disconnect - Disconnect integration

Xero

• GET /api/xero/connect - Initialize OAuth flow
• GET /api/xero/callback - OAuth callback
• GET /api/xero/transactions - Fetch transactions
• GET /api/xero/contacts - Fetch contacts

Sage

• GET /api/sage/connect - Initialize OAuth flow
• GET /api/sage/callback - OAuth callback
• GET /api/sage/transactions - Fetch transactions

Audit

• POST /api/audit/run - Run a complete audit
• GET /api/audit/status/{audit_id} - Get audit status
• POST /api/audit/detect-duplicates - Detect duplicate transactions
• POST /api/audit/detect-unused-subscriptions - Find unused subscriptions

Reports

• GET /api/reports/list - List all reports
• GET /api/reports/{report_id} - Get specific report
• POST /api/reports/generate - Generate new report
• POST /api/reports/{report_id}/email - Email report to user

🧠 AI Analysis

The AI service uses OpenAI's GPT-4 to analyze transactions and provide insights:

1. Duplicate Detection: Identifies duplicate charges from the same vendor
2. Subscription Analysis: Finds unused or underutilized SaaS subscriptions
3. Categorization: Suggests correct accounting categories for transactions
4. Anomaly Detection: Flags unusual spending patterns
5. Report Generation: Creates human-readable summaries with actionable insights

🔐 Security

• All API credentials are stored securely in environment variables
• Database uses Row Level Security (RLS) policies
• OAuth 2.0 for third-party integrations
• Encrypted data transmission (HTTPS in production)
• No storage of sensitive financial data beyond what's necessary

🚢 Deployment

Frontend (Vercel)

npm run build
# Deploy to Vercel
vercel --prod

Backend (Railway, Render, or DigitalOcean)

1. Set up Python 3.9+ environment
2. Install dependencies: pip install -r requirements.txt
3. Set environment variables
4. Run: uvicorn main:app --host 0.0.0.0 --port $PORT

📊 Development Roadmap

✅ MVP (Weeks 1-2)

• Connect to QuickBooks/Xero/Sage APIs
• Run expense categorization
• Detect duplicates & subscriptions
• Send weekly reports
• Basic dashboard

🔄 Phase 2 (Months 2-3)

• Automated reconciliation
• Match invoices → transactions
• AI categorization with reasoning notes
• Daily automated audits

🎯 Phase 3 (Months 4-6)

• Cash flow forecasting
• Anomaly detection alerts
• Missing invoice detection
• AI CFO insights

🚀 Phase 4 (Long-term)

• AR/AP automation
• Tax prep assistant
• Payroll integration
• Full AI Accountant Suite

💰 Revenue Model

Tier	Description	Price
Starter	<1,000 transactions/mo	$49/mo
Growth	1,000-5,000 transactions/mo	$149/mo
Pro	5,000-20,000 transactions/mo	$499/mo

Add-on: AI CFO Insights pack (forecasting, anomaly detection) at +$99/mo

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

Copyright © 2025 Aegis Accountant. All rights reserved.

📧 Support

For questions or support, please contact: support@aegisaccountant.com

---

Built with ❤️ to make accounting easy for SMBs