refactor

app.py

@@ -39,6 +39,52 @@ async def lifespan(app: FastAPI):
     register_db_service_config()
     logger.info("✅ DB Service configured")
     
+    # Register Auth Service configuration
+    from services.auth_service import register_auth_service
+    register_auth_service(
+        required_urls=[
+            "/blink",
+            "/api/*",  # All admin blink API endpoints
+            "/contact",
+            "/gemini/*",
+            "/credits/balance",
+            "/credits/history",
+            "/payments/create-order",
+            "/payments/verify/*",
+        ],
+        optional_urls=[
+            "/",  # Home page works with or without auth
+        ],
+        public_urls=[
+            "/health",
+            "/auth/*",
+            "/payments/packages",  # Public pricing info
+            "/payments/webhook/*",  # Webhooks from payment gateway
+            "/docs",
+            "/openapi.json",
+            "/redoc",
+        ],
+        jwt_secret=os.getenv("JWT_SECRET"),
+        jwt_algorithm="HS256",
+        jwt_expiry_hours=24,
+        google_client_id=os.getenv("AUTH_SIGN_IN_GOOGLE_CLIENT_ID"),
+        admin_emails=os.getenv("ADMIN_EMAILS", "").split(",") if os.getenv("ADMIN_EMAILS") else [],
+    )
+    logger.info("✅ Auth Service configured")
+    
+    # Register Credit Service configuration
+    from services.credit_service import register_credit_service
+    register_credit_service(
+        route_costs={
+            "/gemini/generate-animation-prompt": 1,
+            "/gemini/edit-image": 1,
+            "/gemini/generate-video": 10,
+            "/gemini/generate-text": 1,
+            "/gemini/analyze-image": 1,
+        }
+    )
+    logger.info("✅ Credit Service configured")
+    
     # Check for RESET_DB environment variable
     if os.getenv("RESET_DB", "").lower() == "true":
         logger.warning(f"RESET_DB is set to true. Skipping download and clearing local database ({DB_FILENAME}).")
@@ -95,6 +141,14 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+# Add Credit Middleware first (executes second - after auth)
+from services.credit_service import CreditMiddleware
+app.add_middleware(CreditMiddleware)
+
+# Add Auth Middleware second (executes first - sets user)
+from services.auth_service import AuthMiddleware
+app.add_middleware(AuthMiddleware)
+
 # Include Routers
 app.include_router(general.router)
 app.include_router(auth.router)

routers/blink.py

@@ -11,7 +11,7 @@ import logging
 from core.database import get_db
 from core.models import User, AuditLog, GeminiJob, Contact, ClientUser
 from services.encryption_service import decrypt_multiple_blocks
-from dependencies import get_geolocation, get_optional_user, get_current_user
+from dependencies import get_geolocation
 
 logger = logging.getLogger(__name__)
 
