Skip to Content
DocumentationFeaturesIntegrationsgRPC IntegrationArchitecture

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.

ConceptsConfiguration