Web-Backend Integration - Complete ✅¶

Note: This page is a point-in-time status snapshot and may be out of date relative to the current source. PRs welcome.

What Was Built¶

Backend (FastAPI + TortoiseORM + PostgreSQL)¶

A complete REST API backend with:

✅ Database Layer - TortoiseORM models for Users, Markets, Drafts, Curation - Aerich migration system - Proper relationships and indexes - Aligned with market standard specification

✅ Authentication System - JWT-based authentication - Support for wallet-only OR email+password auth - Role-based access (curator, admin) - Secure password hashing with bcrypt - Token refresh and session management

✅ REST API Endpoints - /api/v1/auth/* - Registration, login, profile management - /api/v1/markets/* - Market discovery, filtering, details - /api/v1/drafts/* - Draft creation and management - /api/v1/curator/* - Curator workflow and approval

✅ Mobile-Ready Design - Stateless JWT (no cookies) - CORS enabled - RESTful JSON responses - Proper HTTP status codes

Frontend (Vue 3 + Pinia + Axios)¶

Integrated web application with:

✅ API Client Infrastructure - Axios client with request/response interceptors - Automatic JWT token injection - Auto-logout on 401 responses - Environment-based API configuration

✅ State Management - Pinia auth store with persistent state - User authentication state - Loading and error handling - LocalStorage integration

✅ API Services - Real backend calls replacing mockApi.ts - Type-safe API functions - Data transformation adapters - Backward compatibility with existing components

✅ Authentication UI - AuthModal component (login/register) - Integrated in AppHeader - Wallet-based or email/password flows - Mobile-responsive design

✅ Type Safety - Backend API types (types/api.ts) - Frontend types (types/index.ts) - Adapter layer for transformation - Full TypeScript coverage

File Structure¶

mentat-protocol/
├── apps/
│   ├── backend/                    # FastAPI Backend
│   │   ├── src/
│   │   │   ├── main.py            # FastAPI app
│   │   │   ├── config.py          # Settings
│   │   │   ├── database.py        # TortoiseORM config
│   │   │   ├── models/            # Database models
│   │   │   │   ├── user.py
│   │   │   │   ├── market.py
│   │   │   │   └── curation.py
│   │   │   ├── schemas/           # Pydantic schemas
│   │   │   │   ├── user.py
│   │   │   │   ├── market.py
│   │   │   │   └── curation.py
│   │   │   ├── api/v1/            # API routes
│   │   │   │   ├── auth.py
│   │   │   │   ├── markets.py
│   │   │   │   ├── drafts.py
│   │   │   │   └── curator.py
│   │   │   └── middleware/
│   │   │       └── auth.py        # JWT utilities
│   │   ├── migrations/            # Aerich migrations
│   │   ├── pyproject.toml
│   │   ├── Makefile
│   │   ├── .env.example
│   │   └── README.md
│   │
│   └── web/                        # Vue 3 Frontend
│       ├── src/
│       │   ├── config/
│       │   │   └── api.ts         # API endpoints
│       │   ├── lib/
│       │   │   └── apiClient.ts   # Axios client
│       │   ├── stores/
│       │   │   └── auth.ts        # Pinia auth store
│       │   ├── services/
│       │   │   ├── api.ts         # Real API calls
│       │   │   ├── adapters.ts    # Type adapters
│       │   │   └── mockApi.ts     # (deprecated)
│       │   ├── types/
│       │   │   ├── index.ts       # Frontend types
│       │   │   └── api.ts         # Backend types
│       │   └── components/
│       │       ├── AuthModal.vue
│       │       └── AppHeader.vue  # Updated with auth
│       ├── package.json
│       ├── .env.example
│       └── .gitignore
│
├── scripts/
│   └── setup-dev.sh                # Auto-setup script
│
├── INTEGRATION.md                  # Integration guide
└── WEB-INTEGRATION-SUMMARY.md     # This file

Quick Start¶

1. Run Setup Script¶

cd mentat-protocol
./scripts/setup-dev.sh

2. Create Database¶

createdb mentat_dev

3. Initialize Backend¶

cd apps/backend
aerich init-db
make dev

Backend runs at: http://localhost:8000

4. Start Frontend¶

cd apps/web
npm install
npm run dev

Frontend runs at: http://localhost:5173

5. Test Integration¶

Open http://localhost:5173
Click "Connect Wallet"
Register with a wallet address
JWT token stored, you're authenticated!

Key Features¶

Authentication Flow¶

User clicks "Connect Wallet"
    ↓
AuthModal opens
    ↓
User enters wallet address (+ optional email/password)
    ↓
Frontend: POST /api/v1/auth/register
    ↓
Backend: Creates user, generates JWT
    ↓
Frontend: Stores token in localStorage
    ↓
All subsequent requests include: Authorization: Bearer <token>
    ↓
User can browse markets, create drafts, etc.

API Integration¶

Frontend	Backend	Status
Market Discovery	`GET /api/v1/markets`	✅ Connected
Market Detail	`GET /api/v1/markets/{id}`	✅ Connected
User Registration	`POST /api/v1/auth/register`	✅ Connected
User Login	`POST /api/v1/auth/login`	✅ Connected
Draft Creation	`POST /api/v1/drafts`	✅ Connected
Curator Queue	`GET /api/v1/curator/queue`	✅ Connected
Draft Approval	`POST /api/v1/curator/{id}/approve`	✅ Connected

Data Flow¶

Vue Component
    ↓ calls
API Service (src/services/api.ts)
    ↓ uses
Axios Client (src/lib/apiClient.ts)
    ↓ injects token →
HTTP Request to Backend
    ↓
FastAPI Endpoint (src/api/v1/*.py)
    ↓ validates with
Pydantic Schema
    ↓ queries
TortoiseORM Model
    ↓ accesses
PostgreSQL Database
    ↓ returns
API Response
    ↓ transforms via
Adapter (src/services/adapters.ts)
    ↓ updates
Vue Component State

Environment Configuration¶

Backend (.env)¶

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mentat_dev
SECRET_KEY=change-this-in-production
CORS_ORIGINS=http://localhost:5173
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Frontend (.env)¶

VITE_API_URL=http://localhost:8000

Testing¶

Test User Registration¶

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK",
    "username": "alice"
  }'

Response:

{
  "access_token": "eyJ...",
  "token_type": "bearer",
  "expires_in": 604800,
  "user": {
    "id": "...",
    "wallet_address": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK",
    "username": "alice",
    ...
  }
}

Test Market Fetching¶

# No auth required for public markets
curl http://localhost:8000/api/v1/markets

Test Authenticated Request¶

curl http://localhost:8000/api/v1/auth/me \
  -H "Authorization: Bearer <your-jwt-token>"

Next Steps¶

Now that web-backend integration is complete, the next phase is:

M2 - Creator MVP Completion¶

AI Agents Integration
Set up DSPy pipelines in apps/ai-agents
Connect to draft creation endpoint
Implement validation agent
Creator Studio UI
Build conversational draft interface
Connect to backend draft APIs
Real-time validation feedback
Curator Console Enhancement
Diff view for draft changes
Rich approval/rejection UI
Action history timeline
WebSocket Integration
Real-time market updates
Live curator queue notifications
Draft status changes

M3 - On-Chain Launch¶

Solana Program Development
Build market-factory program
Build market-settlement program
Deploy to devnet
Indexer Service
Event listener for Solana
Market state synchronization
Analytics aggregation
On-Chain Deployment
Connect approved drafts to Solana
Market creation transactions
Trading interface

Documentation¶

Backend API Docs: http://localhost:8000/docs (Swagger UI)
Integration Guide: INTEGRATION.md
Backend README: apps/backend/README.md
Web Prototype Guide: docs/web-prototype.md

Support¶

All systems operational! 🚀

Backend: http://localhost:8000
Frontend: http://localhost:5173
Database: PostgreSQL on localhost:5432

Ready for M2 implementation: AI agents and creator studio!