@@ -27,16 +27,18 @@ USER_ID_LENGTH = 20
 
 @router.get("/api/data")
 async def get_data(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(100, ge=1, le=500, description="Items per page"),
     log_type: str = Query(None, description="Filter by log type: client, server"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get paginated audit log data for the authenticated user.
     Admins see all logs from all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from services.db_service import QueryService
     
     try:
@@ -93,15 +95,17 @@ async def get_data(
 
 @router.get("/api/users")
 async def get_users(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(50, ge=1, le=500, description="Items per page"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get current user's profile data.
     Admins see paginated list of all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from services.db_service import QueryService
     
     try:
@@ -148,16 +152,18 @@ async def get_users(
 
 @router.get("/api/client-users")
 async def get_client_users(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(50, ge=1, le=500, description="Items per page"),
     user_id: str = Query(None, description="Filter by server user_id"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get current user's client mappings.
     Admins see all client mappings from all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from services.db_service import QueryService
     
     try:
@@ -197,17 +203,19 @@ async def get_client_users(
 
 @router.get("/api/audit-logs")
 async def get_audit_logs(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(50, ge=1, le=500, description="Items per page"),
     log_type: str = Query(None, description="Filter by log type: client, server"),
     action: str = Query(None, description="Filter by action"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get current user's audit logs with optional filters.
     Admins see all logs from all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from services.db_service import QueryService
     
     try:
@@ -263,15 +271,17 @@ async def get_audit_logs(
 
 @router.get("/api/gemini-jobs")
 async def get_gemini_jobs(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(50, ge=1, le=500, description="Items per page"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get current user's Gemini jobs.
     Admins see all jobs from all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from services.db_service import QueryService
     
     try:
@@ -313,15 +323,17 @@ async def get_gemini_jobs(
 
 @router.get("/api/payment-transactions")
 async def get_payment_transactions(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(50, ge=1, le=500, description="Items per page"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get current user's payment transactions.
     Admins see all transactions from all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from core.models import PaymentTransaction
     from services.db_service import QueryService
     
@@ -383,15 +395,17 @@ async def get_payment_transactions(
 
 @router.get("/api/contacts")
 async def get_contacts(
+    request: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(50, ge=1, le=500, description="Items per page"),
-    user: User = Depends(get_current_user),  # Auth required
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get current user's contact form submissions.
     Admins see all contact submissions from all users.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = request.state.user
     from services.db_service import QueryService
     
     try:
@@ -436,13 +450,16 @@ async def get_contacts(
 async def blink(
     request: Request,
     userid: str = Query(..., description="User ID (20 chars) + encrypted data"),
-    db: AsyncSession = Depends(get_db),
-    current_user: User = Depends(get_optional_user)
+    db: AsyncSession = Depends(get_db)
 ):
     """
     Process blink request with encrypted user data.
     Logs to AuditLog with log_type='client'.
     
+    Auth is optional (handled by AuthMiddleware):
+    - If authenticated: user in request.state.user
+    - If not authenticated: request.state.user is None
+    
     If authenticated via JWT:
     - Creates a new ClientUser entry linking client_user_id to server user_id
     - Sets user_id in AuditLog entries
@@ -450,6 +467,8 @@ async def blink(
     If not authenticated:
     - Creates AuditLog entries with user_id=None (anonymous)
     """
+    # Optional auth - may be None
+    current_user = request.state.user
     try:
         # Validate minimum length
         if len(userid) < USER_ID_LENGTH:

routers/contact.py

@@ -14,7 +14,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from core.database import get_db
 from core.models import User, Contact
-from dependencies import get_current_user
 
 logger = logging.getLogger(__name__)
 
@@ -45,14 +44,17 @@ class ContactResponse(BaseModel):
 async def submit_contact(
     request_body: ContactRequest,
     request: Request,
-    user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Submit a contact form for customer support.
     
-    Requires authentication - user must be logged in.
+    Requires authentication - user is authenticated by AuthMiddleware.
+    User is available in request.state.user
     """
+    # Get authenticated user from middleware
+    user = request.state.user
+    
     # Validate message
     if not request_body.message or not request_body.message.strip():
         raise HTTPException(

routers/credits.py

@@ -3,7 +3,7 @@ Credits Router - API endpoints for credit management.
 
 Provides endpoints for checking credit balance and viewing credit history.
 """
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, Query, Request
 from pydantic import BaseModel
 from typing import List, Optional
 from datetime import datetime
@@ -12,7 +12,6 @@ from sqlalchemy import select, desc
 
 from core.database import get_db
 from core.models import User, GeminiJob
-from dependencies import get_current_user
 
 router = APIRouter(prefix="/credits", tags=["credits"])
 
@@ -47,15 +46,17 @@ class CreditHistoryResponse(BaseModel):
     limit: int
 
 
-@router.get("", response_model=CreditBalanceResponse)
+@router.get("/balance", response_model=CreditBalanceResponse)
 async def get_credits(
-    user: User = Depends(get_current_user)
+    request: Request
 ):
     """
     Get current credit balance.
     
     Returns the user's current credit balance and last usage time.
+    Auth is handled by AuthMiddleware - user is in request.state.user
     """
+    user = request.state.user
     return CreditBalanceResponse(
         user_id=user.user_id,
         credits=user.credits,
@@ -65,7 +66,7 @@ async def get_credits(
 
 @router.get("/history", response_model=CreditHistoryResponse)
 async def get_credit_history(
-    user: User = Depends(get_current_user),
+    request: Request,
     db: AsyncSession = Depends(get_db),
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(20, ge=1, le=100, description="Items per page")
@@ -77,7 +78,9 @@ async def get_credit_history(
     showing which jobs used credits and which were refunded.
     
     Only includes jobs where credits were reserved (credits_reserved > 0).
+    Auth is handled by AuthMiddleware - user is in request.state.user
     """
+    user = request.state.user
     offset = (page - 1) * limit
     
     # Query jobs with credit transactions

routers/gemini.py

@@ -5,7 +5,7 @@ Authentication via JWT (Authorization: Bearer <token>).
 """
 import os
 import uuid
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel, Field
 from typing import Optional, Literal
@@ -15,7 +15,6 @@ from sqlalchemy import select, func
 from core.database import get_db
 from core.models import User, GeminiJob
 from services.gemini_service import MODELS, DOWNLOADS_DIR
-from dependencies import verify_credits, verify_video_credits, get_current_user
 from datetime import datetime
 
 router = APIRouter(prefix="/gemini", tags=["gemini"])
@@ -102,13 +101,16 @@ async def create_job(
 
 @router.post("/generate-animation-prompt")
 async def generate_animation_prompt(
+    req: Request,
     request: GenerateAnimationPromptRequest,
-    user: User = Depends(verify_credits),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Queue an animation prompt generation job.
+    Auth and credit validation handled by middleware.
     """
+    user = req.state.user
+    credits_reserved = req.state.credits_reserved
     job = await create_job(
         db=db,
         user=user,
@@ -118,7 +120,7 @@ async def generate_animation_prompt(
             "mime_type": request.mime_type,
             "custom_prompt": request.custom_prompt
         },
-        credits_reserved=1
+        credits_reserved=credits_reserved
     )
     
     position = await get_queue_position(db, job.job_id)
@@ -134,13 +136,16 @@ async def generate_animation_prompt(
 
 @router.post("/edit-image")
 async def edit_image(
+    req: Request,
     request: EditImageRequest,
-    user: User = Depends(verify_credits),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Queue an image edit job.
+    Auth and credit validation handled by middleware.
     """
+    user = req.state.user
+    credits_reserved = req.state.credits_reserved
     job = await create_job(
         db=db,
         user=user,
@@ -150,7 +155,7 @@ async def edit_image(
             "mime_type": request.mime_type,
             "prompt": request.prompt
         },
-        credits_reserved=1
+        credits_reserved=credits_reserved
     )
     
     position = await get_queue_position(db, job.job_id)
@@ -166,13 +171,16 @@ async def edit_image(
 
 @router.post("/generate-video")
 async def generate_video(
+    req: Request,
     request: GenerateVideoRequest,
-    user: User = Depends(verify_video_credits),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Queue a video generation job.
+    Auth and credit validation handled by middleware.
     """
+    user = req.state.user
+    credits_reserved = req.state.credits_reserved
     job = await create_job(
         db=db,
         user=user,
@@ -185,7 +193,7 @@ async def generate_video(
             "resolution": request.resolution,
             "number_of_videos": request.number_of_videos
         },
-        credits_reserved=10  # Video jobs cost 10 credits
+        credits_reserved=credits_reserved  # 10 credits for video
     )
     
     position = await get_queue_position(db, job.job_id)
@@ -201,13 +209,16 @@ async def generate_video(
 
 @router.post("/generate-text")
 async def generate_text(
+    req: Request,
     request: GenerateTextRequest,
-    user: User = Depends(verify_credits),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Queue a text generation job.
+    Auth and credit validation handled by middleware.
     """
+    user = req.state.user
+    credits_reserved = req.state.credits_reserved
     job = await create_job(
         db=db,
         user=user,
@@ -216,7 +227,7 @@ async def generate_text(
             "prompt": request.prompt,
             "model": request.model
         },
-        credits_reserved=1
+        credits_reserved=credits_reserved
     )
     
     position = await get_queue_position(db, job.job_id)
@@ -232,13 +243,16 @@ async def generate_text(
 
 @router.post("/analyze-image")
 async def analyze_image(
+    req: Request,
     request: AnalyzeImageRequest,
-    user: User = Depends(verify_credits),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Queue an image analysis job.
+    Auth and credit validation handled by middleware.
     """
+    user = req.state.user
+    credits_reserved = req.state.credits_reserved
     job = await create_job(
         db=db,
         user=user,
@@ -248,7 +262,7 @@ async def analyze_image(
             "mime_type": request.mime_type,
             "prompt": request.prompt
         },
-        credits_reserved=1
+        credits_reserved=credits_reserved
     )
     
     position = await get_queue_position(db, job.job_id)
@@ -264,7 +278,7 @@ async def analyze_image(
 
 @router.get("/jobs")
 async def get_jobs(
-    user: User = Depends(get_current_user),
+    req: Request,
     db: AsyncSession = Depends(get_db),
     page: int = 1,
     limit: int = 20
@@ -272,7 +286,9 @@ async def get_jobs(
     """
     Get all jobs created by the current user.
     Returns a paginated list of jobs with status, type, and prompt (for video jobs).
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     offset = (page - 1) * limit
     
     # Query jobs for the current user
@@ -326,14 +342,16 @@ async def get_jobs(
 @router.get("/job/{job_id}")
 async def get_job_status(
     job_id: str,
-    user: User = Depends(get_current_user),
+    req: Request,
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get the status of a job.
     Poll this endpoint until status is 'completed' or 'failed'.
     For processing video jobs, this will check the Gemini API status and update the job.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     query = select(GeminiJob).where(
         GeminiJob.job_id == job_id,
         GeminiJob.user_id == user.id  # Integer FK comparison
@@ -391,14 +409,16 @@ async def get_job_status(
 @router.get("/download/{job_id}")
 async def download_video(
     job_id: str,
-    user: User = Depends(get_current_user),
+    req: Request,
     db: AsyncSession = Depends(get_db)
 ):
     """
     Download a generated video.
     Downloads from Gemini URL, streams to client, then deletes local file.
     No permanent storage on server.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     from fastapi.responses import StreamingResponse
     import httpx
     
@@ -470,14 +490,16 @@ async def download_video(
 @router.post("/job/{job_id}/cancel")
 async def cancel_job(
     job_id: str,
-    user: User = Depends(get_current_user),
+    req: Request,
     db: AsyncSession = Depends(get_db)
 ):
     """
     Cancel a queued job.
     Only jobs with status 'queued' can be cancelled.
     Processing/completed/failed jobs cannot be cancelled.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     query = select(GeminiJob).where(
         GeminiJob.job_id == job_id,
         GeminiJob.user_id == user.id  # Integer FK comparison
@@ -512,7 +534,7 @@ async def cancel_job(
 @router.delete("/job/{job_id}")
 async def delete_job(
     job_id: str,
-    user: User = Depends(get_current_user),
+    req: Request,
     db: AsyncSession = Depends(get_db)
 ):
     """
@@ -521,7 +543,9 @@ async def delete_job(
     Refund policy:
     - If queued: Refund 8 credits (10 cost - 2 penalty), soft delete job.
     - If processing/completed/failed: Soft delete job (no refund).
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     from services.db_service import QueryService
     
     qs = QueryService(user, db)

routers/payments.py

@@ -21,7 +21,6 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from core.database import get_db
 from core.models import User, PaymentTransaction
-from dependencies import get_current_user
 from services.drive_service import DriveService
 from services.razorpay_service import (
     RazorpayService,
@@ -223,8 +222,8 @@ async def get_packages():
 
 @router.post("/create-order", response_model=CreateOrderResponse)
 async def create_order(
+    req: Request,
     request: CreateOrderRequest,
-    user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
     """
@@ -232,7 +231,9 @@ async def create_order(
     
     The client should use the returned order_id to open
     Razorpay checkout. After payment, call /verify endpoint.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     # Check if Razorpay is configured
     if not is_razorpay_configured():
         raise HTTPException(
@@ -315,9 +316,9 @@ async def create_order(
 
 @router.post("/verify", response_model=VerifyPaymentResponse)
 async def verify_payment(
+    req: Request,
     request: VerifyPaymentRequest,
     background_tasks: BackgroundTasks,
-    user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
     """
@@ -325,7 +326,9 @@ async def verify_payment(
     
     Called after successful Razorpay checkout.
     Verifies the payment signature and credits the user.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     try:
         razorpay_service = get_razorpay_service()
         
@@ -557,16 +560,18 @@ async def razorpay_webhook(
 
 @router.get("/history", response_model=PaymentHistoryResponse)
 async def get_payment_history(
+    req: Request,
     page: int = Query(1, ge=1, description="Page number"),
     limit: int = Query(20, ge=1, le=100, description="Items per page"),
-    user: User = Depends(get_current_user),
     db: AsyncSession = Depends(get_db)
 ):
     """
     Get user's payment history with pagination.
     
     Returns payment transactions ordered by newest first.
+    Auth handled by AuthMiddleware - user in request.state.user
     """
+    user = req.state.user
     # Get total count
     count_result = await db.execute(
         select(func.count(PaymentTransaction.id))

services/auth_service/__init__.py

@@ -0,0 +1,106 @@
+"""
+Auth Service - Authentication layer for API Gateway
+
+Provides plug-and-play authentication with:
+- Google OAuth integration
+- JWT token management
+- Request middleware for auth validation
+- URL-based route configuration
+
+Usage:
+    # In app.py startup
+    from services.auth_service import register_auth_service
+    
+    register_auth_service(
+        required_urls=["/api/*", "/admin/*"],
+        public_urls=["/", "/health", "/auth/*"],
+        jwt_secret=os.getenv("JWT_SECRET"),
+        google_client_id=os.getenv("GOOGLE_CLIENT_ID")
+    )
+    
+    # In routers
+    from fastapi import Request
+    
+    @router.get("/protected")
+    async def protected_route(request: Request):
+        user = request.state.user  # Populated by AuthMiddleware
+        return {"user_id": user.id}
+"""
+
+from services.auth_service.config import AuthServiceConfig
+from services.auth_service.middleware import AuthMiddleware
+from services.auth_service.google_provider import (
+    GoogleAuthService,
+    GoogleUserInfo,
+    verify_google_token,
+    GoogleAuthError,
+    InvalidTokenError as GoogleInvalidTokenError,
+)
+from services.auth_service.jwt_provider import (
+    JWTService,
+    TokenPayload,
+    create_access_token,
+    verify_access_token,
+    JWTError,
+    TokenExpiredError,
+    InvalidTokenError,
+)
+
+
+def register_auth_service(
+    required_urls: list = None,
+    optional_urls: list = None,
+    public_urls: list = None,
+    jwt_secret: str = None,
+    jwt_algorithm: str = "HS256",
+    jwt_expiry_hours: int = 24,
+    google_client_id: str = None,
+    admin_emails: list = None,
+) -> None:
+    """
+    Register the auth service with application configuration.
+    
+    Args:
+        required_urls: URLs that REQUIRE authentication
+        optional_urls: URLs where authentication is optional
+        public_urls: URLs that don't need authentication
+        jwt_secret: Secret key for JWT signing
+        jwt_algorithm: JWT algorithm (default: HS256)
+        jwt_expiry_hours: Token expiry in hours (default: 24)
+        google_client_id: Google OAuth Client ID
+        admin_emails: List of admin email addresses
+    """
+    AuthServiceConfig.register(
+        required_urls=required_urls or [],
+        optional_urls=optional_urls or [],
+        public_urls=public_urls or [],
+        jwt_secret=jwt_secret,
+        jwt_algorithm=jwt_algorithm,
+        jwt_expiry_hours=jwt_expiry_hours,
+        google_client_id=google_client_id,
+        admin_emails=admin_emails or [],
+    )
+
+
+__all__ = [
+    # Registration
+    'register_auth_service',
+    'AuthServiceConfig',
+    'AuthMiddleware',
+    
+    # Google OAuth
+    'GoogleAuthService',
+    'GoogleUserInfo',
+    'verify_google_token',
+    'GoogleAuthError',
+    'GoogleInvalidTokenError',
+    
+    # JWT
+    'JWTService',
+    'TokenPayload',
+    'create_access_token',
+    'verify_access_token',
+    'JWTError',
+    'TokenExpiredError',
+    'InvalidTokenError',
+]

services/auth_service/config.py

@@ -0,0 +1,164 @@
+"""
+Auth Service Configuration
+
+Manages authentication configuration and route matching for the auth service.
+"""
+
+import logging
+from typing import List
+from services.base_service import BaseService, ServiceConfig
+from services.base_service.route_matcher import RouteConfig
+
+logger = logging.getLogger(__name__)
+
+
+class AuthServiceConfig(BaseService):
+    """
+    Configuration for the auth service.
+    
+    Controls which routes require authentication, which are optional,
+    and which are public (no auth needed).
+    """
+    
+    SERVICE_NAME = "auth_service"
+    
+    # Route configuration
+    _route_config: RouteConfig = None
+    
+    # JWT configuration
+    _jwt_secret: str = None
+    _jwt_algorithm: str = "HS256"
+    _jwt_expiry_hours: int = 24
+    
+    # Google OAuth configuration
+    _google_client_id: str = None
+    
+    # Admin configuration
+    _admin_emails: List[str] = []
+    
+    @classmethod
+    def register(
+        cls,
+        required_urls: List[str] = None,
+        optional_urls: List[str] = None,
+        public_urls: List[str] = None,
+        jwt_secret: str = None,
+        jwt_algorithm: str = "HS256",
+        jwt_expiry_hours: int = 24,
+        google_client_id: str = None,
+        admin_emails: List[str] = None,
+    ) -> None:
+        """
+        Register auth service configuration.
+        
+        Args:
+            required_urls: URLs that REQUIRE authentication
+            optional_urls: URLs where authentication is optional  
+            public_urls: URLs that don't need authentication
+            jwt_secret: Secret key for JWT signing
+            jwt_algorithm: JWT algorithm (default: HS256)
+            jwt_expiry_hours: Token expiry in hours (default: 24)
+            google_client_id: Google OAuth Client ID
+            admin_emails: List of admin email addresses
+        
+        Raises:
+            RuntimeError: If service is already registered
+            ValueError: If jwt_secret is not provided
+        """
+        if cls._registered:
+            raise RuntimeError(f"{cls.SERVICE_NAME} is already registered")
+        
+        # Validate JWT secret
+        if not jwt_secret:
+            raise ValueError("jwt_secret is required for auth service")
+        
+        # Store route configuration
+        cls._route_config = RouteConfig(
+            required=required_urls or [],
+            optional=optional_urls or [],
+            public=public_urls or [],
+        )
+        
+        # Store JWT configuration
+        cls._jwt_secret = jwt_secret
+        cls._jwt_algorithm = jwt_algorithm
+        cls._jwt_expiry_hours = jwt_expiry_hours
+        
+        # Store Google OAuth configuration
+        cls._google_client_id = google_client_id
+        
+        # Store admin configuration
+        cls._admin_emails = admin_emails or []
+        
+        cls._registered = True
+        
+        logger.info(f"✅ {cls.SERVICE_NAME} registered successfully")
+        logger.info(f"   JWT algorithm: {cls._jwt_algorithm}")
+        logger.info(f"   JWT expiry: {cls._jwt_expiry_hours} hours")
+        logger.info(f"   Required URLs: {len(required_urls or [])}")
+        logger.info(f"   Optional URLs: {len(optional_urls or [])}")
+        logger.info(f"   Public URLs: {len(public_urls or [])}")
+        logger.info(f"   Admin emails: {len(cls._admin_emails)}")
+    
+    @classmethod
+    def get_middleware(cls):
+        """Return AuthMiddleware instance."""
+        from services.auth_service.middleware import AuthMiddleware
+        return AuthMiddleware
+    
+    @classmethod
+    def requires_auth(cls, path: str) -> bool:
+        """Check if a URL path requires authentication."""
+        cls.assert_registered()
+        return cls._route_config.is_required(path)
+    
+    @classmethod
+    def allows_optional_auth(cls, path: str) -> bool:
+        """Check if a URL path allows optional authentication."""
+        cls.assert_registered()
+        return cls._route_config.is_optional(path)
+    
+    @classmethod
+    def is_public(cls, path: str) -> bool:
+        """Check if a URL path is public (no auth needed)."""
+        cls.assert_registered()
+        return cls._route_config.is_public(path)
+    
+    @classmethod
+    def get_jwt_secret(cls) -> str:
+        """Get JWT secret key."""
+        cls.assert_registered()
+        return cls._jwt_secret
+    
+    @classmethod
+    def get_jwt_algorithm(cls) -> str:
+        """Get JWT algorithm."""
+        cls.assert_registered()
+        return cls._jwt_algorithm
+    
+    @classmethod
+    def get_jwt_expiry_hours(cls) -> int:
+        """Get JWT expiry hours."""
+        cls.assert_registered()
+        return cls._jwt_expiry_hours
+    
+    @classmethod
+    def get_google_client_id(cls) -> str:
+        """Get Google OAuth Client ID."""
+        cls.assert_registered()
+        return cls._google_client_id
+    
+    @classmethod
+    def is_admin(cls, email: str) -> bool:
+        """Check if an email is an admin."""
+        cls.assert_registered()
+        return email in cls._admin_emails
+    
+    @classmethod
+    def get_admin_emails(cls) -> List[str]:
+        """Get list of admin emails."""
+        cls.assert_registered()
+        return cls._admin_emails.copy()
+
+
+__all__ = ['AuthServiceConfig']

services/auth_service/google_provider.py

@@ -0,0 +1,232 @@
+"""
+Modular Google OAuth Service
+
+A self-contained, plug-and-play service for verifying Google ID tokens.
+Can be used in any Python application with minimal configuration.
+
+Usage:
+    from services.google_auth_service import GoogleAuthService, GoogleUserInfo
+    
+    # Initialize with client ID
+    auth_service = GoogleAuthService(client_id="your-google-client-id")
+    
+    # Or use environment variable GOOGLE_CLIENT_ID
+    auth_service = GoogleAuthService()
+    
+    # Verify a Google ID token
+    user_info = auth_service.verify_token(id_token)
+    print(user_info.email, user_info.google_id, user_info.name)
+
+Environment Variables:
+    GOOGLE_CLIENT_ID: Your Google OAuth 2.0 Client ID
+
+Dependencies:
+    google-auth>=2.0.0
+    google-auth-oauthlib>=1.0.0
+"""
+
+import os
+import logging
+from dataclasses import dataclass
+from typing import Optional
+from google.oauth2 import id_token as google_id_token
+from google.auth.transport import requests as google_requests
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class GoogleUserInfo:
+    """
+    User information extracted from a verified Google ID token.
+    
+    Attributes:
+        google_id: Unique Google user identifier (sub claim)
+        email: User's email address
+        email_verified: Whether Google has verified the email
+        name: User's display name (may be None)
+        picture: URL to user's profile picture (may be None)
+        given_name: User's first name (may be None)
+        family_name: User's last name (may be None)
+        locale: User's locale preference (may be None)
+    """
+    google_id: str
+    email: str
+    email_verified: bool = True
+    name: Optional[str] = None
+    picture: Optional[str] = None
+    given_name: Optional[str] = None
+    family_name: Optional[str] = None
+    locale: Optional[str] = None
+
+
+class GoogleAuthError(Exception):
+    """Base exception for Google Auth errors."""
+    pass
+
+
+class InvalidTokenError(GoogleAuthError):
+    """Raised when the token is invalid or expired."""
+    pass
+
+
+class ConfigurationError(GoogleAuthError):
+    """Raised when the service is not properly configured."""
+    pass
+
+
+class GoogleAuthService:
+    """
+    Service for verifying Google OAuth ID tokens.
+    
+    This service validates ID tokens issued by Google Sign-In and extracts
+    user information. It's designed to be modular and reusable across
+    different applications.
+    
+    Example:
+        service = GoogleAuthService()
+        try:
+            user_info = service.verify_token(token_from_frontend)
+            print(f"Welcome {user_info.name}!")
+        except InvalidTokenError:
+            print("Invalid or expired token")
+    """
+    
+    def __init__(
+        self,
+        client_id: Optional[str] = None,
+        clock_skew_seconds: int = 0
+    ):
+        """
+        Initialize the Google Auth Service.
+        
+        Args:
+            client_id: Google OAuth 2.0 Client ID. If not provided,
+                      falls back to GOOGLE_CLIENT_ID environment variable.
+            clock_skew_seconds: Allowed clock skew in seconds for token
+                               validation (default: 0).
+        
+        Raises:
+            ConfigurationError: If no client_id is provided or found.
+        """
+        self.client_id = client_id or os.getenv("AUTH_SIGN_IN_GOOGLE_CLIENT_ID")
+        self.clock_skew_seconds = clock_skew_seconds
+        
+        if not self.client_id:
+            raise ConfigurationError(
+                "Google Client ID is required. Either pass client_id parameter "
+                "or set GOOGLE_CLIENT_ID environment variable."
+            )
+        
+        logger.info(f"GoogleAuthService initialized with client_id: {self.client_id[:20]}...")
+    
+    def verify_token(self, id_token: str) -> GoogleUserInfo:
+        """
+        Verify a Google ID token and extract user information.
+        
+        Args:
+            id_token: The ID token received from the frontend after
+                     Google Sign-In.
+        
+        Returns:
+            GoogleUserInfo: Dataclass containing user's Google profile info.
+        
+        Raises:
+            InvalidTokenError: If the token is invalid, expired, or
+                              doesn't match the expected client ID.
+        """
+        if not id_token:
+            raise InvalidTokenError("Token cannot be empty")
+        
+        try:
+            # Verify the token with Google
+            idinfo = google_id_token.verify_oauth2_token(
+                id_token,
+                google_requests.Request(),
+                self.client_id,
+                clock_skew_in_seconds=self.clock_skew_seconds
+            )
+            
+            # Validate issuer
+            if idinfo.get("iss") not in ["accounts.google.com", "https://accounts.google.com"]:
+                raise InvalidTokenError("Invalid token issuer")
+            
+            # Validate audience
+            if idinfo.get("aud") != self.client_id:
+                raise InvalidTokenError("Token was not issued for this application")
+            
+            # Extract user info
+            return GoogleUserInfo(
+                google_id=idinfo["sub"],
+                email=idinfo["email"],
+                email_verified=idinfo.get("email_verified", False),
+                name=idinfo.get("name"),
+                picture=idinfo.get("picture"),
+                given_name=idinfo.get("given_name"),
+                family_name=idinfo.get("family_name"),
+                locale=idinfo.get("locale")
+            )
+            
+        except ValueError as e:
+            logger.warning(f"Token verification failed: {e}")
+            raise InvalidTokenError(f"Token verification failed: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error during token verification: {e}")
+            raise InvalidTokenError(f"Token verification error: {str(e)}")
+    
+    def verify_token_safe(self, id_token: str) -> Optional[GoogleUserInfo]:
+        """
+        Verify a Google ID token without raising exceptions.
+        
+        Useful for cases where you want to check validity without
+        exception handling.
+        
+        Args:
+            id_token: The ID token to verify.
+        
+        Returns:
+            GoogleUserInfo if valid, None if invalid.
+        """
+        try:
+            return self.verify_token(id_token)
+        except GoogleAuthError:
+            return None
+
+
+# Singleton instance for convenience (initialized on first use)
+_default_service: Optional[GoogleAuthService] = None
+
+
+def get_google_auth_service() -> GoogleAuthService:
+    """
+    Get the default GoogleAuthService instance.
+    
+    Creates a singleton instance using environment variables.
+    
+    Returns:
+        GoogleAuthService: The default service instance.
+    
+    Raises:
+        ConfigurationError: If GOOGLE_CLIENT_ID is not set.
+    """
+    global _default_service
+    if _default_service is None:
+        _default_service = GoogleAuthService()
+    return _default_service
+
+
+def verify_google_token(id_token: str) -> GoogleUserInfo:
+    """
+    Convenience function to verify a token using the default service.
+    
+    Args:
+        id_token: The Google ID token to verify.
+    
+    Returns:
+        GoogleUserInfo: Verified user information.
+    
+    Raises:
+        InvalidTokenError: If verification fails.
+        ConfigurationError: If service is not configured.
+    """
+    return get_google_auth_service().verify_token(id_token)

services/auth_service/jwt_provider.py

@@ -0,0 +1,386 @@
+"""
+Modular JWT Service
+
+A self-contained, plug-and-play service for creating and verifying JWT tokens.
+Can be used in any Python application with minimal configuration.
+
+Usage:
+    from services.jwt_service import JWTService, TokenPayload
+    
+    # Initialize with secret key
+    jwt_service = JWTService(secret_key="your-secret-key")
+    
+    # Or use environment variable JWT_SECRET
+    jwt_service = JWTService()
+    
+    # Create a token
+    token = jwt_service.create_token(user_id="user123", email="user@example.com")
+    
+    # Verify a token
+    payload = jwt_service.verify_token(token)
+    print(payload.user_id, payload.email)
+
+Environment Variables:
+    JWT_SECRET: Your secret key for signing tokens (required)
+    JWT_EXPIRY_HOURS: Token expiry in hours (default: 168 = 7 days)
+    JWT_ALGORITHM: Algorithm to use (default: HS256)
+
+Dependencies:
+    PyJWT>=2.8.0
+
+Generate a secure secret:
+    python -c "import secrets; print(secrets.token_urlsafe(64))"
+"""
+
+import os
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Optional, Dict, Any
+import jwt
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TokenPayload:
+    """
+    Payload extracted from a verified JWT token.
+    
+    Attributes:
+        user_id: The user's unique identifier (sub claim)
+        email: The user's email address
+        issued_at: When the token was issued
+        expires_at: When the token expires
+        token_version: Version number for token invalidation
+        extra: Any additional claims in the token
+    """
+    user_id: str
+    email: str
+    issued_at: datetime
+    expires_at: datetime
+    token_version: int = 1
+    extra: Dict[str, Any] = None
+    
+    def __post_init__(self):
+        if self.extra is None:
+            self.extra = {}
+    
+    @property
+    def is_expired(self) -> bool:
+        """Check if the token has expired."""
+        return datetime.utcnow() > self.expires_at
+    
+    @property
+    def time_until_expiry(self) -> timedelta:
+        """Get time remaining until expiry."""
+        return self.expires_at - datetime.utcnow()
+
+
+class JWTError(Exception):
+    """Base exception for JWT errors."""
+    pass
+
+
+class TokenExpiredError(JWTError):
+    """Raised when the token has expired."""
+    pass
+
+
+class InvalidTokenError(JWTError):
+    """Raised when the token is invalid."""
+    pass
+
+
+class ConfigurationError(JWTError):
+    """Raised when the service is not properly configured."""
+    pass
+
+
+class JWTService:
+    """
+    Service for creating and verifying JWT tokens.
+    
+    This service handles JWT token lifecycle for authentication.
+    It's designed to be modular and reusable across different applications.
+    
+    Example:
+        service = JWTService(secret_key="my-secret")
+        
+        # Create token
+        token = service.create_token(user_id="u123", email="a@b.com")
+        
+        # Verify token
+        try:
+            payload = service.verify_token(token)
+            print(f"User: {payload.user_id}")
+        except TokenExpiredError:
+            print("Token expired, please login again")
+        except InvalidTokenError:
+            print("Invalid token")
+    """
+    
+    # Default configuration
+    DEFAULT_ALGORITHM = "HS256"
+    DEFAULT_EXPIRY_HOURS = 168  # 7 days
+    
+    def __init__(
+        self,
+        secret_key: Optional[str] = None,
+        algorithm: Optional[str] = None,
+        expiry_hours: Optional[int] = None
+    ):
+        """
+        Initialize the JWT Service.
+        
+        Args:
+            secret_key: Secret key for signing tokens. If not provided,
+                       falls back to JWT_SECRET environment variable.
+            algorithm: JWT algorithm (default: HS256).
+            expiry_hours: Token expiry in hours (default: 168 = 7 days).
+        
+        Raises:
+            ConfigurationError: If no secret_key is provided or found.
+        """
+        self.secret_key = secret_key or os.getenv("JWT_SECRET")
+        self.algorithm = algorithm or os.getenv("JWT_ALGORITHM", self.DEFAULT_ALGORITHM)
+        self.expiry_hours = expiry_hours or int(
+            os.getenv("JWT_EXPIRY_HOURS", str(self.DEFAULT_EXPIRY_HOURS))
+        )
+        
+        if not self.secret_key:
+            raise ConfigurationError(
+                "JWT secret key is required. Either pass secret_key parameter "
+                "or set JWT_SECRET environment variable. "
+                "Generate one with: python -c \"import secrets; print(secrets.token_urlsafe(64))\""
+            )
+        
+        # Warn if secret is too short
+        if len(self.secret_key) < 32:
+            logger.warning(
+                "JWT secret key is short (< 32 chars). "
+                "Consider using a longer secret for better security."
+            )
+        
+        logger.info(
+            f"JWTService initialized (algorithm={self.algorithm}, "
+            f"expiry={self.expiry_hours}h)"
+        )
+    
+    def create_token(
+        self,
+        user_id: str,
+        email: str,
+        token_version: int = 1,
+        extra_claims: Optional[Dict[str, Any]] = None,
+        expiry_hours: Optional[int] = None
+    ) -> str:
+        """
+        Create a JWT token for a user.
+        
+        Args:
+            user_id: The user's unique identifier.
+            email: The user's email address.
+            token_version: User's current token version for invalidation.
+            extra_claims: Additional claims to include in the token.
+            expiry_hours: Custom expiry for this token (overrides default).
+        
+        Returns:
+            str: The encoded JWT token.
+        """
+        now = datetime.utcnow()
+        expiry = expiry_hours or self.expiry_hours
+        
+        payload = {
+            "sub": user_id,
+            "email": email,
+            "tv": token_version,  # Token version for invalidation
+            "iat": now,
+            "exp": now + timedelta(hours=expiry),
+        }
+        
+        if extra_claims:
+            payload.update(extra_claims)
+        
+        token = jwt.encode(payload, self.secret_key, algorithm=self.algorithm)
+        
+        logger.debug(f"Created token for user_id={user_id} (version={token_version})")
+        return token
+    
+    def verify_token(self, token: str) -> TokenPayload:
+        """
+        Verify a JWT token and extract the payload.
+        
+        Args:
+            token: The JWT token to verify.
+        
+        Returns:
+            TokenPayload: Dataclass containing the verified payload.
+        
+        Raises:
+            TokenExpiredError: If the token has expired.
+            InvalidTokenError: If the token is invalid or malformed.
+        """
+        if not token:
+            raise InvalidTokenError("Token cannot be empty")
+        
+        try:
+            payload = jwt.decode(
+                token,
+                self.secret_key,
+                algorithms=[self.algorithm]
+            )
+            
+            # Extract standard claims
+            user_id = payload.get("sub")
+            email = payload.get("email")
+            token_version = payload.get("tv", 1)  # Default to 1 for backward compatibility
+            iat = payload.get("iat")
+            exp = payload.get("exp")
+            
+            if not user_id or not email:
+                raise InvalidTokenError("Token missing required claims (sub, email)")
+            
+            # Convert timestamps to datetime
+            issued_at = datetime.utcfromtimestamp(iat) if isinstance(iat, (int, float)) else iat
+            expires_at = datetime.utcfromtimestamp(exp) if isinstance(exp, (int, float)) else exp
+            
+            # Extract extra claims
+            standard_claims = {"sub", "email", "tv", "iat", "exp"}
+            extra = {k: v for k, v in payload.items() if k not in standard_claims}
+            
+            return TokenPayload(
+                user_id=user_id,
+                email=email,
+                issued_at=issued_at,
+                expires_at=expires_at,
+                token_version=token_version,
+                extra=extra
+            )
+            
+        except jwt.ExpiredSignatureError:
+            logger.debug("Token verification failed: expired")
+            raise TokenExpiredError("Token has expired")
+        except jwt.InvalidTokenError as e:
+            logger.debug(f"Token verification failed: {e}")
+            raise InvalidTokenError(f"Invalid token: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error during token verification: {e}")
+            raise InvalidTokenError(f"Token verification error: {str(e)}")
+    
+    def verify_token_safe(self, token: str) -> Optional[TokenPayload]:
+        """
+        Verify a JWT token without raising exceptions.
+        
+        Args:
+            token: The JWT token to verify.
+        
+        Returns:
+            TokenPayload if valid, None if invalid or expired.
+        """
+        try:
+            return self.verify_token(token)
+        except JWTError:
+            return None
+    
+    def refresh_token(
+        self,
+        token: str,
+        expiry_hours: Optional[int] = None
+    ) -> str:
+        """
+        Refresh a token by creating a new one with the same claims.
+        
+        Args:
+            token: The current (possibly expired) token.
+            expiry_hours: Custom expiry for the new token.
+        
+        Returns:
+            str: A new JWT token with updated expiry.
+        
+        Raises:
+            InvalidTokenError: If the token is malformed.
+        """
+        try:
+            # Decode without verifying expiry
+            payload = jwt.decode(
+                token,
+                self.secret_key,
+                algorithms=[self.algorithm],
+                options={"verify_exp": False}
+            )
+            
+            user_id = payload.get("sub")
+            email = payload.get("email")
+            
+            if not user_id or not email:
+                raise InvalidTokenError("Token missing required claims")
+            
+            # Preserve extra claims
+            standard_claims = {"sub", "email", "iat", "exp"}
+            extra = {k: v for k, v in payload.items() if k not in standard_claims}
+            
+            return self.create_token(
+                user_id=user_id,
+                email=email,
+                extra_claims=extra,
+                expiry_hours=expiry_hours
+            )
+            
+        except jwt.InvalidTokenError as e:
+            raise InvalidTokenError(f"Cannot refresh invalid token: {str(e)}")
+
+
+# Singleton instance for convenience
+_default_service: Optional[JWTService] = None
+
+
+def get_jwt_service() -> JWTService:
+    """
+    Get the default JWTService instance.
+    
+    Creates a singleton instance using environment variables.
+    
+    Returns:
+        JWTService: The default service instance.
+    
+    Raises:
+        ConfigurationError: If JWT_SECRET is not set.
+    """
+    global _default_service
+    if _default_service is None:
+        _default_service = JWTService()
+    return _default_service
+
+
+def create_access_token(user_id: str, email: str, token_version: int = 1, **kwargs) -> str:
+    """
+    Convenience function to create a token using the default service.
+    
+    Args:
+        user_id: The user's unique identifier.
+        email: The user's email address.
+        token_version: User's current token version for invalidation.
+        **kwargs: Additional arguments passed to create_token.
+    
+    Returns:
+        str: The encoded JWT token.
+    """
+    return get_jwt_service().create_token(user_id, email, token_version, **kwargs)
+
+
+def verify_access_token(token: str) -> TokenPayload:
+    """
+    Convenience function to verify a token using the default service.
+    
+    Args:
+        token: The JWT token to verify.
+    
+    Returns:
+        TokenPayload: Verified token payload.
+    
+    Raises:
+        TokenExpiredError: If the token has expired.
+        InvalidTokenError: If the token is invalid.
+    """
+    return get_jwt_service().verify_token(token)

services/auth_service/middleware.py

@@ -0,0 +1,225 @@
+"""
+Auth Middleware - Request authentication layer
+
+Intercepts requests to validate JWT tokens and attach authenticated
+user to request.state for use in route handlers.
+"""
+
+import logging
+from fastapi import Request, HTTPException, status
+from fastapi.responses import JSONResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from core.database import async_session_maker
+from core.models import User
+from services.auth_service.config import AuthServiceConfig
+from services.auth_service.jwt_provider import (
+    verify_access_token,
+    TokenExpiredError,
+    InvalidTokenError,
+    JWTError,
+)
+from services.base_service.middleware_chain import (
+    BaseServiceMiddleware,
+    get_request_context,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AuthMiddleware(BaseServiceMiddleware):
+    """
+    Authentication middleware for request validation.
+    
+    Flow:
+    1. Check if route requires/allows auth based on URL
+    2. Extract Authorization header
+    3. Verify JWT token
+    4. Load user from database
+    5. Attach user to request.state.user
+    6. Continue to next middleware/route
+    
+    Public routes skip all auth checks.
+    Required routes must have valid auth or return 401.
+    Optional routes attach user if auth is provided, but don't fail if missing.
+    """
+    
+    SERVICE_NAME = "auth"
+    
+    async def dispatch(self, request: Request, call_next):
+        """Process request through auth middleware."""
+        # Skip OPTIONS requests (CORS preflight)
+        if request.method == "OPTIONS":
+            return await call_next(request)
+        
+        # Initialize request context
+        ctx = get_request_context(request)
+        
+        # Get path and method from request
+        path = request.url.path
+        
+        # Check if route is public (skip all auth)
+        if AuthServiceConfig.is_public(path):
+            self.log_request(request, "Public route, skipping auth")
+            request.state.user = None
+            ctx.user = None
+            ctx.is_authenticated = False
+            response = await call_next(request)
+            return response
+        
+        # Check if route requires auth or allows optional auth
+        requires_auth = AuthServiceConfig.requires_auth(path)
+        allows_optional = AuthServiceConfig.allows_optional_auth(path)
+        
+        # If route doesn't require auth and doesn't allow optional, skip
+        if not requires_auth and not allows_optional:
+            self.log_request(request, "Route not configured for auth, skipping")
+            request.state.user = None
+            ctx.user = None
+            ctx.is_authenticated = False
+            response = await call_next(request)
+            return response
+        
+        # Extract Authorization header
+        auth_header = request.headers.get("Authorization")
+        
+        # If no auth header
+        if not auth_header:
+            if requires_auth:
+                self.log_request(request, "Missing Authorization header (required)")
+                return JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={"detail": "Missing Authorization header"},
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            else:
+                # Optional auth, no header provided
+                self.log_request(request, "No auth header (optional route)")
+                request.state.user = None
+                ctx.user = None
+                ctx.is_authenticated = False
+                response = await call_next(request)
+                return response
+        
+        # Validate Authorization header format
+        if not auth_header.startswith("Bearer "):
+            if requires_auth:
+                self.log_request(request, "Invalid Authorization header format")
+                return JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={"detail": "Invalid Authorization header format. Use: Bearer <token>"},
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            else:
+                # Optional auth, invalid format
+                request.state.user = None
+                ctx.user = None
+                ctx.is_authenticated = False
+                response = await call_next(request)
+                return response
+        
+        # Extract token
+        token = auth_header.split(" ", 1)[1]
+        
+        # Verify token
+        try:
+            payload = verify_access_token(token)
+        except TokenExpiredError:
+            if requires_auth:
+                self.log_request(request, "Token expired")
+                return JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={"detail": "Token has expired. Please sign in again."},
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            else:
+                # Optional auth, expired token
+                request.state.user = None
+                ctx.user = None
+                ctx.is_authenticated = False
+                response = await call_next(request)
+                return response
+        except (InvalidTokenError, JWTError) as e:
+            if requires_auth:
+                self.log_error(request, f"Token verification failed: {e}")
+                return JSONResponse(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    content={"detail": f"Invalid token: {str(e)}"},
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            else:
+                # Optional auth, invalid token
+                request.state.user = None
+                ctx.user = None
+                ctx.is_authenticated = False
+                response = await call_next(request)
+                return response
+        
+        # Get database session
+        async with async_session_maker() as db:
+            try:
+                # Load user from database
+                query = select(User).where(
+                    User.user_id == payload.user_id,
+                    User.is_active == True
+                )
+                result = await db.execute(query)
+                user = result.scalar_one_or_none()
+                
+                if not user:
+                    if requires_auth:
+                        self.log_request(request, "User not found or inactive")
+                        return JSONResponse(
+                            status_code=status.HTTP_401_UNAUTHORIZED,
+                            content={"detail": "User not found or inactive"},
+                        )
+                    else:
+                        # Optional auth, user not found
+                        request.state.user = None
+                        ctx.user = None
+                        ctx.is_authenticated = False
+                        response = await call_next(request)
+                        return response
+                
+                # Validate token version
+                if payload.token_version < user.token_version:
+                    if requires_auth:
+                        self.log_request(
+                            request,
+                            f"Token invalidated (version {payload.token_version} < {user.token_version})"
+                        )
+                        return JSONResponse(
+                            status_code=status.HTTP_401_UNAUTHORIZED,
+                            content={"detail": "Token has been invalidated. Please sign in again."},
+                            headers={"WWW-Authenticate": "Bearer"},
+                        )
+                    else:
+                        # Optional auth, invalidated token
+                        request.state.user = None
+                        ctx.user = None
+                        ctx.is_authenticated = False
+                        response = await call_next(request)
+                        return response
+                
+                # Attach user to request state
+                request.state.user = user
+                ctx.set_user(user)
+                
+                # Check if user is admin
+                is_admin = AuthServiceConfig.is_admin(user.email)
+                request.state.is_admin = is_admin
+                ctx.set_flag('is_admin', is_admin)
+                
+                self.log_request(request, f"Authenticated user: {user.user_id}")
+                
+                # Continue to next middleware/route
+                response = await call_next(request)
+                return response
+            
+            finally:
+                await db.close()
+
+
+__all__ = ['AuthMiddleware']

services/base_service/__init__.py

@@ -0,0 +1,246 @@
+"""
+Base Service Infrastructure
+
+Provides the foundation for plug-and-play services in the API gateway.
+All services (auth, credit, gemini, etc.) extend this base infrastructure.
+
+Core Components:
+- BaseService: Abstract base class for all services
+- ServiceConfig: Configuration container
+- ServiceRegistry: Global registry for service discovery
+- MiddlewareProtocol: Type definition for middleware functions
+
+Usage:
+    class MyService(BaseService):
+        @classmethod
+        def register(cls, **config):
+            # Service-specific registration
+            pass
+        
+        @classmethod
+        def get_middleware(cls):
+            # Return middleware function if needed
+            return MyMiddleware()
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, Type, Optional, Callable, Any
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class ServiceConfig:
+    """
+    Base configuration container for services.
+    
+    Services can extend this to add their specific configuration.
+    """
+    
+    def __init__(self, **kwargs):
+        """Initialize configuration with arbitrary key-value pairs."""
+        self._config = kwargs
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get configuration value."""
+        return self._config.get(key, default)
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set configuration value."""
+        self._config[key] = value
+    
+    def __getitem__(self, key: str) -> Any:
+        """Dictionary-style access."""
+        return self._config[key]
+    
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Dictionary-style assignment."""
+        self._config[key] = value
+    
+    def __contains__(self, key: str) -> bool:
+        """Check if key exists."""
+        return key in self._config
+
+
+class BaseService(ABC):
+    """
+    Abstract base class for all plug-and-play services.
+    
+    Services must implement:
+    - register(): Register service configuration at startup
+    - get_middleware(): Return middleware if service needs request interception
+    - on_shutdown(): Cleanup on app shutdown
+    """
+    
+    # Service name (override in subclass)
+    SERVICE_NAME: str = "base_service"
+    
+    # Service configuration
+    _config: Optional[ServiceConfig] = None
+    
+    # Registration state
+    _registered: bool = False
+    
+    @classmethod
+    @abstractmethod
+    def register(cls, **config) -> None:
+        """
+        Register service configuration at application startup.
+        
+        Args:
+            **config: Service-specific configuration parameters
+        
+        Raises:
+            RuntimeError: If service is already registered
+        """
+        if cls._registered:
+            raise RuntimeError(f"{cls.SERVICE_NAME} is already registered")
+        
+        cls._config = ServiceConfig(**config)
+        cls._registered = True
+        
+        logger.info(f"✅ {cls.SERVICE_NAME} registered successfully")
+    
+    @classmethod
+    def get_middleware(cls) -> Optional[BaseHTTPMiddleware]:
+        """
+        Return middleware instance if service needs request interception.
+        
+        Returns:
+            Middleware instance or None if service doesn't need middleware
+        """
+        return None
+    
+    @classmethod
+    def on_shutdown(cls) -> None:
+        """
+        Cleanup hook called during application shutdown.
+        
+        Override this to perform cleanup (close connections, save state, etc.)
+        """
+        pass
+    
+    @classmethod
+    def is_registered(cls) -> bool:
+        """Check if service has been registered."""
+        return cls._registered
+    
+    @classmethod
+    def assert_registered(cls) -> None:
+        """
+        Assert that service has been registered.
+        
+        Raises:
+            RuntimeError: If service is not registered
+        """
+        if not cls._registered:
+            raise RuntimeError(
+                f"{cls.SERVICE_NAME} is not registered. "
+                f"Call {cls.SERVICE_NAME}.register() at application startup."
+            )
+    
+    @classmethod
+    def get_config(cls) -> ServiceConfig:
+        """
+        Get service configuration.
+        
+        Returns:
+            ServiceConfig instance
+        
+        Raises:
+            RuntimeError: If service is not registered
+        """
+        cls.assert_registered()
+        return cls._config
+
+
+class ServiceRegistry:
+    """
+    Global registry for service discovery and management.
+    
+    Tracks all registered services and provides lookup functionality.
+    """
+    
+    _services: Dict[str, Type[BaseService]] = {}
+    
+    @classmethod
+    def register_service(cls, service_class: Type[BaseService]) -> None:
+        """
+        Register a service class in the global registry.
+        
+        Args:
+            service_class: Service class to register
+        """
+        service_name = service_class.SERVICE_NAME
+        
+        if service_name in cls._services:
+            logger.warning(f"Service '{service_name}' already registered, overwriting")
+        
+        cls._services[service_name] = service_class
+        logger.debug(f"Registered service: {service_name}")
+    
+    @classmethod
+    def get_service(cls, service_name: str) -> Optional[Type[BaseService]]:
+        """
+        Get a service class by name.
+        
+        Args:
+            service_name: Name of the service to retrieve
+        
+        Returns:
+            Service class or None if not found
+        """
+        return cls._services.get(service_name)
+    
+    @classmethod
+    def get_all_services(cls) -> Dict[str, Type[BaseService]]:
+        """
+        Get all registered services.
+        
+        Returns:
+            Dictionary mapping service names to service classes
+        """
+        return cls._services.copy()
+    
+    @classmethod
+    def get_all_middleware(cls) -> list:
+        """
+        Get middleware from all registered services.
+        
+        Returns:
+            List of middleware instances in registration order
+        """
+        middleware_list = []
+        
+        for service_name, service_class in cls._services.items():
+            if service_class.is_registered():
+                middleware = service_class.get_middleware()
+                if middleware:
+                    middleware_list.append(middleware)
+                    logger.debug(f"Added middleware from service: {service_name}")
+        
+        return middleware_list
+    
+    @classmethod
+    def shutdown_all(cls) -> None:
+        """
+        Call shutdown hooks for all registered services.
+        """
+        logger.info("Shutting down all services...")
+        
+        for service_name, service_class in cls._services.items():
+            try:
+                service_class.on_shutdown()
+                logger.debug(f"Shutdown complete: {service_name}")
+            except Exception as e:
+                logger.error(f"Error shutting down {service_name}: {e}")
+        
+        logger.info("All services shut down")
+
+
+__all__ = [
+    'BaseService',
+    'ServiceConfig',
+    'ServiceRegistry',
+]

services/base_service/middleware_chain.py

@@ -0,0 +1,212 @@
+"""
+Middleware Chain - Orchestration of multiple middleware layers.
+
+Provides utilities for managing and coordinating multiple middleware
+components in the request/response flow.
+
+Usage:
+    # In app.py
+    from services.base_service import MiddlewareChain
+    
+    # Add middleware in reverse order (last added = first executed)
+    app.add_middleware(CreditMiddleware)
+    app.add_middleware(AuthMiddleware)
+    
+    # Or use the chain helper
+    chain = MiddlewareChain()
+    chain.add(AuthMiddleware)
+    chain.add(CreditMiddleware)
+    chain.apply_to_app(app)
+"""
+
+import logging
+from typing import List, Type, Callable
+from starlette.middleware.base import BaseHTTPMiddleware
+from fastapi import FastAPI, Request, Response
+
+logger = logging.getLogger(__name__)
+
+
+class RequestContext:
+    """
+    Shared context for passing data between middleware layers.
+    
+    Attached to request.state for access across middleware and routers.
+    """
+    
+    def __init__(self):
+        """Initialize empty context."""
+        # Auth layer
+        self.user = None
+        self.is_authenticated = False
+        
+        # Credit layer
+        self.credits_reserved = 0
+        self.credit_cost = 0
+        
+        # General
+        self.start_time = None
+        self.service_flags = {}
+    
+    def set_user(self, user) -> None:
+        """Set authenticated user."""
+        self.user = user
+        self.is_authenticated = True
+    
+    def set_credits(self, reserved: int, cost: int) -> None:
+        """Set credit information."""
+        self.credits_reserved = reserved
+        self.credit_cost = cost
+    
+    def set_flag(self, key: str, value: any) -> None:
+        """Set a service-specific flag."""
+        self.service_flags[key] = value
+    
+    def get_flag(self, key: str, default=None) -> any:
+        """Get a service-specific flag."""
+        return self.service_flags.get(key, default)
+
+
+class MiddlewareChain:
+    """
+    Helper for managing middleware registration order.
+    
+    FastAPI/Starlette middleware executes in REVERSE order of registration,
+    so the LAST middleware added is the FIRST to execute.
+    
+    This class helps manage the order explicitly.
+    """
+    
+    def __init__(self):
+        """Initialize empty middleware chain."""
+        self._middleware: List[Type[BaseHTTPMiddleware]] = []
+    
+    def add(self, middleware_class: Type[BaseHTTPMiddleware], **kwargs) -> 'MiddlewareChain':
+        """
+        Add middleware to the chain.
+        
+        Middleware is added to the END of the list, but will be registered
+        in REVERSE order (so first added = first executed).
+        
+        Args:
+            middleware_class: Middleware class to add
+            **kwargs: Arguments to pass to middleware constructor
+        
+        Returns:
+            Self for chaining
+        """
+        self._middleware.append((middleware_class, kwargs))
+        logger.debug(f"Added middleware to chain: {middleware_class.__name__}")
+        return self
+    
+    def apply_to_app(self, app: FastAPI) -> None:
+        """
+        Apply all middleware to the FastAPI app in correct order.
+        
+        Middleware is registered in REVERSE order so that the first
+        middleware added to the chain is the first to execute.
+        
+        Args:
+            app: FastAPI application instance
+        """
+        # Reverse the list so first added = first executed
+        for middleware_class, kwargs in reversed(self._middleware):
+            app.add_middleware(middleware_class, **kwargs)
+            logger.info(f"Registered middleware: {middleware_class.__name__}")
+    
+    def get_middleware_list(self) -> List[Type[BaseHTTPMiddleware]]:
+        """
+        Get the list of middleware in execution order.
+        
+        Returns:
+            List of middleware classes in the order they will execute
+        """
+        return [m[0] for m in self._middleware]
+    
+    def __len__(self) -> int:
+        """Get number of middleware in chain."""
+        return len(self._middleware)
+    
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        middleware_names = [m[0].__name__ for m in self._middleware]
+        return f"MiddlewareChain({middleware_names})"
+
+
+async def initialize_request_context(request: Request) -> None:
+    """
+    Initialize request context for middleware to use.
+    
+    This should be called early in the middleware chain to ensure
+    request.state.ctx is available.
+    
+    Usage:
+        class MyMiddleware(BaseHTTPMiddleware):
+            async def dispatch(self, request: Request, call_next):
+                await initialize_request_context(request)
+                # Now request.state.ctx is available
+                ...
+    """
+    if not hasattr(request.state, "ctx"):
+        request.state.ctx = RequestContext()
+
+
+def get_request_context(request: Request) -> RequestContext:
+    """
+    Get request context from request.state.
+    
+    Creates context if it doesn't exist.
+    
+    Args:
+        request: FastAPI request object
+    
+    Returns:
+        RequestContext instance
+    """
+    if not hasattr(request.state, "ctx"):
+        request.state.ctx = RequestContext()
+    return request.state.ctx
+
+
+class BaseServiceMiddleware(BaseHTTPMiddleware):
+    """
+    Base class for service middleware.
+    
+    Provides common functionality for all service middleware:
+    - Request context initialization
+    - Error handling
+    - Logging
+    """
+    
+    SERVICE_NAME = "base"
+    
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """
+        Process request through middleware.
+        
+        Override this in subclasses to implement service-specific logic.
+        """
+        # Initialize context
+        await initialize_request_context(request)
+        
+        # Call next middleware/route
+        response = await call_next(request)
+        
+        return response
+    
+    def log_request(self, request: Request, message: str) -> None:
+        """Log request with service context."""
+        logger.info(f"[{self.SERVICE_NAME}] {request.method} {request.url.path} - {message}")
+    
+    def log_error(self, request: Request, error: str) -> None:
+        """Log error with service context."""
+        logger.error(f"[{self.SERVICE_NAME}] {request.method} {request.url.path} - ERROR: {error}")
+
+
+__all__ = [
+    'MiddlewareChain',
+    'RequestContext',
+    'BaseServiceMiddleware',
+    'initialize_request_context',
+    'get_request_context',
+]

services/base_service/route_matcher.py

@@ -0,0 +1,254 @@
+"""
+Route Matcher - URL pattern matching for service configuration.
+
+Provides flexible URL matching capabilities for services to define
+which routes require auth, credits, etc.
+
+Supported patterns:
+- Exact match: "/api/users"
+- Prefix match: "/api/*" (matches /api/anything)
+- Wildcard match: "/api/users/*/posts" (matches /api/users/123/posts)
+- Deep wildcard: "/api/**" (matches /api/users/123/posts/456)
+- Regex match: "^/api/v[0-9]+/.*$"
+
+Usage:
+    matcher = RouteMatcher(["/api/*", "/admin/**"])
+    
+    if matcher.matches("/api/users"):
+        # Route requires auth
+        pass
+"""
+
+import re
+import logging
+from typing import List, Set, Optional, Pattern
+from fnmatch import fnmatch
+
+logger = logging.getLogger(__name__)
+
+
+class RouteMatcher:
+    """
+    Flexible URL pattern matcher for route configuration.
+    
+    Supports exact matches, glob patterns, and regex patterns.
+    """
+    
+    def __init__(self, patterns: List[str]):
+        """
+        Initialize route matcher with patterns.
+        
+        Args:
+            patterns: List of URL patterns to match
+        """
+        self.patterns = patterns
+        self._exact_matches: Set[str] = set()
+        self._prefix_patterns: List[str] = []
+        self._glob_patterns: List[str] = []
+        self._regex_patterns: List[Pattern] = []
+        
+        # Classify patterns for performance
+        self._classify_patterns()
+    
+    def _classify_patterns(self) -> None:
+        """
+        Classify patterns by type for optimal matching performance.
+        
+        Order of matching:
+        1. Exact matches (fastest - O(1))
+        2. Prefix patterns (fast - string startswith)
+        3. Glob patterns (medium - fnmatch)
+        4. Regex patterns (slowest - regex matching)
+        """
+        for pattern in self.patterns:
+            # Empty pattern
+            if not pattern:
+                continue
+            
+            # Regex pattern (starts with ^)
+            if pattern.startswith("^"):
+                try:
+                    compiled = re.compile(pattern)
+                    self._regex_patterns.append(compiled)
+                    logger.debug(f"Classified as regex: {pattern}")
+                except re.error as e:
+                    logger.warning(f"Invalid regex pattern '{pattern}': {e}")
+                continue
+            
+            # Glob pattern (contains * or ?)
+            if "*" in pattern or "?" in pattern:
+                # Simple prefix wildcard: /api/*
+                if pattern.endswith("/*") and "*" not in pattern[:-2]:
+                    prefix = pattern[:-2]  # Remove /*
+                    self._prefix_patterns.append(prefix)
+                    logger.debug(f"Classified as prefix: {prefix}")
+                else:
+                    # Complex glob: /api/*/users or /api/**
+                    self._glob_patterns.append(pattern)
+                    logger.debug(f"Classified as glob: {pattern}")
+                continue
+            
+            # Exact match
+            self._exact_matches.add(pattern)
+            logger.debug(f"Classified as exact: {pattern}")
+    
+    def matches(self, path: str) -> bool:
+        """
+        Check if a URL path matches any configured pattern.
+        
+        Args:
+            path: URL path to check (e.g., "/api/users/123")
+        
+        Returns:
+            True if path matches any pattern, False otherwise
+        """
+        # Strip query parameters and fragments
+        path = path.split("?")[0].split("#")[0]
+        
+        # Normalize path (remove trailing slash unless it's just "/")
+        if path != "/" and path.endswith("/"):
+            path = path.rstrip("/")
+        
+        # 1. Exact match (O(1))
+        if path in self._exact_matches:
+            return True
+        
+        # 2. Prefix match (O(n) but fast)
+        for prefix in self._prefix_patterns:
+            if path.startswith(prefix + "/") or path == prefix:
+                return True
+        
+        # 3. Glob match (O(n))
+        for pattern in self._glob_patterns:
+            if fnmatch(path, pattern):
+                return True
+        
+        # 4. Regex match (O(n) but slower)
+        for regex in self._regex_patterns:
+            if regex.match(path):
+                return True
+        
+        return False
+    
+    def get_matching_pattern(self, path: str) -> Optional[str]:
+        """
+        Get the first pattern that matches the given path.
+        
+        Useful for debugging or determining which rule matched.
+        
+        Args:
+            path: URL path to check
+        
+        Returns:
+            Matching pattern string or None
+        """
+        # Strip query parameters and fragments
+        path = path.split("?")[0].split("#")[0]
+        
+        # Normalize path
+        if path != "/" and path.endswith("/"):
+            path = path.rstrip("/")
+        
+        # Exact match
+        if path in self._exact_matches:
+            return path
+        
+        # Prefix match
+        for prefix in self._prefix_patterns:
+            if path.startswith(prefix + "/") or path == prefix:
+                return prefix + "/*"
+        
+        # Glob match
+        for pattern in self._glob_patterns:
+            if fnmatch(path, pattern):
+                return pattern
+        
+        # Regex match
+        for regex in self._regex_patterns:
+            if regex.match(path):
+                return regex.pattern
+        
+        return None
+    
+    def __repr__(self) -> str:
+        """String representation for debugging."""
+        return (
+            f"RouteMatcher("
+            f"exact={len(self._exact_matches)}, "
+            f"prefix={len(self._prefix_patterns)}, "
+            f"glob={len(self._glob_patterns)}, "
+            f"regex={len(self._regex_patterns)})"
+        )
+
+
+class RouteConfig:
+    """
+    Route configuration helper for services.
+    
+    Manages multiple route lists (required, optional, public) with
+    precedence and exclusion logic.
+    """
+    
+    def __init__(
+        self,
+        required: List[str] = None,
+        optional: List[str] = None,
+        public: List[str] = None,
+    ):
+        """
+        Initialize route configuration.
+        
+        Args:
+            required: Routes that REQUIRE the service (e.g., auth required)
+            optional: Routes where service is OPTIONAL (e.g., auth optional)
+            public: Routes that are PUBLIC (e.g., no auth needed)
+        
+        Precedence: public > required > optional (for conflict resolution)
+        """
+        self.required_matcher = RouteMatcher(required or [])
+        self.optional_matcher = RouteMatcher(optional or [])
+        self.public_matcher = RouteMatcher(public or [])
+    
+    def is_required(self, path: str) -> bool:
+        """
+        Check if service is REQUIRED for this path.
+        
+        Returns False if path is public (public takes precedence).
+        """
+        if self.is_public(path):
+            return False
+        return self.required_matcher.matches(path)
+    
+    def is_optional(self, path: str) -> bool:
+        """
+        Check if service is OPTIONAL for this path.
+        
+        Returns False if path is public or required.
+        """
+        if self.is_public(path):
+            return False
+        if self.required_matcher.matches(path):
+            return False
+        return self.optional_matcher.matches(path)
+    
+    def is_public(self, path: str) -> bool:
+        """
+        Check if path is PUBLIC (service not needed).
+        
+        Public takes highest precedence.
+        """
+        return self.public_matcher.matches(path)
+    
+    def requires_service(self, path: str) -> bool:
+        """
+        Check if service is needed (required OR optional) for this path.
+        
+        Returns False if path is not matched by any configuration.
+        """
+        return self.is_required(path) or self.is_optional(path)
+
+
+__all__ = [
+    'RouteMatcher',
+    'RouteConfig',
+]

services/credit_service/__init__.py

@@ -0,0 +1,76 @@
+"""
+Credit Service - Credit validation middleware for API Gateway
+
+Provides plug-and-play credit management with:
+- Per-route cost configuration
+- Credit reservation and validation
+- Request middleware for credit checks
+- Automatic refund on errors
+
+Usage:
+    # In app.py startup
+    from services.credit_service import register_credit_service
+    
+    register_credit_service(
+        route_costs={
+            "/gemini/generate-animation-prompt": 1,
+            "/gemini/edit-image": 1,
+            "/gemini/generate-video": 10,
+            "/gemini/generate-text": 1,
+            "/gemini/analyze-image": 1,
+        }
+    )
+    
+    # In routers
+    from fastapi import Request
+    
+    @router.post("/api/endpoint")
+    async def endpoint(request: Request):
+        user = request.state.user  # From AuthMiddleware
+        credits_reserved = request.state.credits_reserved  # From CreditMiddleware
+        return {"credits_remaining": user.credits}
+"""
+
+from services.credit_service.config import CreditServiceConfig
+from services.credit_service.middleware import CreditMiddleware
+from services.credit_service.credit_manager import (
+    reserve_credit,
+    confirm_credit,
+    refund_credit,
+    handle_job_completion,
+    is_refundable_error,
+    REFUNDABLE_ERROR_PATTERNS,
+    NON_REFUNDABLE_ERROR_PATTERNS,
+)
+
+
+def register_credit_service(
+    route_costs: dict = None,
+) -> None:
+    """
+    Register the credit service with application configuration.
+    
+    Args:
+        route_costs: Dictionary mapping route paths to credit costs
+                    Example: {"/gemini/generate-video": 10, "/gemini/edit-image": 1}
+    """
+    CreditServiceConfig.register(
+        route_costs=route_costs or {},
+    )
+
+
+__all__ = [
+    # Registration
+    'register_credit_service',
+    'CreditServiceConfig',
+    'CreditMiddleware',
+    
+    # Credit Management
+    'reserve_credit',
+    'confirm_credit',
+    'refund_credit',
+    'handle_job_completion',
+    'is_refundable_error',
+    'REFUNDABLE_ERROR_PATTERNS',
+    'NON_REFUNDABLE_ERROR_PATTERNS',
+]

services/credit_service/config.py

@@ -0,0 +1,87 @@
+"""
+Credit Service Configuration
+
+Manages credit cost configuration for API routes.
+"""
+
+import logging
+from typing import Dict
+from services.base_service import BaseService
+
+logger = logging.getLogger(__name__)
+
+
+class CreditServiceConfig(BaseService):
+    """
+    Configuration for the credit service.
+    
+    Controls which routes require credits and how much they cost.
+    """
+    
+    SERVICE_NAME = "credit_service"
+    
+    # Route cost configuration
+    _route_costs: Dict[str, int] = {}
+    
+    @classmethod
+    def register(
+        cls,
+        route_costs: Dict[str, int] = None,
+    ) -> None:
+        """
+        Register credit service configuration.
+        
+        Args:
+            route_costs: Dictionary mapping route paths to credit costs
+                        Example: {"/gemini/generate-video": 10, "/gemini/edit-image": 1}
+        
+        Raises:
+            RuntimeError: If service is already registered
+        """
+        if cls._registered:
+            raise RuntimeError(f"{cls.SERVICE_NAME} is already registered")
+        
+        # Store route costs
+        cls._route_costs = route_costs or {}
+        
+        cls._registered = True
+        
+        logger.info(f"✅ {cls.SERVICE_NAME} registered successfully")
+        logger.info(f"   Routes with credit costs: {len(cls._route_costs)}")
+        for route, cost in cls._route_costs.items():
+            logger.info(f"     {route}: {cost} credits")
+    
+    @classmethod
+    def get_middleware(cls):
+        """Return CreditMiddleware instance."""
+        from services.credit_service.middleware import CreditMiddleware
+        return CreditMiddleware
+    
+    @classmethod
+    def get_cost(cls, path: str) -> int:
+        """
+        Get the credit cost for a given path.
+        
+        Args:
+            path: URL path to check
+            
+        Returns:
+            Credit cost (0 if route doesn't require credits)
+        """
+        cls.assert_registered()
+        return cls._route_costs.get(path, 0)
+    
+    @classmethod
+    def requires_credits(cls, path: str) -> bool:
+        """Check if a URL path requires credits."""
+        cls.assert_registered()
+        return cls.get_cost(path) > 0
+    
+    @classmethod
+    def get_all_costs(cls) -> Dict[str, int]:
+        """Get all route costs."""
+        cls.assert_registered()
+        return cls._route_costs.copy()
+
+
+__all__ = ['CreditServiceConfig']

services/credit_service/credit_manager.py

@@ -0,0 +1,257 @@
+"""
+Credit Service - Manages credit reservation, confirmation, and refunding.
+
+Implements the Credit Reservation Pattern:
+1. Reserve credits when job is created (deduct from user, track in job)
+2. Confirm credits only on successful completion
+3. Refund credits on refundable errors (server-side issues)
+4. Keep credits on non-refundable errors (user-caused issues)
+"""
+import logging
+from typing import Optional
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Error Categories for Refund Decisions
+# =============================================================================
+
+# Refundable errors - User gets credits back (server/API issues)
+REFUNDABLE_ERROR_PATTERNS = [
+    "API_KEY_INVALID",
+    "QUOTA_EXCEEDED",
+    "INTERNAL_ERROR", 
+    "CONNECTION_FAILED",
+    "SERVER_SHUTDOWN",
+    "TIMEOUT",
+    "Server Authentication Error",
+    "Network error",
+    "Connection refused",
+    "Connection reset",
+    "Service unavailable",
+    "503",
+    "500",
+    "429",  # Rate limit (our quota, not user's fault)
+]
+
+# Non-refundable error patterns - User's input/content issue
+NON_REFUNDABLE_ERROR_PATTERNS = [
+    "safety",
+    "blocked",
+    "SAFETY_FILTER",
+    "INVALID_INPUT",
+    "Invalid image",
+    "Bad request",
+    "400",
+    "cancelled",
+    "User cancelled",
+]
+
+
+def is_refundable_error(error_message: Optional[str]) -> bool:
+    """
+    Determine if an error should result in a credit refund.
+    
+    Args:
+        error_message: The error message from the failed job
+        
+    Returns:
+        True if the error is refundable (server/API issue)
+        False if non-refundable (user's fault) or no error message
+    """
+    if not error_message:
+        return False
+    
+    error_lower = error_message.lower()
+    
+    # Check for REFUNDABLE patterns FIRST (specific server errors take precedence)
+    # This ensures API_KEY_INVALID is caught before generic "400" matcher
+    for pattern in REFUNDABLE_ERROR_PATTERNS:
+        if pattern.lower() in error_lower:
+            logger.debug(f"Error matched refundable pattern '{pattern}': {error_message[:100]}")
+            return True
+    
+    # Check for non-refundable patterns (user-caused issues)
+    for pattern in NON_REFUNDABLE_ERROR_PATTERNS:
+        if pattern.lower() in error_lower:
+            logger.debug(f"Error matched non-refundable pattern '{pattern}': {error_message[:100]}")
+            return False
+    
+    # Default: Max retries exceeded is refundable (we consumed API resources trying)
+    if "max retries" in error_lower:
+        return True
+    
+    # Default: Unknown errors are NOT refundable to prevent abuse
+    # If it's an unknown error, it's more likely user-caused
+    logger.debug(f"Unknown error (not refundable): {error_message[:100]}")
+    return False
+
+
+async def reserve_credit(session: AsyncSession, user, amount: int = 1) -> bool:
+    """
+    Reserve credits for a job (deduct from user's balance).
+    
+    The credits are deducted but tracked in the job's credits_reserved field.
+    If the job fails with a refundable error, they can be restored.
+    
+    Args:
+        session: Database session
+        user: User model instance
+        amount: Number of credits to reserve (default: 1)
+        
+    Returns:
+        True if credits were successfully reserved
+        False if user has insufficient credits
+    """
+    if user.credits < amount:
+        logger.warning(f"User {user.user_id} has insufficient credits ({user.credits}) to reserve {amount}")
+        return False
+    
+    user.credits -= amount
+    logger.info(f"Reserved {amount} credit(s) for user {user.user_id}. Remaining: {user.credits}")
+    # Note: Don't commit here - let caller handle transaction
+    return True
+
+
+async def confirm_credit(session: AsyncSession, job) -> None:
+    """
+    Confirm that credits were legitimately used for a completed job.
+    
+    This is called when a job completes successfully. The credits stay
+    deducted (they were already deducted during reservation).
+    
+    Args:
+        session: Database session
+        job: GeminiJob model instance
+    """
+    if job.credits_reserved > 0:
+        # Credits were used - clear the reservation tracking
+        credits_used = job.credits_reserved
+        job.credits_reserved = 0
+        logger.info(f"Confirmed {credits_used} credit(s) used for job {job.job_id}")
+    # Note: Don't commit here - let caller handle transaction
+
+
+async def refund_credit(session: AsyncSession, job, reason: str) -> bool:
+    """
+    Refund reserved credits back to the user.
+    
+    Called when a job fails due to a refundable error (server-side issue).
+    
+    Args:
+        session: Database session  
+        job: GeminiJob model instance
+        reason: Reason for the refund (for logging)
+        
+    Returns:
+        True if credits were refunded
+        False if no credits to refund or already refunded
+    """
+    if job.credits_reserved <= 0:
+        logger.debug(f"Job {job.job_id} has no credits to refund")
+        return False
+    
+    if job.credits_refunded:
+        logger.warning(f"Job {job.job_id} was already refunded")
+        return False
+    
+    # Get the user to restore credits
+    from core.models import User
+    
+    result = await session.execute(
+        select(User).where(User.id == job.user_id)
+    )
+    user = result.scalar_one_or_none()
+    
+    if not user:
+        logger.error(f"Cannot refund job {job.job_id}: User {job.user_id} not found")
+        return False
+    
+    # Restore credits
+    credits_to_refund = job.credits_reserved
+    user.credits += credits_to_refund
+    job.credits_reserved = 0
+    job.credits_refunded = True
+    
+    logger.info(
+        f"Refunded {credits_to_refund} credit(s) to user {user.user_id} for job {job.job_id}. "
+        f"Reason: {reason[:100]}. New balance: {user.credits}"
+    )
+    
+    # Note: Don't commit here - let caller handle transaction
+    return True
+
+
+async def handle_job_completion(session: AsyncSession, job) -> None:
+    """
+    Handle credit finalization when a job completes or fails.
+    
+    This is the main entry point called by the job worker.
+    
+    Args:
+        session: Database session
+        job: GeminiJob model instance with final status
+    """
+    if job.status == "completed":
+        # Success - confirm credits were used
+        await confirm_credit(session, job)
+        
+    elif job.status == "failed":
+        # Failure - check if refundable
+        if is_refundable_error(job.error_message):
+            await refund_credit(session, job, job.error_message or "Unknown error")
+        else:
+            # Non-refundable - confirm credits were used (user's fault)
+            await confirm_credit(session, job)
+            logger.info(f"Job {job.job_id} failed with non-refundable error, credits kept")
+            
+    elif job.status == "cancelled":
+        # Cancelled jobs get refunds only if they were never started
+        if job.started_at is None:
+            await refund_credit(session, job, "Job cancelled before processing")
+        else:
+            # Was processing - keep credits (API may have been consumed)
+            await confirm_credit(session, job)
+            logger.info(f"Job {job.job_id} cancelled during processing, credits kept")
+
+
+async def refund_orphaned_jobs(session: AsyncSession) -> int:
+    """
+    Refund credits for jobs that were abandoned due to server shutdown.
+    
+    Called during graceful shutdown to ensure no credits are lost.
+    
+    Args:
+        session: Database session
+        
+    Returns:
+        Number of jobs that were refunded
+    """
+    from core.models import GeminiJob
+    
+    # Find jobs that are still processing with reserved credits
+    result = await session.execute(
+        select(GeminiJob).where(
+            GeminiJob.status == "processing",
+            GeminiJob.credits_reserved > 0,
+            GeminiJob.credits_refunded == False
+        )
+    )
+    orphaned_jobs = result.scalars().all()
+    
+    refund_count = 0
+    for job in orphaned_jobs:
+        if await refund_credit(session, job, "SERVER_SHUTDOWN: Job orphaned during server shutdown"):
+            # Mark job as failed
+            job.status = "failed"
+            job.error_message = "Server shutdown during processing. Credits refunded."
+            refund_count += 1
+    
+    if refund_count > 0:
+        await session.commit()
+        logger.info(f"Refunded {refund_count} orphaned job(s) during shutdown")
+    
+    return refund_count

services/credit_service/middleware.py

@@ -0,0 +1,130 @@
+"""
+Credit Middleware - Request credit validation layer
+
+Intercepts requests to validate and reserve credits for paid endpoints.
+"""
+
+import logging
+from datetime import datetime
+from fastapi import Request, HTTPException, status
+from fastapi.responses import JSONResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from core.database import async_session_maker
+from services.credit_service.config import CreditServiceConfig
+from services.base_service.middleware_chain import (
+    BaseServiceMiddleware,
+    get_request_context,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class CreditMiddleware(BaseServiceMiddleware):
+    """
+    Credit validation middleware for request validation.
+    
+    Flow:
+    1. Check if route requires credits based on URL
+    2. Get authenticated user from request.state (set by AuthMiddleware)
+    3. Check if user has sufficient credits
+    4. Reserve credits (deduct from balance)
+    5. Attach credit info to request.state
+    6. Continue to next middleware/route
+    
+    Credits are reserved but tracked - they can be refunded if job fails
+    with a server-side error.
+    
+    NOTE: This middleware MUST run AFTER AuthMiddleware since it needs
+    the authenticated user from request.state.user
+    """
+    
+    SERVICE_NAME = "credit"
+    
+    async def dispatch(self, request: Request, call_next):
+        """Process request through credit middleware."""
+        # Skip OPTIONS requests (CORS preflight)
+        if request.method == "OPTIONS":
+            return await call_next(request)
+        
+        # Initialize request context
+        ctx = get_request_context(request)
+        
+        # Get path from request
+        path = request.url.path
+        
+        # Check if route requires credits
+        credit_cost = CreditServiceConfig.get_cost(path)
+        
+        if credit_cost == 0:
+            # Route doesn't require credits, skip
+            self.log_request(request, f"Route doesn't require credits")
+            ctx.set_credits(0, 0)
+            response = await call_next(request)
+            return response
+        
+        # Route requires credits - user MUST be authenticated
+        # (AuthMiddleware should have already validated this)
+        user = request.state.user if hasattr(request.state, 'user') else None
+        
+        if not user:
+            # This shouldn't happen if auth is configured correctly
+            self.log_error(request, "Credit-required route accessed without authentication")
+            return JSONResponse(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                content={"detail": "Authentication required for this endpoint"},
+            )
+        
+        # Check if user has sufficient credits
+        if user.credits < credit_cost:
+            self.log_request(
+                request,
+                f"Insufficient credits: has {user.credits}, needs {credit_cost}"
+            )
+            return JSONResponse(
+                status_code=status.HTTP_402_PAYMENT_REQUIRED,
+                content={
+                    "detail": f"Insufficient credits. This operation requires {credit_cost} credits. You have {user.credits}.",
+                    "credits_required": credit_cost,
+                    "credits_available": user.credits,
+                },
+            )
+        
+        # Reserve credits (deduct from user balance)
+        async with async_session_maker() as db:
+            try:
+                # Deduct credits
+                user.credits -= credit_cost
+                user.last_used_at = datetime.utcnow()
+                
+                # Update in database
+                db.add(user)
+                await db.commit()
+                await db.refresh(user)
+                
+                # Attach credit info to request state
+                ctx.set_credits(credit_cost, user.credits)
+                request.state.credits_reserved = credit_cost
+                request.state.credits_remaining = user.credits
+                
+                self.log_request(
+                    request,
+                    f"Reserved {credit_cost} credits for {user.user_id}, remaining: {user.credits}"
+                )
+                
+                # Continue to next middleware/route
+                response = await call_next(request)
+                return response
+            
+            except Exception as e:
+                await db.rollback()
+                self.log_error(request, f"Error reserving credits: {e}")
+                return JSONResponse(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    content={"detail": "Failed to reserve credits. Please try again."},
+                )
+            finally:
+                await db.close()
+
+
+__all__ = ['CreditMiddleware']

tests/test_base_service.py

@@ -0,0 +1,252 @@
+"""
+Unit tests for base service infrastructure.
+
+Tests:
+- BaseService registration and configuration
+- ServiceRegistry service management
+- ServiceConfig operations
+"""
+
+import pytest
+from services.base_service import BaseService, ServiceConfig, ServiceRegistry
+
+
+class TestServiceConfig:
+    """Test ServiceConfig container."""
+    
+    def test_initialization(self):
+        """Test config initialization with kwargs."""
+        config = ServiceConfig(key1="value1", key2=42)
+        
+        assert config.get("key1") == "value1"
+        assert config.get("key2") == 42
+    
+    def test_get_with_default(self):
+        """Test get with default value."""
+        config = ServiceConfig(key1="value1")
+        
+        assert config.get("key1") == "value1"
+        assert config.get("missing", "default") == "default"
+        assert config.get("missing") is None
+    
+    def test_set_value(self):
+        """Test setting values."""
+        config = ServiceConfig()
+        
+        config.set("key1", "value1")
+        assert config.get("key1") == "value1"
+    
+    def test_dictionary_access(self):
+        """Test dictionary-style access."""
+        config = ServiceConfig(key1="value1")
+        
+        assert config["key1"] == "value1"
+        
+        config["key2"] = "value2"
+        assert config["key2"] == "value2"
+    
+    def test_contains(self):
+        """Test 'in' operator."""
+        config = ServiceConfig(key1="value1")
+        
+        assert "key1" in config
+        assert "missing" not in config
+
+
+class TestBaseService:
+    """Test BaseService abstract class."""
+    
+    def setup_method(self):
+        """Reset service state before each test."""
+        # Create concrete test service
+        class TestService(BaseService):
+            SERVICE_NAME = "test_service"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        self.TestService = TestService
+        
+        # Reset state
+        self.TestService._registered = False
+        self.TestService._config = None
+    
+    def test_registration(self):
+        """Test service registration."""
+        assert not self.TestService.is_registered()
+        
+        self.TestService.register(key1="value1", key2=42)
+        
+        assert self.TestService.is_registered()
+        assert self.TestService.get_config().get("key1") == "value1"
+        assert self.TestService.get_config().get("key2") == 42
+    
+    def test_double_registration_fails(self):
+        """Test that double registration raises error."""
+        self.TestService.register(key1="value1")
+        
+        with pytest.raises(RuntimeError, match="already registered"):
+            self.TestService.register(key2="value2")
+    
+    def test_assert_registered(self):
+        """Test assert_registered raises when not registered."""
+        with pytest.raises(RuntimeError, match="not registered"):
+            self.TestService.assert_registered()
+        
+        self.TestService.register()
+        self.TestService.assert_registered()  # Should not raise
+    
+    def test_get_config_before_registration(self):
+        """Test get_config raises before registration."""
+        with pytest.raises(RuntimeError, match="not registered"):
+            self.TestService.get_config()
+    
+    def test_get_middleware_default(self):
+        """Test default get_middleware returns None."""
+        assert self.TestService.get_middleware() is None
+    
+    def test_on_shutdown_default(self):
+        """Test default on_shutdown does nothing."""
+        self.TestService.on_shutdown()  # Should not raise
+
+
+class TestServiceRegistry:
+    """Test ServiceRegistry global registry."""
+    
+    def setup_method(self):
+        """Reset registry before each test."""
+        ServiceRegistry._services = {}
+    
+    def test_register_service(self):
+        """Test registering a service."""
+        class TestService(BaseService):
+            SERVICE_NAME = "test_service"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        ServiceRegistry.register_service(TestService)
+        
+        assert ServiceRegistry.get_service("test_service") == TestService
+    
+    def test_register_multiple_services(self):
+        """Test registering multiple services."""
+        class Service1(BaseService):
+            SERVICE_NAME = "service1"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        class Service2(BaseService):
+            SERVICE_NAME = "service2"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        ServiceRegistry.register_service(Service1)
+        ServiceRegistry.register_service(Service2)
+        
+        assert len(ServiceRegistry.get_all_services()) == 2
+        assert ServiceRegistry.get_service("service1") == Service1
+        assert ServiceRegistry.get_service("service2") == Service2
+    
+    def test_get_nonexistent_service(self):
+        """Test getting service that doesn't exist."""
+        assert ServiceRegistry.get_service("nonexistent") is None
+    
+    def test_overwrite_service(self):
+        """Test registering service with same name overwrites."""
+        class Service1(BaseService):
+            SERVICE_NAME = "test"
+            version = 1
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        class Service2(BaseService):
+            SERVICE_NAME = "test"
+            version = 2
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        ServiceRegistry.register_service(Service1)
+        ServiceRegistry.register_service(Service2)
+        
+        service = ServiceRegistry.get_service("test")
+        assert service.version == 2
+    
+    def test_get_all_middleware(self):
+        """Test getting middleware from all services."""
+        class MockMiddleware:
+            pass
+        
+        class ServiceWithMiddleware(BaseService):
+            SERVICE_NAME = "with_middleware"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+            
+            @classmethod
+            def get_middleware(cls):
+                return MockMiddleware()
+        
+        class ServiceWithoutMiddleware(BaseService):
+            SERVICE_NAME = "without_middleware"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+        
+        # Register services
+        ServiceWithMiddleware.register()
+        ServiceWithoutMiddleware.register()
+        
+        ServiceRegistry.register_service(ServiceWithMiddleware)
+        ServiceRegistry.register_service(ServiceWithoutMiddleware)
+        
+        middleware_list = ServiceRegistry.get_all_middleware()
+        
+        assert len(middleware_list) == 1
+        assert isinstance(middleware_list[0], MockMiddleware)
+    
+    def test_shutdown_all(self):
+        """Test calling shutdown on all services."""
+        shutdown_called = []
+        
+        class Service1(BaseService):
+            SERVICE_NAME = "service1"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+            
+            @classmethod
+            def on_shutdown(cls):
+                shutdown_called.append("service1")
+        
+        class Service2(BaseService):
+            SERVICE_NAME = "service2"
+            
+            @classmethod
+            def register(cls, **config):
+                super().register(**config)
+            
+            @classmethod
+            def on_shutdown(cls):
+                shutdown_called.append("service2")
+        
+        ServiceRegistry.register_service(Service1)
+        ServiceRegistry.register_service(Service2)
+        
+        ServiceRegistry.shutdown_all()
+        
+        assert "service1" in shutdown_called
+        assert "service2" in shutdown_called

tests/test_route_matcher.py

@@ -0,0 +1,243 @@
+"""
+Unit tests for route matcher.
+
+Tests:
+- Exact path matching
+- Prefix pattern matching
+- Glob pattern matching
+- Regex pattern matching
+- RouteConfig precedence logic
+"""
+
+import pytest
+from services.base_service.route_matcher import RouteMatcher, RouteConfig
+
+
+class TestRouteMatcher:
+    """Test RouteMatcher pattern matching."""
+    
+    def test_exact_match(self):
+        """Test exact path matching."""
+        matcher = RouteMatcher(["/api/users", "/api/posts"])
+        
+        assert matcher.matches("/api/users")
+        assert matcher.matches("/api/posts")
+        assert not matcher.matches("/api/comments")
+        assert not matcher.matches("/api/users/123")
+    
+    def test_prefix_match(self):
+        """Test prefix wildcard matching."""
+        matcher = RouteMatcher(["/api/*", "/admin/*"])
+        
+        assert matcher.matches("/api/users")
+        assert matcher.matches("/api/posts")
+        assert matcher.matches("/admin/dashboard")
+        assert not matcher.matches("/public/page")
+    
+    def test_complex_glob_match(self):
+        """Test complex glob patterns."""
+        matcher = RouteMatcher(["/api/users/*/posts", "/api/**/comments"])
+        
+        assert matcher.matches("/api/users/123/posts")
+        assert matcher.matches("/api/users/456/posts")
+        assert matcher.matches("/api/v1/users/comments")
+        assert matcher.matches("/api/deep/nested/path/comments")
+        assert not matcher.matches("/api/users/posts")
+    
+    def test_regex_match(self):
+        """Test regex pattern matching."""
+        matcher = RouteMatcher(["^/api/v[0-9]+/.*$", "^/users/[0-9]+$"])
+        
+        assert matcher.matches("/api/v1/users")
+        assert matcher.matches("/api/v2/posts")
+        assert matcher.matches("/users/123")
+        assert not matcher.matches("/api/v/users")
+        assert not matcher.matches("/users/abc")
+    
+    def test_query_parameters_stripped(self):
+        """Test that query parameters are ignored."""
+        matcher = RouteMatcher(["/api/users"])
+        
+        assert matcher.matches("/api/users?page=1")
+        assert matcher.matches("/api/users?page=1&limit=10")
+    
+    def test_fragments_stripped(self):
+        """Test that URL fragments are ignored."""
+        matcher = RouteMatcher(["/api/users"])
+        
+        assert matcher.matches("/api/users#section")
+    
+    def test_trailing_slash_normalized(self):
+        """Test trailing slash normalization."""
+        matcher = RouteMatcher(["/api/users"])
+        
+        assert matcher.matches("/api/users/")
+        
+        # Root path keeps trailing slash
+        root_matcher = RouteMatcher(["/"])
+        assert root_matcher.matches("/")
+    
+    def test_empty_patterns(self):
+        """Test with empty pattern list."""
+        matcher = RouteMatcher([])
+        
+        assert not matcher.matches("/any/path")
+    
+    def test_get_matching_pattern(self):
+        """Test getting the matched pattern."""
+        matcher = RouteMatcher([
+            "/api/users",
+            "/api/*",
+            "/admin/**"
+        ])
+        
+        assert matcher.get_matching_pattern("/api/users") == "/api/users"
+        assert matcher.get_matching_pattern("/api/posts") == "/api/*"
+        assert matcher.get_matching_pattern("/admin/deep/path") == "/admin/**"
+        assert matcher.get_matching_pattern("/public") is None
+    
+    def test_mixed_patterns(self):
+        """Test combination of all pattern types."""
+        matcher = RouteMatcher([
+            "/exact",
+            "/prefix/*",
+            "/glob/*/nested",
+            "^/regex/[0-9]+$"
+        ])
+        
+        assert matcher.matches("/exact")
+        assert matcher.matches("/prefix/anything")
+        assert matcher.matches("/glob/123/nested")
+        assert matcher.matches("/regex/456")
+        assert not matcher.matches("/other")
+    
+    def test_invalid_regex_pattern(self):
+        """Test that invalid regex is handled gracefully."""
+        # Should not raise, just log warning and skip pattern
+        matcher = RouteMatcher(["^[invalid(regex$"])
+        
+        assert not matcher.matches("/anything")
+
+
+class TestRouteConfig:
+    """Test RouteConfig precedence logic."""
+    
+    def test_required_routes(self):
+        """Test required route checking."""
+        config = RouteConfig(
+            required=["/api/users", "/api/posts"],
+        )
+        
+        assert config.is_required("/api/users")
+        assert config.is_required("/api/posts")
+        assert not config.is_required("/public")
+    
+    def test_optional_routes(self):
+        """Test optional route checking."""
+        config = RouteConfig(
+            optional=["/", "/home"],
+        )
+        
+        assert config.is_optional("/")
+        assert config.is_optional("/home")
+        assert not config.is_optional("/api/users")
+    
+    def test_public_routes(self):
+        """Test public route checking."""
+        config = RouteConfig(
+            public=["/health", "/docs"],
+        )
+        
+        assert config.is_public("/health")
+        assert config.is_public("/docs")
+        assert not config.is_public("/api/users")
+    
+    def test_public_overrides_required(self):
+        """Test that public takes precedence over required."""
+        config = RouteConfig(
+            required=["/api/*"],
+            public=["/api/health"],
+        )
+        
+        # /api/health is public, so not required
+        assert config.is_public("/api/health")
+        assert not config.is_required("/api/health")
+        
+        # Other /api routes are required
+        assert config.is_required("/api/users")
+        assert not config.is_public("/api/users")
+    
+    def test_public_overrides_optional(self):
+        """Test that public takes precedence over optional."""
+        config = RouteConfig(
+            optional=["/api/*"],
+            public=["/api/health"],
+        )
+        
+        # /api/health is public, so not optional
+        assert config.is_public("/api/health")
+        assert not config.is_optional("/api/health")
+        
+        # Other /api routes are optional
+        assert config.is_optional("/api/users")
+    
+    def test_required_overrides_optional(self):
+        """Test that required takes precedence over optional."""
+        config = RouteConfig(
+            required=["/api/users"],
+            optional=["/api/*"],
+        )
+        
+        # /api/users is required, so not optional
+        assert config.is_required("/api/users")
+        assert not config.is_optional("/api/users")
+        
+        # Other /api routes are optional
+        assert config.is_optional("/api/posts")
+    
+    def test_requires_service(self):
+        """Test requires_service helper."""
+        config = RouteConfig(
+            required=["/api/users"],
+            optional=["/api/posts"],
+            public=["/health"],
+        )
+        
+        # Service required
+        assert config.requires_service("/api/users")
+        
+        # Service optional (still requires service)
+        assert config.requires_service("/api/posts")
+        
+        # Public (does not require service)
+        assert not config.requires_service("/health")
+    
+    def test_empty_config(self):
+        """Test with empty configuration."""
+        config = RouteConfig()
+        
+        assert not config.is_required("/any")
+        assert not config.is_optional("/any")
+        assert not config.is_public("/any")
+        assert not config.requires_service("/any")
+    
+    def test_complex_precedence(self):
+        """Test complex precedence scenarios."""
+        config = RouteConfig(
+            required=["/api/users"],  # Specific required path
+            optional=["/api/*"],       # Broader optional pattern
+            public=["/api/health"],
+        )
+        
+        # Public overrides everything
+        assert config.is_public("/api/health")
+        assert not config.is_required("/api/health")
+        assert not config.is_optional("/api/health")
+        
+        # Required path
+        assert config.is_required("/api/users")
+        assert not config.is_optional("/api/users")
+        
+        # Optional for other paths under /api
+        assert config.is_optional("/api/posts")
+        assert not config.is_required("/api/posts")