MerchantPilot AI — Autonomous Merchant Operations Platform

MerchantPilot AI is a production-looking full-stack hackathon project for Qwen Cloud Global AI Hackathon — Track 4: Autopilot Agent.

It simulates an autonomous merchant operations workflow for fintech teams: merchant onboarding, document intake, AI-assisted document review, risk assessment, compliance recommendation, human approval, and audit logging.

The project is intentionally built as a realistic scaffold: clean API boundaries, database models, storage adapter pattern, agent service abstraction, seed data, and a polished frontend dashboard.

---

Hackathon Track

Track 4: Autopilot Agent

MerchantPilot AI demonstrates an agentic system where multiple specialized agents collaborate to complete merchant onboarding operations:

1. Intake Agent — validates submitted merchant data and document completeness.
2. Verification Agent — reviews document availability and simulated identity/business checks.
3. Risk Agent — generates merchant risk score, reasons, confidence, and recommendation.
4. Compliance Agent — maps risk findings to compliance actions and review requirements.
5. Memory Agent — stores reusable operational context and previous review signals.

The current implementation requires QWEN_API_KEY for AI reviews and calls Qwen through DashScope's OpenAI-compatible chat completions API.

---

Features

Backend

• Create merchant applications
• Upload merchant documents
• Store files through a storage adapter
• Local filesystem storage during development
• Alibaba OSS placeholder storage service for future deployment
• Run autonomous AI agent review
• Generate agent timeline events
• Persist risk assessments
• Persist compliance reviews
• Persist memory records
• Human approval actions:
  • Approve merchant
  • Reject merchant
  • Request more information
• Audit logging for major system events
• Dashboard metrics API
• Seed data with realistic demo merchants
• Alembic-ready PostgreSQL setup

Frontend

• Modern fintech compliance dashboard
• Merchant application form
• Merchant detail/review page with tabs:
  • Overview
  • Documents
  • Agent Analysis
  • Risk
  • Compliance
  • History
  • Audit Trail
• Human review center
• Agent investigation timeline
• Polished neutral UI with dark/light-friendly styling
• TanStack Query-powered API state

---

Architecture

merchantpilot-ai/
├── backend/
│   ├── alembic/
│   ├── app/
│   │   ├── api/
│   │   │   └── routes/
│   │   ├── core/
│   │   ├── db/
│   │   ├── models/
│   │   ├── schemas/
│   │   └── services/
│   │       ├── agents/
│   │       ├── cac/
│   │       ├── documents/
│   │       └── storage/
│   ├── requirements.txt
│   ├── seed.py
│   └── alembic.ini
├── frontend/
│   ├── app/
│   ├── components/
│   ├── lib/
│   ├── package.json
│   └── tailwind.config.ts
├── docker-compose.yml
├── .env.example
└── README.md

---

Tech Stack

Frontend

• Next.js 15
• TypeScript
• Tailwind CSS
• shadcn/ui-style components
• TanStack Query

Backend

• FastAPI
• Python
• Pydantic
• SQLAlchemy
• Alembic
• PostgreSQL

Storage

• Local filesystem storage for development
• Storage adapter abstraction
• Alibaba OSS placeholder service for future implementation

AI

• Qwen agent service abstraction
• Qwen OpenAI-compatible chat completion integration when QWEN_API_KEY is configured
• Mock CAC verification provider for hackathon/demo mode
• Agent timeline persistence

---

Local Setup

1. Clone and enter project

git clone <your-repo-url>
cd merchantpilot-ai
cp .env.example .env

2. Start PostgreSQL

docker compose up -d

PostgreSQL will run on port 5432.

3. Backend setup

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run migrations:

alembic upgrade head

Seed demo data:

python seed.py

Start API server:

uvicorn app.main:app --reload --port 8000

API docs:

http://localhost:8000/docs

4. Frontend setup

Open a second terminal:

cd frontend
npm install
npm run dev

Frontend:

http://localhost:3000

---

Environment Variables

Use a single .env file in the project root. See .env.example.

DATABASE_URL=postgresql+psycopg2://merchantpilot:merchantpilot@localhost:5432/merchantpilot
APP_ENV=development
API_CORS_ORIGINS=http://localhost:3000
STORAGE_TYPE=local
LOCAL_UPLOAD_ROOT=uploads
QWEN_API_KEY=
QWEN_MODEL=qwen-plus
QWEN_BASE_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1
QWEN_TIMEOUT_SECONDS=30
QWEN_MAX_RETRIES=2
CAC_PROVIDER=mock
CAC_API_KEY=
CAC_API_BASE_URL=
NEXT_PUBLIC_API_URL=http://localhost:8000/api

---

API Routes

Base URL:

http://localhost:8000/api

