managarten/manadeck/backend/README_MANA_INTEGRATION.md

ManaDeck Backend with Mana Core Integration

Overview

This is the NestJS backend for ManaDeck, integrated with the Mana Core authentication system. It provides a secure API for the ManaDeck mobile application with centralized authentication, user management, and database operations.

Architecture

Mobile App (React Native/Expo)
    ↓ API requests
Backend Service (NestJS + @mana-core/nestjs-integration)
    ↓ Proxy auth requests
Mana Core Middleware (Central Auth Service)
    ↓ User management
Supabase (Database & Storage)

Features

• ✅ Mana Core authentication integration
• ✅ Protected and public API endpoints
• ✅ Supabase database integration with RLS
• ✅ Health check endpoints
• ✅ CORS configuration for mobile app
• ✅ Docker containerization
• ✅ Google Cloud Run deployment ready

Project Structure

backend/
├── src/
│   ├── config/
│   │   └── validation.schema.ts    # Environment variable validation
│   ├── controllers/
│   │   ├── api.controller.ts       # Protected API endpoints
│   │   ├── public.controller.ts    # Public endpoints
│   │   └── health.controller.ts    # Health checks
│   ├── services/
│   │   └── supabase.service.ts     # Database operations
│   ├── app.controller.ts           # Default app controller
│   ├── app.module.ts               # Main application module
│   ├── app.service.ts              # Default app service
│   └── main.ts                     # Application entry point
├── .env                            # Environment variables
├── .env.example                    # Example environment file
├── Dockerfile                      # Docker configuration
├── cloudbuild.yaml                # Google Cloud Build config
└── package.json                   # Dependencies and scripts

Prerequisites

• Node.js 18+
• NPM or Yarn
• Mana Core Middleware running (locally or deployed)
• Supabase project with configured database

Installation

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env

# Edit .env with your configuration

Configuration

Required Environment Variables

# Server Configuration
NODE_ENV=development
PORT=8080

# Mana Core Configuration
MANA_SERVICE_URL=http://localhost:3000  # URL to Mana Core Middleware
APP_ID=your-app-id                      # Your app's UUID
SERVICE_KEY=your-service-key            # Optional service key
SIGNUP_REDIRECT_URL=https://yourapp.com/welcome

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key   # Optional for admin operations

# JWT Configuration
JWT_SECRET=your-jwt-secret

# CORS Configuration
FRONTEND_URL=http://localhost:8081

Available Endpoints

Authentication (Proxied by ManaCoreModule)

• POST /auth/signin - Email/password sign-in
• POST /auth/signup - User registration
• POST /auth/google-signin - Google OAuth
• POST /auth/apple-signin - Apple OAuth
• POST /auth/refresh - Token refresh
• POST /auth/logout - User logout
• POST /auth/forgot-password - Password reset
• POST /auth/validate - Token validation
• GET /auth/credits - Get user credits
• GET /auth/devices - Get user devices

Protected API Endpoints (Requires Authentication)

• GET /v1/api/profile - Get user profile
• GET /v1/api/decks - Get user's decks
• POST /v1/api/decks - Create a new deck
• PUT /v1/api/decks/:id - Update a deck
• DELETE /v1/api/decks/:id - Delete a deck
• GET /v1/api/cards - Get user's cards
• POST /v1/api/cards - Create a new card
• GET /v1/api/stats - Get user statistics

Public Endpoints

• GET /v1/public/featured-decks - Get featured decks (personalized if authenticated)
• GET /v1/public/leaderboard - Get leaderboard
• GET /v1/public/deck-templates - Get deck templates
• GET /v1/public/announcements - Get announcements
• GET /v1/public/health - Basic health check
• GET /v1/public/version - API version info

Health Checks

• GET /health - Comprehensive health check
• GET /health/ready - Readiness probe
• GET /health/live - Liveness probe

Development

# Start development server with watch mode
npm run start:dev

# Start production server
npm run start:prod

# Run tests
npm test

# Run linting
npm run lint

# Build the application
npm run build

Testing the Integration

1. Start Mana Core Middleware (if running locally):

cd ../mana-core-middleware
npm run start:dev

2. Start the Backend:

npm run start:dev

3. Test Health Check:

curl http://localhost:8080/health

4. Test Public Endpoint:

curl http://localhost:8080/v1/public/version

5. Test Authentication:

# Sign up
curl -X POST http://localhost:8080/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Sign in
curl -X POST http://localhost:8080/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

6. Test Protected Endpoint:

# Use the token from signin response
curl http://localhost:8080/v1/api/profile \
  -H "Authorization: Bearer YOUR_TOKEN"

Docker

Build Docker Image

docker build -t manadeck-backend .

Run Docker Container

docker run -p 8080:8080 --env-file .env manadeck-backend

Deployment

Google Cloud Run

1. Build and push to Container Registry:

gcloud builds submit --config cloudbuild.yaml

2. Or deploy directly:

gcloud run deploy manadeck-backend \
  --source . \
  --region us-central1 \
  --allow-unauthenticated

Mobile App Integration

Update your React Native app to use the backend:

1. Update API configuration:

// utils/api.js
const API_URL = process.env.EXPO_PUBLIC_API_URL || 'http://localhost:8080';

2. Use auth endpoints:

// Sign in
const response = await fetch(`${API_URL}/auth/signin`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password }),
});

3. Use protected endpoints:

// Get profile
const response = await fetch(`${API_URL}/v1/api/profile`, {
  headers: {
    'Authorization': `Bearer ${token}`
  },
});

Security Considerations

• Always use HTTPS in production
• Keep SERVICE_KEY secure and never expose it
• Regularly rotate JWT_SECRET
• Use environment-specific configurations
• Enable rate limiting on auth endpoints
• Implement proper CORS policies
• Use Supabase RLS for data security

Troubleshooting

"App verification failed"

• Verify APP_ID matches the one registered with Mana Core
• Check MANA_SERVICE_URL is correct and accessible

"Token expired" errors

• Ensure token refresh is implemented in the mobile app
• Check token expiration settings in Mana Core

"CORS errors" in mobile app

• Update FRONTEND_URL in .env
• Verify CORS configuration in main.ts

"Cannot connect to Mana Core"

• Ensure Mana Core Middleware is running
• Check network connectivity
• Verify MANA_SERVICE_URL is correct

Next Steps

1. Database Setup: Create tables in Supabase for decks, cards, etc.
2. RLS Policies: Implement Row-Level Security in Supabase
3. Testing: Add unit and integration tests
4. Monitoring: Set up logging and monitoring
5. CI/CD: Configure automated deployment pipeline
6. Documentation: Generate API documentation with Swagger

Support

For issues or questions:

• Check the Mana Core documentation
• Review the integration guides
• Contact the development team