Part 11: Error Handling Architecture: Unified GraphQL Error Formatting & Sentry Integration

Module: Module 1: Architecture, Monorepo Setup & Tooling
Category: Technology
Keywords: django, graphql, angular, erp, architecture, docker
Meta Description: Standardizing error responses, domain exceptions, and centralized exception tracking.

1. Executive Summary & System Architecture

Implement clean, structured GraphQL error extensions with error codes (NOT_FOUND, PERMISSION_DENIED, VALIDATION_ERROR).

In enterprise Educational Resource Planning (ERP) systems, orchestrating students, faculty, schedules, attendance, grading, and finances demands a robust, loosely-coupled architecture. We pair Django (leveraging its robust ORM, transactional integrity, and battle-tested security) with GraphQL (providing flexible, client-driven data graphs with zero over-fetching) and Angular (featuring strict TypeScript typing, Standalone components, reactive Signals, and Apollo Client normalization).

2. Backend Database Modeling (Django ORM & PostgreSQL)

Below is the production-grade Django model definition enforcing data integrity, foreign key constraints, indexes, and audit metadata:

# backend/apps/erp/models.py
class ERPDomainException(Exception):
    def __init__(self, message, code='BUSINESS_ERROR', params=None):
        super().__init__(message)
        self.code = code
        self.params = params or {}

Key Architectural Highlights:

• Audit Logging: Inherits from a base audit model capturing created_at, updated_at, created_by, and soft-delete flags.
• Index Optimization: Explicit database indexes (db_index=True, indexes=[models.Index(...)]) positioned for high-frequency queries.
• Validation: Enforces domain constraints via clean validation methods and unique constraints across academic years and tenant boundaries.

3. GraphQL API Layer (Types, Queries & Mutations)

The GraphQL layer exposes precise schema definitions, input validation, and transactional mutation execution:

# backend/apps/erp/schema.py
# GraphQL formatted error handler
def format_error(error):
    formatted = error.formatted
    if hasattr(error, 'original_error') and isinstance(error.original_error, ERPDomainException):
        formatted['extensions'] = {
            'code': error.original_error.code,
            'params': error.original_error.params
        }
    return formatted

Resolver & Data Fetching Patterns:

• Batch Loading: Resolvers integrate with DataLoader to eliminate N+1 database queries when fetching nested relationships.
• Permission Enforcement: Mutations verify caller authorization via role-based access decorators before touching the database.
• Transactional Consistency: Multi-table updates execute inside transaction.atomic() context blocks to ensure ACID atomicity.

4. Frontend Angular Implementation (Signals & Apollo Client)

The modern Angular implementation features Standalone components, reactive Signals, and type-safe Apollo Client interactions:

// frontend/src/app/erp/components/feature.component.ts
// Angular Global Error Handler
import { ErrorHandler, Injectable } from '@angular/core';

@Injectable()
export class GlobalErrorHandler implements ErrorHandler {
  handleError(error: any): void {
    console.error('ERP Client Error:', error);
  }
}

Frontend Architectural Patterns:

• Reactivity with Signals: Uses Angular signal(), computed(), and effect primitives for fine-grained DOM updates without unnecessary change detection cycles.
• Type-Safe GraphQL: Consumes strongly-typed operations generated by @graphql-codegen.
• User Feedback: Integrates reactive loading state indicators, optimistic UI updates, and error handling toasts.

5. Security, Permissions & Multi-Tenancy

Sanitize database and stack trace errors so internal infrastructure details are never leaked to client browsers.

6. Critical Pitfalls & Production Anti-Patterns

When deploying this module in large-scale institutions with thousands of concurrent users, avoid these traps:

1. Exposing raw database error messages with SQL syntax to end users.
2. Swallowing errors silently without logging to centralized monitors.
3. Displaying technical error codes instead of user-friendly explanations.

7. Enterprise Best Practices & Production Checklist

• ✅ Map domain exceptions to standard GraphQL error extension codes.
• ✅ Integrate Sentry on both Django and Angular for real-time error alerts.
• ✅ Provide localized, helpful validation messages in error payloads.
• ✅ Log unique trace IDs in both client and server logs for easy debugging.

Part 11 of the comprehensive Fullstack Student ERP Tutorial Series.