Method	Route	Description
POST	/merchants	Create merchant application
POST	/merchants/{merchant_id}/documents	Upload merchant document
GET	/merchants	Get all merchants
GET	/merchants/{merchant_id}	Get merchant details
POST	/merchants/{merchant_id}/run-review	Run AI agent review
GET	/merchants/{merchant_id}/agent-timeline	Get agent timeline
POST	/merchants/{merchant_id}/approve	Approve merchant
POST	/merchants/{merchant_id}/reject	Reject merchant
POST	/merchants/{merchant_id}/request-info	Request more information
GET	/audit-logs	View audit logs
GET	/dashboard/metrics	View dashboard metrics

---

Database Setup

Create database using Docker Compose:

docker compose up -d

Run Alembic migrations:

cd backend
alembic upgrade head

Seed realistic fake merchants:

python seed.py

Seeded statuses include:

• Pending
• Approved
• Flagged
• Needs information
• Rejected

---

Storage Explanation

Local files are stored using this structure:

uploads/merchants/{merchant_id}/{document_type}/{filename}

Storage logic is not hardcoded inside routes. Routes call the storage abstraction:

app/services/storage/base.py
app/services/storage/local.py
app/services/storage/oss.py
app/services/storage/factory.py

Set storage backend using:

STORAGE_TYPE=local

or:

STORAGE_TYPE=oss

oss currently uses a placeholder AlibabaOSSStorageService with TODO comments showing where Alibaba OSS SDK logic should be added.

---

CAC Verification Mode

MerchantPilot AI includes a demo-safe CAC verification mode for hackathon usage.

• The app does not call paid CAC APIs in demo mode.
• CAC_PROVIDER=mock enables the local mock CAC verification adapter.
• Uploaded CAC PDFs are parsed locally with pypdf.
• The verifier extracts readable PDF text, RC/BN numbers, and labeled business names when available.
• The submitted business name is compared against extracted text using rapidfuzz.
• The system generates a confidence score, risk flags, recommendation, audit log entry, memory record, and Verification Agent timeline events.
• Official CAC registry verification is not performed in demo mode; it is abstracted behind CACVerificationService for future provider integration.

CAC files should be uploaded with:

document_type=cac

For backward compatibility, existing cac_document uploads are also accepted.

---

Alibaba OSS Deployment Note

Alibaba OSS is not implemented yet by design. The project includes a clean placeholder service:

backend/app/services/storage/oss.py

To implement OSS later:

1. Install Alibaba Cloud OSS SDK.
2. Add OSS environment variables:
   • ALIBABA_OSS_ENDPOINT
   • ALIBABA_OSS_BUCKET
   • ALIBABA_ACCESS_KEY_ID
   • ALIBABA_ACCESS_KEY_SECRET
3. Implement save() in AlibabaOSSStorageService.
4. Keep API routes unchanged because they depend only on StorageService.

---

Qwen Cloud Integration Note

The Qwen integration is intentionally abstracted behind:

backend/app/services/agents/qwen_service.py

Current behavior:

• If QWEN_API_KEY is missing, the backend returns a clear 503 error and the frontend displays the configuration problem.
• If QWEN_API_KEY is present, the backend calls the configured Qwen OpenAI-compatible chat completions endpoint.
• Qwen output is requested as strict JSON and validated with Pydantic before persistence.
• The service includes timeout and retry handling through QWEN_TIMEOUT_SECONDS and QWEN_MAX_RETRIES.

The default QWEN_BASE_URL is:

https://dashscope-intl.aliyuncs.com/compatible-mode/v1

---

Demo Workflow

1. Open dashboard.
2. Review metrics and recent merchant applications.
3. Create a new merchant application.
4. Upload CAC and means of identification documents.
5. Open merchant detail page.
6. Click Run AI Review.
7. Watch the agent timeline populate:
   • Intake Agent started
   • CAC parsed
   • Verification completed
   • Risk score generated
   • Compliance recommendation ready
   • Waiting for human review
8. Go to Human Review Center.
9. Review AI recommendation, risk score, confidence, and supporting reasons.
10. Approve, reject, or request more information.
11. Check audit logs.

---

Hackathon Positioning

MerchantPilot AI is strong for a demo because it solves a real fintech operations problem:

• Merchant onboarding is repetitive.
• Compliance review is document-heavy.
• Risk teams need explainable recommendations.
• Human reviewers need audit trails.
• Regulators require traceability.

The project does not pretend AI fully replaces compliance teams. The stronger story is AI autopilot with human approval and auditability.

---

Commands Summary

# Start DB
docker compose up -d

# Backend
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
python seed.py
uvicorn app.main:app --reload --port 8000

# Frontend
cd frontend
npm install
npm run dev

---

License

MIT