# samber/oops architecture

> Architecture diagram of the GitHub repository samber/oops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samber/oops
- Repository: https://github.com/samber/oops

## Overview

##### Project type and purpose
- This is a Go library (“oops”) for structured error handling.
- It provides a fluent error‐builder API that captures context, stack traces, source fragments, assertions, and panic recovery.
- Integrations include formatters for popular loggers (logrus, zerolog, slog) and a Gin middleware for panic handling.

##### File structure
- Root files (builder.go, context.go, error.go, utils.go, kv.go, stacktrace.go, etc.) make up the core “oops” package.
- Subdirectories:
– loggers/logrus, loggers/zerolog – formatter implementations for two log libraries
– recovery/gin – a Gin middleware for recovering panics to oops errors
– examples/… – sample apps demonstrating usage with various loggers and panic scenarios
- Supporting files: tests, Makefile, CI workflows, assets (logo, README).

##### Key insights from the README
- The library wraps or builds errors via methods like `.Errorf`, `.Wrapf`, `.Recover`, `.Assert`, each returning an `OopsError`.
- Internally it captures a stack trace (configurable max depth), can read Go source files for fragments, and attaches metadata (code, domain, tags, timing, user/tenant info, hints, owners).
- It integrates with Go’s `context.Context`, and exposes custom slog/logrus/zerolog formatters.

##### Main components
A. Consumer Application Code
– Calls `oops` builder methods in business logic or HTTP handlers.
– May pass or retrieve an `OopsErrorBuilder` via `context.Context`.
B. Oops Core Package
1. Builder API – fluent methods (`With`, `In`, `Code`, `User`, `.Errorf`/`.Wrap`/`.Recoverf`, `.Assertf`, etc.)
2. Error Implementation – `OopsError` struct implementing `error`, holding context map, stack frames, source fragments, metadata fields
3. StackTrace Generator – uses `runtime` to capture and prune call frames
4. SourceFragment Extractor – reads Go source files based on frame file paths (if enabled)
5. Panic Recovery / Assertion Engine – wrappers for `panic` interception
6. Context Propagation – attach/retrieve builder via `context.Context`
C. Logger Integration Modules
– loggers/logrus/formatter.go
– loggers/zerolog/formatter.go
– examples for built-in `log` and `slog`
D. Third-Party / External Systems
– Gin HTTP framework (recovery middleware)
– External log sinks (console, JSON file, external services)

##### Relationships and data flow
1. Application logic → invokes Oops Builder API → returns `OopsError`
2. Builder API → requests stack trace from StackTrace Generator
3. Builder API → (optionally) reads source fragments via SourceFragment Extractor
4. Application → logs the `OopsError` → passes it to a logger integration module
5. Logger integration → extracts error fields via `ToMap`/`Format`/`LogValuer` → emits JSON or structured log
6. HTTP handler wraps business logic → uses Gin Recovery Middleware → automatically converts panics into `OopsError`

##### Architectural patterns & design principles
- Fluent/builder pattern for error composition
- Separation of concerns: core error builder vs. logging formatters vs. HTTP middleware vs. examples
- Lazy evaluation of context attributes (functions)
- Strict SemVer and zero external dependencies

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Application
    subgraph "Consumer Application" 
        direction TB
        App["Application Code"]:::app
    end

    %% Oops Core Package
    subgraph "Oops Core Package"
        direction TB
        CoreEntry["Core Package Entrypoint"]:::core
        Builder["Builder API"]:::core
        ErrorImpl["OopsError Implementation"]:::core
        ContextProp["Context Propagation"]:::core
        KV["KV Context Helpers"]:::core
        StackTrace["StackTrace Generator"]:::core
        SourceFrag["SourceFragment Extractor"]:::core
        RecoveryEngine["Panic Recovery & Assertion Engine"]:::core
    end

    %% Integrations
    subgraph "Integrations"
        direction TB
        Logrus["Logrus Formatter"]:::ext
        Zerolog["Zerolog Formatter"]:::ext
        GinMW["Gin Recovery Middleware"]:::ext
    end

    %% Examples & CI/CD
    subgraph "Examples & CI/CD"
        direction TB
        Examples["Examples/"]:::infra
    end

    %% Connections
    App -->|"invokes"| Builder
    Builder -->|"captures traces"| StackTrace
    Builder -->|"extracts sources"| SourceFrag
    Builder -->|"attaches context"| ContextProp
    Builder -->|"creates error"| ErrorImpl
    Builder -->|"uses KV helpers"| KV
    Builder -->|"wraps panics/assert"| RecoveryEngine
    App -->|"logs error"| Logrus
    App -->|"logs error"| Zerolog
    App -->|"HTTP panic handling"| GinMW
    GinMW -->|"converts panic to OopsError"| Builder
    ErrorImpl -->|"formatted by"| Logrus
    ErrorImpl -->|"formatted by"| Zerolog
    ErrorImpl -->|"handled by"| GinMW
    App -->|"demo & tests"| Examples

    %% Click Events
    click App "https://github.com/samber/oops/tree/main/examples/"
    click Builder "https://github.com/samber/oops/blob/main/builder.go"
    click ErrorImpl "https://github.com/samber/oops/blob/main/error.go"
    click ContextProp "https://github.com/samber/oops/blob/main/context.go"
    click KV "https://github.com/samber/oops/blob/main/kv.go"
    click StackTrace "https://github.com/samber/oops/blob/main/stacktrace.go"
    click SourceFrag "https://github.com/samber/oops/blob/main/sources.go"
    click RecoveryEngine "https://github.com/samber/oops/blob/main/helpers.go"
    click RecoveryEngine "https://github.com/samber/oops/blob/main/utils.go"
    click GinMW "https://github.com/samber/oops/blob/main/recovery/gin/middleware.go"
    click Logrus "https://github.com/samber/oops/blob/main/loggers/logrus/formatter.go"
    click Zerolog "https://github.com/samber/oops/blob/main/loggers/zerolog/formatter.go"
    click CoreEntry "https://github.com/samber/oops/blob/main/oops.go"
    click CoreEntry "https://github.com/samber/oops/blob/main/oops_n.go"
    click Examples "https://github.com/samber/oops/tree/main/examples/"

    %% Styles
    classDef app fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef core fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef ext fill:#FAD7A0,stroke:#B9770E,color:#7E5109
    classDef infra fill:#E8DAEF,stroke:#6C3483,color:#4A235A
```
