Observability & Error Handling
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Observability and Error Handling in Comply-Quick are centered around a structured approach to request validation, rate limiting, and technical logging. The system is designed to provide clear feedback during the compliance package generation process and ensure operational stability through centralized error utilities and logging.
The architecture emphasizes strict TypeScript compliance and standardized Next.js App Router conventions for handling failures, such as error.tsx and structured JSON error responses in API routes. This ensures that failures in complex pipelines—like the AI-driven scanner or autopilot regeneration—are captured and communicated effectively to both users and system administrators.
Sources: devin/instructions.md:65-68, src/app/api/compliance/route.ts:7-13
Centralized Logging Architecture
The project utilizes a centralized logger to track system events, particularly during API interactions and internal pipeline executions. In API routes, loggers are often scoped to specific modules to provide context-rich debugging information.
The logger captures critical metadata such as the framework used in a compliance request, the number of target regions, and the specific modules requested. This data helps in monitoring the distribution of generated packages and identifying usage patterns.
Sources: src/app/api/compliance/route.ts:13-15, src/app/api/compliance/route.ts:108-112
Error Handling & Response Patterns
Comply-Quick uses a standardized error response mechanism to ensure consistency across its REST API. Errors are categorized primarily into validation errors, rate limit exceeded errors, and internal processing failures.
Standardized API Error Responses
When a request fails, the API returns a structured JSON object. The response varies based on the type of error:
- Validation Errors (400/422): Occur when required fields (userType, framework, etc.) are missing or contain invalid values.
- Rate Limit Errors (429): Occurred via the
enforceRateLimitutility. - JSON Parsing Errors (400): Occur if the request body is malformed.
| Error Type | Status Code | Description |
|---|---|---|
ValidationError | 400/422 | Thrown when input data fails schema or logic validation. |
Invalid JSON | 400 | Thrown when request.json() fails to parse. |
RateLimitError | 429 | Thrown when a client exceeds the allowed request window. |
Sources: src/app/api/v1/compliance/route.ts:47-60, src/app/api/compliance/route.ts:77-84, src/services/index.ts:1-10
Logic for API Validation
API routes implement validateBody or validateRequestBody functions that check input against allowed sets of constants (e.g., VALID_FRAMEWORKS, VALID_PIXELS).
function validateBody(body: unknown): asserts body is ApiRequestBody {
if (typeof body !== "object" || body === null) throw new ValidationError("Request body must be a JSON object.");
// ... check userType, framework, trackingPixels, targetRegions
}
Sources: src/app/api/v1/compliance/route.ts:40-55, src/app/api/compliance/route.ts:50-59
Observability in AI Pipelines
The system includes specialized observability logic for AI-driven features like the Compliance Scanner and Autopilot Regeneration. Since these rely on external AI clients, they implement deterministic fallbacks to ensure the system remains observable even when the AI service is unavailable or fails.
Scanner Pipeline:* Logs whether a headless render was executed (rendered: boolean) to indicate the depth of tracker detection.
- Autopilot Pipeline: Compares regenerated markdown against stored versions and produces a
DocumentDiffto track document evolution.
Sources: src/lib/scanner/pipeline.ts:15-17, src/lib/scanner/pipeline.ts:45-56, src/lib/autopilot/pipeline.ts:80-95
Rate Limiting and Traffic Control
Traffic control is implemented via an InMemoryRateLimiter. This service tracks client keys (derived from headers) and enforces limits within a specific time window.
- Public API Limit: Capped at 30 requests per 60,000ms (1 minute).
- Programmatic API Limit: 120 requests per minute per key.
- Headers: Responses include standard headers:
X-RateLimit-Limit,X-RateLimit-Remaining, andX-RateLimit-Reset.
Sources: src/app/api/compliance/route.ts:17-18, src/app/dashboard/api/ApiView.tsx:310-315
Conclusion
The Observability and Error Handling framework in Comply-Quick provides a robust foundation for building and scaling compliance tools. By combining strict TypeScript typing, centralized error utilities, scoped logging, and deterministic fallbacks for AI components, the system maintains high reliability and provides clear diagnostic paths for developers. This structure is essential for managing the project's complex interactions between user inputs, regulatory logic, and external AI services.