Architecture Patterns

Multi-Tenancy: One Database, Many Shops

JongYang is a marketplace SaaS — one running application serves all shops. Every booking, resource, and service belongs to a specific shop via shop_id. This is multi-tenancy with row-level isolation:

async def list_bookings(
    admin: ShopAdmin = Depends(get_current_admin),  # JWT contains shop_id
    session: AsyncSession = Depends(get_db),
):
    q = (
        select(Booking)
        .where(Booking.shop_id == admin.shop_id)  # ← isolation enforced here
        .order_by(Booking.booking_date)
    )
    # BKK Sports Club admin can never see Paw & Groom's bookings
    # because admin.shop_id is always BKK's UUID

The shop_id is extracted from the JWT (set at login time) and embedded in every query. There's no way for an admin to query another shop's data — even if they tried to craft a malicious request, the dependency injection always applies their shop_id filter.

The Two Scheduling Models

if resource.resource_type == "staff":
    if not body.service_id:
        raise HTTPException(422, "service_id is required for staff resources")
    service = ...  # look up the service
    duration_min = service.duration_min  # OVERRIDE whatever was in the request
    total_price = service.price          # fixed price from service record

else:  # asset
    duration_min = body.duration_min     # customer's choice (60/90/120 min)
    total_price = float(resource.price_per_hour) * duration_min / 60
    service_id = None                    # no service for asset bookings

Subdomain Routing: The Full Picture

The middleware in proxy.ts handles three scenarios:

Scenario 1: Shop subdomain
  Request: bkk-sports-club.jongyang.xyz/
  Middleware:
    - pathname = "/"
    - slug = "bkk-sports-club" (not in RESERVED, not BASE_DOMAIN)
    - pathname does NOT start with "/shop/"
    → NextResponse.rewrite("/shop/bkk-sports-club")
    → Next.js serves app/shop/[slug]/page.tsx with slug="bkk-sports-club"
    → URL bar still shows bkk-sports-club.jongyang.xyz/

Scenario 2: Shop subdomain + booking link
  Request: bkk-sports-club.jongyang.xyz/shop/bkk-sports-club/book?...
  Middleware:
    - slug = "bkk-sports-club"
    - pathname STARTS WITH "/shop/" ← skip rewrite (prevents double-rewrite)
    → NextResponse.next() — serves /shop/bkk-sports-club/book directly
    → Next.js serves app/shop/[slug]/book/page.tsx

Scenario 3: Admin subdomain
  Request: admin.jongyang.xyz/
  Middleware:
    - pathname = "/"
    - does NOT start with "/admin" → skip admin guard
    - slug = "admin" → match admin subdomain condition
    - pathname does NOT start with "/api"
    → NextResponse.redirect("/admin/login")
    → Browser navigates to admin.jongyang.xyz/admin/login
    → Middleware runs again, pathname = "/admin/login"
    → admin guard: no token → NextResponse.next() → shows login page

The Admin Proxy Pattern

Why does the admin panel make API calls through Next.js (/api/admin/proxy/*) instead of directly to FastAPI? Security:

WITHOUT proxy (insecure):
  Browser JS → directly calls https://api.jongyang.xyz/api/admin/bookings
  Browser must store the JWT somewhere JS can read → XSS risk

WITH proxy (what we do):
  Browser JS → POST /api/admin/proxy/bookings (Next.js API route)
                   ↓
             Next.js server reads httpOnly cookie (JS can't do this)
             Adds: Authorization: Bearer {JWT}
             Forwards to: https://api.jongyang.xyz/api/admin/bookings
                   ↓
             FastAPI verifies JWT → returns bookings
                   ↓
             Next.js returns JSON to browser
  Browser receives data — never saw the JWT

CORS: Cross-Origin Resource Sharing

Browsers enforce the "same-origin policy" — JavaScript on jongyang.xyz can't make requests to api.jongyang.xyz without permission. CORS is the mechanism for granting that permission:

app.add_middleware(
    CORSMiddleware,
    allow_origins=settings.ALLOWED_ORIGINS,  # list of allowed origins
    allow_credentials=True,   # allow cookies to be included in cross-origin requests
    allow_methods=["*"],      # GET, POST, PATCH, DELETE, etc.
    allow_headers=["*"],
)

# CORRECT: pydantic-settings parses list[str] fields as JSON
ALLOWED_ORIGINS=["https://jongyang.xyz","https://admin.jongyang.xyz","https://bkk-sports-club.jongyang.xyz"]

# WRONG: comma-separated string causes JSONDecodeError
ALLOWED_ORIGINS=https://jongyang.xyz,https://admin.jongyang.xyz

Background Tasks: APScheduler Pattern

Background tasks (expiry, reminders) need a database session, but they're not HTTP request handlers. The pattern: create a new async session for each job run:

async def expire_pending_bookings() -> None:
    async with AsyncSessionLocal() as session:  # create a fresh session
        await run_expire_task(session)
    # session closes automatically

# Registered with APScheduler:
scheduler.add_job(expire_pending_bookings, "interval", minutes=5)

The session is scoped to the job execution — it opens when the job starts and closes when it finishes. This is the same pattern as get_db() for HTTP requests, just without the request lifecycle managing it.