Recon Agent — Multi-Tenant SaaS

AI-powered financial reconciliation as a multi-tenant SaaS.

Architecture

• Frontend: Next.js 16 + Clerk auth (App Router)
• Backend API: FastAPI (Python)
• Core Engine: Pure Python reconciliation logic (core/)
• Database: Supabase PostgreSQL with RLS
• Storage: Supabase Storage (CSV/XLSX files)

The architecture flows strictly as: Web → FastAPI API → Core Engine → Database

[!NOTE] The Command Line Interface (recon) is a fully featured CLI that consumes the FastAPI REST API using Personal Access Tokens (PATs).

Quick Start

1. Backend (FastAPI)

cd /home/abhishek/PROJECTS/recon-agent
.venv/bin/python -m uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

Health check: curl http://localhost:8000/health

2. Frontend (Next.js)

cd /home/abhishek/PROJECTS/recon-agent/web
npm run dev

Command Line Interface (CLI)

Recon Agent includes a powerful CLI that acts as a first-class client to the FastAPI backend. It allows you to automate reconciliations, view history, export reports, and generate AI explanations straight from the terminal.

Installation

Install locally via pip or uv:

pip install -e .
# or
uv pip install -e .

This makes the recon command globally available.

recon --help

Usage

1. Login: Generate a Personal Access Token in the Web UI, then run:

   recon login
   

2. Reconcile:

   recon reconcile source.csv target.csv
   

3. History:

   recon history
   

4. Machine Readable output:

   recon history --json
   

Documentation

• Docs Directory
• Phase 1: Feature 1–7 Audit
• Phase 2: Platform Foundations
• Phase 3: API Authentication
• Phase 4: CLI Documentation
• Phase 5: Tiers and Roles

Development

uv sync

Create .env (root) and web/.env.local with these values.

Root .env

SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_SERVICE_KEY=<service_role JWT>      # NOT the publishable key!
CLERK_SECRET_KEY=sk_test_...
CLERK_ISSUER=https://<your-app>.clerk.accounts.dev
ENCRYPTION_KEY=<base64 32 bytes>

web/.env.local

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...

Database Setup

Run the SQL in api/migrations/001_initial_schema.sql in the Supabase SQL editor.

This creates the tables and enables RLS policies.

How multi-tenancy works

1. User signs in with Clerk (organizations enabled)
2. Clerk JWT is sent on every API request
3. Backend extracts clerk_org_id from JWT
4. Each DB query is scoped to that org — RLS enforces isolation as a backstop

See api/migrations/001_initial_schema.sql to 005_usage_quotas.sql for the full schema.