# pccria/logd architecture

> Architecture diagram of the GitHub repository pccria/logd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pccria/logd
- Repository: https://github.com/pccria/logd

## Overview

logd is a Dart/Flutter structured logging engine and package family. Applications create hierarchical loggers, emit contextual entries, and route them to handlers and destinations; formatting and optional background-isolate processing support that path. The README also documents specialized HTTP inspection, compact TOON output, HTML/Markdown rendering, SQLite persistence, and network shipping/dashboard capabilities. Core source was not sampled, so core relationships below rely on README statements; satellite package internals and their wiring are represented only at package-directory level.

Main entry points: [`packages/logd/lib/src/handler/handler.dart`](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/handler.dart) (Handler Routing), [`packages/logd/lib/src/logger/logger.dart`](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/logger.dart) (Hierarchical Logger), [`packages/logd_network/lib`](https://github.com/pccria/logd/tree/master/packages/logd_network/lib) (Network Shipping), [`packages/logd_dio/lib`](https://github.com/pccria/logd/tree/master/packages/logd_dio/lib) (Dio Inspection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_logging["Logging Core"]
  node_logger["Hierarchical Logger<br/>[logger.dart]"]
  node_context["Ambient Context<br/>[log_context.dart]"]
  node_entry["Log Entries<br/>[log_entry.dart]"]
  node_buffer["Log Buffer<br/>[log_buffer.dart]"]
end

subgraph group_processing["Handler Processing"]
  node_handlers["Handler Routing<br/>[handler.dart]"]
  node_filters["Filtering"]
  node_formatters["Formatters"]
  node_async["Async Offload<br/>[async_handler.dart]"]
  node_sinks["Core Sinks"]
end

subgraph group_outputs["Output Packages"]
  node_console["Console Output"]
  node_toon["TOON Output"]
  node_html["HTML Sessions"]
  node_markdown["Markdown Output"]
  node_sqlite[("SQLite Store")]
  node_network["Network Shipping"]
  node_dashboard["Browser Dashboard"]
end

subgraph group_integrations["Integrations"]
  node_dio["Dio Inspection"]
end

node_app(("Dart / Flutter App"))
node_http_service["HTTP Service"]
node_websocket_service["WebSocket Service"]
node_http_demo["HTTP Log Receiver<br/>[main.py]"]
node_socket_demo["Socket Log Receiver<br/>[main.py]"]

node_app -->|"emits logs"| node_logger
node_logger -->|"propagates context"| node_context
node_logger -->|"routes logs"| node_handlers
node_logger -.->|"creates entries"| node_entry
node_logger -.->|"buffers logs"| node_buffer
node_handlers -.->|"filters records"| node_filters
node_handlers -.->|"formats records"| node_formatters
node_handlers -->|"offloads work"| node_async
node_handlers -.->|"writes output"| node_sinks
node_handlers -->|"routes to"| node_console
node_handlers -->|"routes to"| node_toon
node_handlers -->|"routes to"| node_html
node_handlers -->|"routes to"| node_markdown
node_handlers -->|"persists to"| node_sqlite
node_handlers -->|"ships logs"| node_network
node_network -->|"streams to"| node_dashboard
node_network -->|"ships batches"| node_http_service
node_network -->|"streams logs"| node_websocket_service
node_app -->|"inspects HTTP"| node_dio
node_dio -->|"forwards traces"| node_context
node_http_service -.->|"receives POST"| node_http_demo
node_websocket_service -.->|"receives stream"| node_socket_demo

click node_logger "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/logger.dart"
click node_context "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/log_context.dart"
click node_entry "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/log_entry.dart"
click node_buffer "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/log_buffer.dart"
click node_handlers "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/handler.dart"
click node_filters "https://github.com/pccria/logd/tree/master/packages/logd/lib/src/handler/filter"
click node_formatters "https://github.com/pccria/logd/tree/master/packages/logd/lib/src/handler/formatter"
click node_async "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/engine/async_handler.dart"
click node_sinks "https://github.com/pccria/logd/tree/master/packages/logd/lib/src/handler/sink"
click node_console "https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/target_handlers/console_handler.dart"
click node_toon "https://github.com/pccria/logd/tree/master/packages/logd_toon/lib"
click node_html "https://github.com/pccria/logd/tree/master/packages/logd_html/lib"
click node_markdown "https://github.com/pccria/logd/tree/master/packages/logd_markdown/lib"
click node_sqlite "https://github.com/pccria/logd/tree/master/packages/logd_sqlite/lib"
click node_network "https://github.com/pccria/logd/tree/master/packages/logd_network/lib"
click node_dashboard "https://github.com/pccria/logd/tree/master/packages/logd_network/lib"
click node_dio "https://github.com/pccria/logd/tree/master/packages/logd_dio/lib"
click node_http_demo "https://github.com/pccria/logd/blob/master/scripts/servers/http/main.py"
click node_socket_demo "https://github.com/pccria/logd/blob/master/scripts/servers/socket/main.py"

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_logger,node_context,node_entry,node_buffer toneBlue
class node_handlers,node_filters,node_formatters,node_async,node_sinks toneAmber
class node_console,node_toon,node_html,node_markdown,node_sqlite,node_network,node_dashboard toneMint
class node_dio toneRose
class node_app,node_http_service,node_websocket_service toneIndigo
class node_http_demo,node_socket_demo toneTeal
```

## Components

### Logging Core

- [Hierarchical Logger](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/logger.dart): `packages/logd/lib/src/logger/logger.dart`
- [Ambient Context](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/log_context.dart): `packages/logd/lib/src/logger/log_context.dart`
- [Log Entries](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/log_entry.dart): `packages/logd/lib/src/logger/log_entry.dart`
- [Log Buffer](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/logger/log_buffer.dart): `packages/logd/lib/src/logger/log_buffer.dart`

### Handler Processing

- [Handler Routing](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/handler.dart): `packages/logd/lib/src/handler/handler.dart`
- [Filtering](https://github.com/pccria/logd/tree/master/packages/logd/lib/src/handler/filter): `packages/logd/lib/src/handler/filter`
- [Formatters](https://github.com/pccria/logd/tree/master/packages/logd/lib/src/handler/formatter): `packages/logd/lib/src/handler/formatter`
- [Async Offload](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/engine/async_handler.dart): `packages/logd/lib/src/handler/engine/async_handler.dart`
- [Core Sinks](https://github.com/pccria/logd/tree/master/packages/logd/lib/src/handler/sink): `packages/logd/lib/src/handler/sink`

### Output Packages

- [Console Output](https://github.com/pccria/logd/blob/master/packages/logd/lib/src/handler/target_handlers/console_handler.dart): `packages/logd/lib/src/handler/target_handlers/console_handler.dart`
- [TOON Output](https://github.com/pccria/logd/tree/master/packages/logd_toon/lib): `packages/logd_toon/lib`
- [HTML Sessions](https://github.com/pccria/logd/tree/master/packages/logd_html/lib): `packages/logd_html/lib`
- [Markdown Output](https://github.com/pccria/logd/tree/master/packages/logd_markdown/lib): `packages/logd_markdown/lib`
- [SQLite Store](https://github.com/pccria/logd/tree/master/packages/logd_sqlite/lib): `packages/logd_sqlite/lib`
- [Network Shipping](https://github.com/pccria/logd/tree/master/packages/logd_network/lib): `packages/logd_network/lib`
- [Browser Dashboard](https://github.com/pccria/logd/tree/master/packages/logd_network/lib): `packages/logd_network/lib`

### Integrations

- [Dio Inspection](https://github.com/pccria/logd/tree/master/packages/logd_dio/lib): `packages/logd_dio/lib`

### Other components

- **Dart / Flutter App**
- **HTTP Service**
- **WebSocket Service**
- [HTTP Log Receiver](https://github.com/pccria/logd/blob/master/scripts/servers/http/main.py): `scripts/servers/http/main.py`
- [Socket Log Receiver](https://github.com/pccria/logd/blob/master/scripts/servers/socket/main.py): `scripts/servers/socket/main.py`

## Connections

- Dart / Flutter App → Hierarchical Logger: emits logs (evidence: `README.md`)
- Hierarchical Logger → Ambient Context: propagates context (evidence: `README.md`)
- Hierarchical Logger → Handler Routing: routes logs (evidence: `README.md`)
- Hierarchical Logger → Log Entries: creates entries
- Hierarchical Logger → Log Buffer: buffers logs
- Handler Routing → Filtering: filters records
- Handler Routing → Formatters: formats records
- Handler Routing → Async Offload: offloads work (evidence: `README.md`)
- Handler Routing → Core Sinks: writes output
- Handler Routing → Console Output: routes to (evidence: `README.md`)
- Handler Routing → TOON Output: routes to (evidence: `README.md`)
- Handler Routing → HTML Sessions: routes to (evidence: `README.md`)
- Handler Routing → Markdown Output: routes to (evidence: `README.md`)
- Handler Routing → SQLite Store: persists to (evidence: `README.md`)
- Handler Routing → Network Shipping: ships logs (evidence: `README.md`)
- Network Shipping → Browser Dashboard: streams to (evidence: `README.md`)
- Network Shipping → HTTP Service: ships batches (evidence: `README.md`)
- Network Shipping → WebSocket Service: streams logs (evidence: `README.md`)
- Dart / Flutter App → Dio Inspection: inspects HTTP (evidence: `README.md`)
- Dio Inspection → Ambient Context: forwards traces (evidence: `README.md`)
- HTTP Service → HTTP Log Receiver: receives POST
- WebSocket Service → Socket Log Receiver: receives stream
