# granitebps/mongoose-log-history architecture

> Architecture diagram of the GitHub repository granitebps/mongoose-log-history, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/granitebps/mongoose-log-history
- Repository: https://github.com/granitebps/mongoose-log-history

## Overview

mongoose-log-history is a Mongoose audit-history plugin. An application attaches the plugin to a schema; hooks capture create, update, delete, soft-delete, and bulk operations, calculate configured field/array changes and context, then persist audit entries in single or per-model collections. Optional snapshots can be gzip-compressed, and callers can prune retained history or use exported helpers manually. The sampled plugin excerpt is partial, so detailed hook-to-diff dispatch is not fully verified; README capability statements preserve those branches without inventing internal call links.

Main entry points: [`src/plugin.ts`](https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts) (Model hooks), [`src/index.ts`](https://github.com/granitebps/mongoose-log-history/blob/main/src/index.ts) (Plugin API), [`src/schema.ts`](https://github.com/granitebps/mongoose-log-history/blob/main/src/schema.ts) (Log model selection), [`src/change-tracking.ts`](https://github.com/granitebps/mongoose-log-history/blob/main/src/change-tracking.ts) (Field and array diffs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Mongoose integration"]
  node_plugin_api["Plugin API<br/>[index.ts]"]
  node_schema_hooks["Model hooks<br/>[plugin.ts]"]
end

subgraph group_capture["Change capture"]
  node_operation_capture["CRUD and bulk capture<br/>[plugin.ts]"]
  node_soft_delete["Soft-delete detection<br/>[plugin.ts]"]
  node_field_diff["Field and array diffs<br/>[change-tracking.ts]"]
  node_context_user["Context and user data<br/>[plugin.ts]"]
end

subgraph group_history["History storage"]
  node_log_entry["Log entry schema<br/>[schema.ts]"]
  node_log_model["Log model selection<br/>[schema.ts]"]
  node_mongo_store[("MongoDB log collections")]
end

subgraph group_support["Helpers and API"]
  node_value_helpers["Value utilities<br/>[utils.ts]"]
  node_snapshot_compression["Snapshot compression<br/>[compression.ts]"]
  node_pruning["History pruning<br/>[prune.ts]"]
  node_manual_helpers["Manual logging helpers<br/>[plugin.ts]"]
  node_public_types["Typed configuration<br/>[types.ts]"]
end

node_application(("Application"))

node_application -->|"applies plugin"| node_plugin_api
node_plugin_api -->|"exports plugin"| node_schema_hooks
node_schema_hooks -.->|"registers hooks"| node_operation_capture
node_schema_hooks -->|"selects log model"| node_log_model
node_operation_capture -.->|"detects transition"| node_soft_delete
node_operation_capture -.->|"calculates changes"| node_field_diff
node_operation_capture -.->|"extracts metadata"| node_context_user
node_field_diff -->|"uses utilities"| node_value_helpers
node_schema_hooks -->|"compresses snapshots"| node_snapshot_compression
node_schema_hooks -.->|"builds entries"| node_log_entry
node_log_model -->|"models collections"| node_mongo_store
node_application -->|"requests pruning"| node_pruning
node_pruning -->|"selects history model"| node_log_model
node_application -->|"calls helpers"| node_manual_helpers
node_plugin_api -->|"exports types"| node_public_types

click node_plugin_api "https://github.com/granitebps/mongoose-log-history/blob/main/src/index.ts"
click node_schema_hooks "https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts"
click node_operation_capture "https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts"
click node_soft_delete "https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts"
click node_field_diff "https://github.com/granitebps/mongoose-log-history/blob/main/src/change-tracking.ts"
click node_context_user "https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts"
click node_value_helpers "https://github.com/granitebps/mongoose-log-history/blob/main/src/utils.ts"
click node_log_entry "https://github.com/granitebps/mongoose-log-history/blob/main/src/schema.ts"
click node_log_model "https://github.com/granitebps/mongoose-log-history/blob/main/src/schema.ts"
click node_snapshot_compression "https://github.com/granitebps/mongoose-log-history/blob/main/src/compression.ts"
click node_pruning "https://github.com/granitebps/mongoose-log-history/blob/main/src/prune.ts"
click node_manual_helpers "https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts"
click node_public_types "https://github.com/granitebps/mongoose-log-history/blob/main/src/types.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_api,node_schema_hooks toneBlue
class node_operation_capture,node_soft_delete,node_field_diff,node_context_user toneAmber
class node_log_entry,node_log_model,node_mongo_store toneMint
class node_value_helpers,node_snapshot_compression,node_pruning,node_manual_helpers,node_public_types toneRose
class node_application toneIndigo
```

## Components

### Mongoose integration

- [Plugin API](https://github.com/granitebps/mongoose-log-history/blob/main/src/index.ts): `src/index.ts`
- [Model hooks](https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts): `src/plugin.ts`

### Change capture

- [CRUD and bulk capture](https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts): `src/plugin.ts`
- [Soft-delete detection](https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts): `src/plugin.ts`
- [Field and array diffs](https://github.com/granitebps/mongoose-log-history/blob/main/src/change-tracking.ts): `src/change-tracking.ts`
- [Context and user data](https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts): `src/plugin.ts`

### History storage

- [Log entry schema](https://github.com/granitebps/mongoose-log-history/blob/main/src/schema.ts): `src/schema.ts`
- [Log model selection](https://github.com/granitebps/mongoose-log-history/blob/main/src/schema.ts): `src/schema.ts`
- **MongoDB log collections**

### Helpers and API

- [Value utilities](https://github.com/granitebps/mongoose-log-history/blob/main/src/utils.ts): `src/utils.ts`
- [Snapshot compression](https://github.com/granitebps/mongoose-log-history/blob/main/src/compression.ts): `src/compression.ts`
- [History pruning](https://github.com/granitebps/mongoose-log-history/blob/main/src/prune.ts): `src/prune.ts`
- [Manual logging helpers](https://github.com/granitebps/mongoose-log-history/blob/main/src/plugin.ts): `src/plugin.ts`
- [Typed configuration](https://github.com/granitebps/mongoose-log-history/blob/main/src/types.ts): `src/types.ts`

### Other components

- **Application**

## Connections

- Application → Plugin API: applies plugin (evidence: `README.md`)
- Plugin API → Model hooks: exports plugin (evidence: `src/index.ts`)
- Model hooks → CRUD and bulk capture: registers hooks (evidence: `src/plugin.ts`)
- Model hooks → Log model selection: selects log model (evidence: `src/plugin.ts`)
- CRUD and bulk capture → Soft-delete detection: detects transition (evidence: `src/plugin.ts`)
- CRUD and bulk capture → Field and array diffs: calculates changes (evidence: `src/plugin.ts`)
- CRUD and bulk capture → Context and user data: extracts metadata (evidence: `src/plugin.ts`)
- Field and array diffs → Value utilities: uses utilities (evidence: `src/change-tracking.ts`)
- Model hooks → Snapshot compression: compresses snapshots (evidence: `src/plugin.ts`)
- Model hooks → Log entry schema: builds entries (evidence: `src/plugin.ts`)
- Log model selection → MongoDB log collections: models collections (evidence: `src/schema.ts`)
- Application → History pruning: requests pruning (evidence: `README.md`)
- History pruning → Log model selection: selects history model (evidence: `src/prune.ts`)
- Application → Manual logging helpers: calls helpers (evidence: `README.md`)
- Plugin API → Typed configuration: exports types (evidence: `src/index.ts`)