Skip to content

Frontend Separation Guide

The web onboarding frontend has been extracted from the backend API into a separate package for independent deployment.

📦 Frontend Package Location

File: sage-onboarding-frontend.tar.gz (13KB, in this repository root)

To extract: 

tar -xzf sage-onboarding-frontend.tar.gz
cd sage-onboarding-frontend/

📁 Package Contents

sage-onboarding-frontend/
├── README.md                    # Quick start guide
├── API_INTEGRATION.md           # Complete API integration documentation
├── DEPLOYMENT.md                # Deployment guides for various platforms
├── .env.example                 # Environment variable template
├── package.json                 # Node.js dependencies (optional)
├── server.js                    # Optional Node.js server
├── templates/                   # HTML pages
│   ├── onboarding_welcome.html  # Step 1: Phone entry
│   ├── onboarding_verify.html   # Step 2: OTP verification + profile
│   ├── onboarding_trial.html    # Step 3: Trial payment
│   └── onboarding_success.html  # Step 4: Success confirmation
└── static/
    └── css/
        └── onboarding.css       # Mobile-first responsive styles

🚀 Quick Deploy Options

Option 1: Static Hosting (Netlify, Vercel, S3)

Best for: Simple deployments, serverless

# Deploy to Netlify
netlify deploy --prod

# Deploy to Vercel
vercel --prod

Option 2: Node.js Server (Cloud Run, ECS, Heroku)

Best for: Full control, custom logic

npm install
node server.js

Option 3: Any Web Server (Nginx, Apache)

Best for: Traditional hosting

Just serve the templates/ and static/ directories.

🔗 Backend API Integration

The frontend will call these backend endpoints:

Authentication Flow:

  1. POST /auth/verify/start - Send OTP code
  2. POST /auth/verify/confirm - Verify OTP + submit profile
  3. GET /auth/session - Check authentication status

Payment Flow:

  1. POST /payment/checkout/trial - Create $5 trial checkout
  2. POST /payment/checkout/topup - Create credit top-up checkout
  3. GET /payment/status/{user_id} - Get payment status

Usage & Credits:

  1. GET /usage/balance/{user_id} - Get credit balance
  2. GET /usage/history/{user_id} - Get transaction history
  3. GET /usage/pricing - Get pricing information

Full API documentation: See API_INTEGRATION.md in the package

⚙️ Configuration Required

Frontend Environment Variables:

BACKEND_API_URL=https://your-backend-api.com

Backend CORS Configuration:

In app/main.py, add your frontend domain to allowed origins:

allowed_origins = [
    "https://your-frontend-domain.com",
    "http://localhost:3000",  # For local development
]

📋 For the Frontend Engineer

Step-by-Step Setup:

  1. Extract the package: 

    tar -xzf sage-onboarding-frontend.tar.gz
cd sage-onboarding-frontend/

  2. Read the documentation:

  3. README.md - Overview and quick start
  4. API_INTEGRATION.md - Complete API reference with examples

  5. DEPLOYMENT.md - Platform-specific deployment guides

  6. Configure environment: 

    cp .env.example .env
# Edit .env with your backend API URL

  7. Test locally: 

    # Option A: Node.js server
npm install
npm start

# Option B: Python HTTP server
python -m http.server 3000
# Then navigate to http://localhost:3000/templates/onboarding_welcome.html

  8. Update JavaScript API URLs: All HTML files are configured to use window.ENV?.BACKEND_API_URL which falls back to http://localhost:8000.

To use environment variables, you can: - Set window.ENV = { BACKEND_API_URL: 'https://api.example.com' } in a config script - Or use the Node.js server which can inject environment variables - Or find/replace http://localhost:8000 with your production API URL

  1. Deploy to your platform:

  2. See DEPLOYMENT.md for Netlify, Vercel, AWS S3, Docker, etc.

  3. Configure backend CORS:

  4. Contact backend team to add your domain to allowed origins

  5. Test the complete flow:

  6. Welcome → Verify → Trial → Success
  7. Verify phone verification works
  8. Verify Stripe checkout works
  9. Check that cookies are being set/sent properly

🔒 Security Checklist

  • Frontend deployed via HTTPS
  • Backend CORS configured for frontend domain
  • Environment variables configured (not hardcoded)
  • API calls include credentials: 'include' for cookies
  • Test phone verification in Twilio test mode
  • Test Stripe checkout in test mode
  • Verify secure cookies are working

📞 Support

Frontend Issues:

  • Deployment problems → See DEPLOYMENT.md
  • API integration questions → See API_INTEGRATION.md
  • Environment configuration → See .env.example

Backend Issues:

  • API endpoints not working → Check backend logs
  • CORS errors → Verify frontend domain in backend's allowed_origins
  • Authentication errors → Verify cookies are being sent

🎯 What Changed in Backend

The following were removed from the backend repository: - web/templates/ directory (all HTML files) - web/static/ directory (CSS files) - app/api/web_routes.py (web page serving routes)

The backend is now a pure API service with no frontend code.

📈 Next Steps

  1. For Frontend Engineer:
  2. Extract package
  3. Read API_INTEGRATION.md thoroughly
  4. Set up local development
  5. Deploy to staging environment
  6. Test complete flow

  7. Deploy to production

  8. For Backend Team:

  9. Ensure CORS is configured
  10. Verify all API endpoints are working
  11. Set up Twilio and Stripe in production

  12. Monitor API usage and errors

  13. For Both Teams:

  14. Coordinate on API contract changes
  15. Share error logs for debugging
  16. Document any API changes
  17. Test end-to-end flow together

📚 Additional Resources

  • Twilio Test Numbers: https://www.twilio.com/docs/iam/test-credentials
  • Stripe Test Cards: https://stripe.com/docs/testing
  • Backend API Source: This repository
  • Frontend Package: sage-onboarding-frontend.tar.gz