ttbkk-edge

🌐 Supabase Edge Functions for ttbkk ecosystem - API gateway with authentication, geocoding, and data management

📋 Overview

ttbkk-edge is a collection of Supabase Edge Functions that serve as an API gateway for the ttbkk (떡볶이맵) ecosystem. It provides:

• Geocoding API: Convert place names to coordinates using Kakao Maps API
• Authentication: Secure API access and user management
• Data Management: CRUD operations with proper authorization
• Rate Limiting: API usage control and monitoring

🏗️ Architecture

ttbkk-web (Frontend) → ttbkk-edge (API Gateway) → External APIs + Supabase

Benefits

• Security: Hide API keys and manage authentication
• Consistency: Unified API interface for all clients
• Scalability: Edge-based serverless architecture
• Monitoring: Request logging and analytics

🚀 Quick Start

Prerequisites

• Deno installed
• Supabase CLI installed
• Supabase project set up
• Kakao Maps API key

Local Development

1. Clone and setup

   git clone <repository-url>
   cd ttbkk-edge

2. Install Supabase CLI

   npm install -g supabase

3. Link to your Supabase project

   supabase link --project-ref your-project-id

4. Set environment variables

   cp env.example .env
   # Edit .env with your actual values

5. Start local development

   supabase start
   npm run dev

6. Test the functions

   curl -X POST http://localhost:54321/functions/v1/geocoding \
     -H "Content-Type: application/json" \
     -d '{"query": "강남역"}'

📡 API Endpoints

Authentication

ttbkk-edge uses Supabase Auth with Google OAuth integration for user authentication.

Sign Up / Sign In with Google

Use Supabase client-side authentication:

import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  'https://izhutepzzveasglrlbcx.supabase.co',
  'your-anon-key'
)

// Sign in with Google
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'google',
  options: {
    redirectTo: 'http://localhost:3000/auth/callback'
  }
})

User Profile API

Endpoint: GET/PUT /functions/v1/user-profile

Headers:

Authorization: Bearer <user-jwt-token>
Content-Type: application/json

GET Response:

{
  "success": true,
  "data": {
    "id": "user-uuid",
    "display_name": "John Doe",
    "avatar_url": "https://...",
    "bio": "Love tteokbokki!",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

PUT Request:

{
  "display_name": "Jane Doe",
  "avatar_url": "https://new-avatar-url.com",
  "bio": "Tteokbokki enthusiast 🌶️"
}

Geocoding API

Endpoint: POST /functions/v1/geocoding

Request:

{
  "query": "강남역",
  "provider": "kakao",
  "limit": 1
}

Response:

{
  "success": true,
  "data": {
    "latitude": 37.497952,
    "longitude": 127.027619,
    "address": "서울 강남구 역삼동",
    "formatted_address": "강남역",
    "provider": "kakao",
    "confidence": 1.0
  }
}

Error Response:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "No results found for the given query"
  }
}

🔧 Configuration

Environment Variables

Variable	Description	Required
SUPABASE_URL	Your Supabase project URL	✅
SUPABASE_ANON_KEY	Supabase anonymous key	✅
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key	✅
KAKAO_API_KEY	Kakao Maps API key	✅
GOOGLE_OAUTH_CLIENT_ID	Google OAuth 2.0 Client ID	✅
GOOGLE_OAUTH_CLIENT_SECRET	Google OAuth 2.0 Client Secret	✅

GitHub Secrets (for CI/CD)

Secret	Description
SUPABASE_PROJECT_ID	Your Supabase project reference ID
SUPABASE_ACCESS_TOKEN	Supabase access token for CLI
KAKAO_API_KEY	Kakao Maps API key

🚢 Deployment

Automatic Deployment (Recommended)

1. Push to main branch
2. GitHub Actions automatically deploys to Supabase

Manual Deployment

# Deploy all functions
supabase functions deploy

# Deploy specific function
supabase functions deploy geocoding

🔐 Google OAuth Setup

1. Create Google OAuth Application

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google+ API
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth 2.0 Client IDs
6. Configure consent screen if needed
7. Set Application type to Web application
8. Add authorized redirect URIs:
   • https://izhutepzzveasglrlbcx.supabase.co/auth/v1/callback
   • http://localhost:54321/auth/v1/callback (for local development)

2. Configure Supabase

1. Go to your Supabase project dashboard
2. Navigate to Authentication > Providers
3. Enable Google provider
4. Enter your Google OAuth credentials:
   • Client ID: From Google Cloud Console
   • Client Secret: From Google Cloud Console

3. Set Environment Variables

# In production (Supabase Dashboard > Settings > Edge Functions)
GOOGLE_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret

# Or using Supabase CLI
supabase secrets set GOOGLE_OAUTH_CLIENT_ID=your-client-id
supabase secrets set GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret

🧪 Testing

Local Testing

# Start local Supabase
supabase start

# Test geocoding
curl -X POST http://localhost:54321/functions/v1/geocoding \
  -H "Content-Type: application/json" \
  -d '{"query": "홍대입구역"}'

Production Testing

curl -X POST https://your-project-id.supabase.co/functions/v1/geocoding \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-anon-key" \
  -d '{"query": "강남역"}'

📊 Monitoring

Supabase Dashboard

• Function logs: Supabase Dashboard > Edge Functions > Logs
• Performance metrics: Supabase Dashboard > Settings > API

Error Handling

All functions return standardized error responses:

• 400: Bad Request (invalid input)
• 401: Unauthorized
• 404: Not Found
• 429: Rate Limited
• 500: Internal Server Error

🔗 Integration

With ttbkk-mcp-server

The geocoding function is designed to work with the ttbkk-mcp-server:

// MCP tool integration example
const geocodeResult = await fetch(`${TTBKK_EDGE_URL}/functions/v1/geocoding`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: '강남역' })
})

With ttbkk-web

Frontend integration with proper error handling:

import { GeocodeResponse } from '@/types/geocoding'

export async function geocodeAddress(query: string): Promise<GeocodeResponse> {
  const response = await fetch('/api/geocode', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query })
  })
  
  return response.json()
}

📝 Development Notes

Code Style

• Use TypeScript for type safety
• Follow Deno conventions
• Implement proper error handling
• Include comprehensive logging

Performance

• Edge functions are optimized for low latency
• Implement caching where appropriate
• Monitor function execution time

Security

• Validate all inputs
• Sanitize user queries
• Implement rate limiting
• Use proper CORS headers

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

• ttbkk-web - Frontend application
• ttbkk-mcp-server - MCP server for AI tools
• ttbkk-data - Data management tools