GitHubEmailContact
Skip to main content

gRPC Architecture & Design

This document explains the architecture and design patterns behind Django-CFG's gRPC integration.

🏗️ System Architecture​

High-Level Overview​

🔄 Request Flow Architecture​

Complete Request Lifecycle​

Error Flow​

🧩 Component Architecture​

1. Interceptors Pipeline​

The interceptors execute in a specific order to ensure proper request handling:

Key Design Decisions:

  1. Request Logger First - Creates log entry before any processing
  2. Auth Before Error Handler - User context available for error logging
  3. Error Handler Wraps Service - Catches all service exceptions
  4. Bidirectional Flow - Interceptors process both request and response

2. Service Discovery System​

3. Base Service Classes Hierarchy​

🔐 Authentication Architecture​

API Key Flow​

Public vs Protected Methods​

📊 Monitoring Architecture​

Request Logging System​

Statistics & Metrics​

🔄 Phase 4: Dynamic Invocation​

Dynamic gRPC Client Architecture​

Key Features:

  1. Service Discovery - Automatically discover all available services
  2. Method Introspection - Get method signatures and schemas
  3. Dynamic Message Creation - Create protobuf messages from JSON/dict
  4. No Proto Files Required - Use reflection to understand service contracts

Learn more: Dynamic Invocation Guide

🎯 Design Patterns​

1. Interceptor Pattern​

Purpose: Cross-cutting concerns (logging, auth, metrics) without modifying service code.

Implementation:

class MyInterceptor(grpc.ServerInterceptor):
    def intercept_service(self, continuation, handler_call_details):
        # Pre-processing
        # ...

        # Call next interceptor/service
        response = continuation(handler_call_details)

        # Post-processing
        # ...

        return response

2. Service Discovery Pattern​

Purpose: Automatic registration of gRPC services from Django apps.

Key Components:

  • Module scanning (grpc_services.py, grpc_handlers.py)
  • Lazy loading support
  • Convention over configuration

3. Django Integration Pattern​

Purpose: Seamless access to Django features in gRPC services.

Integration Points:

  • ORM via models
  • User authentication via API keys
  • Permissions via Django auth
  • Admin interface for monitoring
  • Signals for events

4. Error Mapping Pattern​

Purpose: Convert Django exceptions to appropriate gRPC status codes.

Mapping:

Django Exception          → gRPC Status Code
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ValidationError           → INVALID_ARGUMENT
ObjectDoesNotExist        → NOT_FOUND
PermissionDenied          → PERMISSION_DENIED
NotImplementedError       → UNIMPLEMENTED
TimeoutError              → DEADLINE_EXCEEDED
Exception                 → INTERNAL

🚀 Performance Considerations​

Threading Model​

Configuration:

GRPCServerConfig(
    max_workers=10,  # Thread pool size
    # More workers = more concurrent requests
    # But higher memory usage
)

Database Optimization​

  • Connection Pooling - Reuse database connections
  • Select Related / Prefetch Related - Reduce N+1 queries
  • Indexed Fields - Fast lookups on service/method/status
  • Async Logging - Non-blocking request logging

📚 Related Documentation​

Next: Learn how to get started with gRPC in your Django-CFG project.

Last updated on