Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Error Handling & Logging

​

Standard Error Pattern: ServiceResult

​

Structure

interface IServiceResult<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;        // e.g., 'PERMISSION_DENIED'
    message: string;     // Human readable for devs
    details?: any;       // Raw error or context
    severity: 'low' | 'medium' | 'high' | 'critical';
  };
}

​

Usage in Services

async myAction() {
  return this.withServiceResult(async () => {
    // If this throws, it is caught and wrapped
    const data = await someAsyncWork();
    return data;
  }, { operation: 'myAction' });
}

​

Error Classifications

​

Logging & Monitoring

​

1. Application Logs (Structured Logger)

• Emits structured logs to Cloud Logging (server) or console (client)
• Adds Sentry breadcrumbs for info/warn
• Captures exceptions in logger.error()

• Debug: Only in development.
• Info: Major business events (Project started, user joined).
• Warn: Recoverable issues (also breadcrumbs; optionally captureMessage when explicitly requested).
• Error/Fatal: Caught exceptions.

​

2. Audit Logging (Firestore)

• Retention: Permanent (compliance requirement).
• Fields: userId, organizationId, action, payload, timestamp.

​

3. Sentry Integration

• React render crashes (via error boundaries)
• Manual reports via logger.error() and handleError()
• Performance warnings via Sentry.captureMessage() where explicitly used

​

Error Code Catalog

​

ErrorSeverity Enum

​

ErrorCategory Enum

​

Error Class Hierarchy

AppError (abstract)
├── UserError
│   ├── ValidationError          — Input validation failures
│   ├── AuthorizationError       — Permission denied (userMessage: "You do not have permission…")
│   ├── NotFoundError            — Resource not found (accepts resource name + id)
│   ├── RateLimitError           — API throttling (accepts optional retryAfter seconds)
│   └── BusinessLogicError       — Domain rule violations (userMessage = message)
│
└── SystemError
    ├── AuthenticationError      — Login/token failures
    ├── FirestoreError           — Firestore operation failures (accepts operation + original error)
    ├── StorageError             — Firebase Storage failures (accepts operation + original error)
    ├── NetworkError             — Fetch/connectivity failures
    ├── ExternalAPIError         — Third-party API failures (accepts service name + original error)
    ├── AIServiceError           — Gemini/Genkit failures (accepts operation + original error)
    └── EmailServiceError        — Postmark failures (accepts operation + original error)

​

Domain-Specific Error Classes

​

Standalone Error Class

​

Sentry Integration Details

​

Frontend (src/lib/sentryBrowser.ts)

​

Cloud Functions (functions/src/core/sentry.ts)

• Uses getIsolationScope() for per-request tenant/user tagging (organizationId, authType, requestId, userId).
• withSentryIsolationScope(scope, fn) wraps an async operation with scoped tags.
• captureException() calls Sentry.flush() (default 2 s timeout) to ensure delivery before the function terminates.
• Release is set from SENTRY_RELEASE or GITHUB_SHA (uploaded via CI).

​

What Gets Sent to Sentry (Filtering Rules)

1. Never in development (import.meta.env.DEV).
2. Never for INFO or WARNING severity.
3. Never for user-error categories: VALIDATION, NOT_FOUND, AUTHORIZATION.
4. Everything else (system errors, Firestore errors, network errors, external API errors, AI service errors) is captured.

• category — the ErrorCategory value
• severity — the ErrorSeverity value
• error_class — the constructor name (e.g., FirestoreError)

​

Error Boundaries in React

​

1. SentryErrorBoundary (src/components/SentryErrorBoundary.tsx)

• Scope: Wraps the entire <App /> in src/bootstrap.tsx — the outermost catch.
• Behavior: Captures to Sentry, shows full-page “Something went wrong” card with “Reload Application” button and “Report feedback” link (opens Sentry.showReportDialog).
• Displays: Sentry event ID in footer for support reference.

​

2. RouteErrorBoundary (src/components/ui/RouteErrorBoundary.tsx)

• Scope: Wraps individual routes and page sections.
• Isolation levels: 'route' (full-page fallback, default) or 'section' (compact inline card).
• Behavior: Captures to Sentry with isolationLevel context. Supports custom fallbackComponent prop. “Try Again” resets state; “Go to Overview” navigates to /overview.
• Dev mode: Shows error message in a code block.

​

3. ErrorBoundary (src/components/ui/ErrorBoundary.tsx)

• Scope: Wraps individual components or widget areas.
• Features: Accepts context string (sent as Sentry tag errorBoundary), onError callback, onReset handler, optional fallback ReactNode, showDetails toggle.
• Dev mode: Shows full error details and component stack trace.
• Recovery: “Try Again” button with repeated-failure warning.

​

4. WidgetErrorBoundary (inline in src/components/widgets/WidgetDashboardBase.tsx)

• Scope: Wraps individual dashboard widgets.
• Purpose: Prevents a single broken widget from crashing the entire dashboard.

​

Error Handling Patterns by Layer

​

Service Layer

// In a service extending BaseService
async archiveProject(id: string): Promise<ServiceResult> {
  return this.withServiceResult(
    async () => {
      await this.update(id, { archived: true });
    },
    { operation: 'archiveProject', entityId: id }
  );
}

import { NotFoundError, BusinessLogicError } from '@grantmaster/shared/errors';

if (!project) throw new NotFoundError('Project', projectId);
if (project.budget <= 0) throw new BusinessLogicError('Budget must be positive');

​

Hook Layer

• handleError(error, context?, options?) — logs, toasts, and captures to Sentry.
• handleErrorSilent(error, context?) — logs and captures but no toast.
• withErrorBoundary(fn, context?) — wraps an async function with automatic error handling.

• Wraps an async action with loading state, error state, duplicate-execution prevention, success/error toasts, and automatic handleError integration.

const { execute, isLoading } = useAsyncAction({
  action: () => projectService.archiveProject(id),
  successMessage: 'Project archived',
  errorContext: { operation: 'archiveProject', projectId: id },
});

​

Component Layer

1. Wrap risky subtrees with <ErrorBoundary context="...">.
2. Use useErrorHandler() for imperative error handling in event handlers.
3. Use useAsyncAction() for button-triggered async operations.
4. Check ServiceResult.success before accessing .data.

function ProjectActions({ projectId }: Props) {
  const { handleError } = useErrorHandler();

  const handleArchive = async () => {
    const result = await projectService.archiveProject(projectId);
    if (!result.success) {
      // Error already logged by service — optionally show custom UI
      return;
    }
    toast.success('Project archived');
  };

  return (
    <ErrorBoundary context="Project Actions">
      <Button onClick={handleArchive}>Archive</Button>
    </ErrorBoundary>
  );
}

​

tRPC / Cloud Functions Layer

• Wrap request handlers with withSentryIsolationScope(scope, fn) for per-request user/org tagging.
• Call captureException(error, { scope, extra, tags }) for unrecoverable errors.
• Sentry flushes before function termination to avoid dropped events.

​

Maintenance

• Adding a new global error code.
• Adding or removing an error class from the hierarchy.
• Changing the severity levels.
• Modifying Sentry filtering rules.
• Adding a new error boundary.
• Switching logging providers.