# yelmuratoff/ispect architecture

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

- Interactive diagram: https://gitdiagram.com/yelmuratoff/ispect
- Repository: https://github.com/yelmuratoff/ispect

## Overview

##### Project Type and Purpose
- Monorepo of modular Dart/Flutter packages
- Purpose: provide an in-app debug panel (ISpect) + logging backbone (ISpectify) + adapters for HTTP, Dio, WebSocket, DB, BLoC, Jira + example apps + CLI tooling + automation scripts
- Consumers: Flutter app developers who integrate these packages into their applications for debugging, monitoring, and reporting

##### File Structure
Top‐level directories:
- .github/workflows → CI/CD pipelines for publishing and version sync
- bash → release & pre-commit scripts (version bump, changelog, dependency checks)
- docs, licences → documentation and license artifacts
- packages/… → individual Dart/Flutter packages (ispect, ispectify, ispectify_dio, …, ispect_jira)
- readme_generator → CLI tool to auto‐generate README files per package
- web_logs_viewer → standalone Flutter web app to view JSON logs
Patterns:
- Each package follows lib/src/common, core, features, presentation, services, test
- Modular layering: common utilities, domain models, feature slices

##### README for Additional Insights
- “Architecture” section calls out each package’s role
- Core panel (ispect), logging backbone (ispectify), adapters (ispectify_*)
- Integration flow: wrap your app in ISpectBuilder, attach interceptors/observers

##### Main Components
A. Host Application (Flutter App)
– Entry point: main.dart
– Wraps MaterialApp in ISpect.run & ISpectBuilder
B. Core Panel Module (packages/ispect)
– UI layer: panel, cards, dialogs, widget tree inspector
– Controllers & services for logs, performance, device info
C. Logging Backbone (packages/ispectify)
– Produces log events, history storage, console forwarding
– Filter, redaction, formatting utilities
D. Adapters / Integrations
– HTTP: ispectify_http (http package interceptor)
– Dio: ispectify_dio (Dio interceptor)
– WebSocket: ispectify_ws
– Database: ispectify_db (sqflite wrapper)
– BLoC: ispectify_bloc (BlocObserver)
– Jira: ispect_jira (CUBIT + JiraClient + UI to send issues)
E. Storage & History
– In-memory/event stream + optional file history (daily_file_history)
F. Example Apps
– Flutter example under each package → demonstrate usage patterns
– web_logs_viewer: standalone web app visualizing JSON logs
G. Tooling & Pipelines
– readme_generator: Dart CLI to scaffold/update READMEs
– bash scripts: version bump, changelog, pre-commit hooks
– GitHub Actions: deploy, sync versions, validate versions

##### Relationships & Data Flows
- Host App → ISpect.run
- onInit callback → attach interceptors to HTTP/Dio/WS/DB clients + set Bloc.observer
- Adapters intercept traffic/events → forward to ISpectify logger
- ISpectify logger → stores events → exposes event stream
- ISpect panel controllers subscribe → render UI widgets in overlay
- Optionally: ISpectify logger writes to file (daily_file_history)
- readme_generator and bash pipelines operate offline on packages → update docs & version files

##### Architectural Patterns & Principles
- Modular Monorepo: each package independently versioned & published
- Layered Architecture: common → core → features → presentation
- Adapter / Strategy Pattern: interceptors for different protocols
- Observer Pattern: event streams for real-time UI updates
- Flag-driven Initialization: tree-shaken in production builds
- Separation of Concerns: logging backbone vs UI vs integration

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Host Application" 
    HostMain["main.dart"]:::hostapp
    HostQuick["main_quick.dart"]:::hostapp
  end

  subgraph "Adapters" 
    HTTPAdapter["ispectify_http"]:::library
    DioAdapter["ispectify_dio"]:::library
    WSAdapter["ispectify_ws"]:::library
    DBAdapter["ispectify_db"]:::library
    BlocAdapter["ispectify_bloc"]:::library
    JiraAdapter["ispect_jira"]:::library
  end

  subgraph "Logging Backbone (ISpectify)" 
    IspectifyLib["lib"]:::library
    IsoHistory["file_log_history.dart"]:::library
  end

  subgraph "Core Panel (ISpect)" 
    CoreSrc["lib/src"]:::library
    CoreCommon["lib/src/common"]:::library
    CoreFeatures["lib/src/features"]:::library
    CoreHistory["daily_file_history.dart"]:::library
  end

  subgraph "Example Apps" 
    ExISpect["packages/ispect/example"]:::hostapp
    ExIspectify["packages/ispectify/example"]:::hostapp
    ExHTTP["packages/ispectify_http/example"]:::hostapp
    ExDio["packages/ispectify_dio/example"]:::hostapp
    ExWS["packages/ispectify_ws/example"]:::hostapp
    ExDB["packages/ispectify_db/example"]:::hostapp
    ExJira["packages/ispect_jira/example"]:::hostapp
    WebViewer["web_logs_viewer/lib/main.dart"]:::hostapp
  end

  subgraph "Tooling & CI" 
    ReadmeGen["generate_readme.dart"]:::tooling
    BashScripts["bash/"]:::tooling
    GitHubActions[".github/workflows/"]:::tooling
  end

  HostMain -->|"onInit attach"| HTTPAdapter
  HostMain -->|"onInit attach"| DioAdapter
  HostMain -->|"onInit attach"| WSAdapter
  HostMain -->|"onInit attach"| DBAdapter
  HostMain -->|"onInit attach"| BlocAdapter
  HostMain -->|"onInit attach"| JiraAdapter

  HTTPAdapter -->|"forwards events"| IspectifyLib
  DioAdapter -->|"forwards events"| IspectifyLib
  WSAdapter -->|"forwards events"| IspectifyLib
  DBAdapter -->|"forwards events"| IspectifyLib
  BlocAdapter -->|"forwards events"| IspectifyLib
  JiraAdapter -->|"forwards events"| IspectifyLib

  IspectifyLib -->|"event stream"| CoreSrc
  IspectifyLib -->|"writes to file"| IsoHistory
  CoreSrc --> CoreCommon
  CoreSrc --> CoreFeatures
  CoreCommon --> CoreHistory

  classDef hostapp fill:#e0ffe0,stroke:#2ca02c
  classDef library fill:#e0f0ff,stroke:#1f77b4
  classDef external fill:#dddddd,stroke:#888888
  classDef tooling fill:#fff5e6,stroke:#ff7f0e

  click HostMain "https://github.com/yelmuratoff/ispect/blob/main/packages/ispect/example/lib/main.dart"
  click HostQuick "https://github.com/yelmuratoff/ispect/blob/main/packages/ispect/example/lib/main_quick.dart"
  click CoreSrc "https://github.com/yelmuratoff/ispect/tree/main/packages/ispect/lib/src"
  click CoreCommon "https://github.com/yelmuratoff/ispect/tree/main/packages/ispect/lib/src/common"
  click CoreFeatures "https://github.com/yelmuratoff/ispect/tree/main/packages/ispect/lib/src/features/ispect"
  click CoreHistory "https://github.com/yelmuratoff/ispect/blob/main/packages/ispect/lib/src/common/history/daily_file_history.dart"
  click IspectifyLib "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify/lib"
  click IsoHistory "https://github.com/yelmuratoff/ispect/blob/main/packages/ispectify/lib/src/history/file_log/file_log_history.dart"
  click HTTPAdapter "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_http/lib"
  click DioAdapter "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_dio/lib"
  click WSAdapter "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_ws/lib"
  click DBAdapter "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_db/lib"
  click BlocAdapter "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_bloc/lib"
  click JiraAdapter "https://github.com/yelmuratoff/ispect/tree/main/packages/ispect_jira/lib"
  click ExISpect "https://github.com/yelmuratoff/ispect/tree/main/packages/ispect/example"
  click ExIspectify "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify/example"
  click ExHTTP "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_http/example"
  click ExDio "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_dio/example"
  click ExWS "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_ws/example"
  click ExDB "https://github.com/yelmuratoff/ispect/tree/main/packages/ispectify_db/example"
  click ExJira "https://github.com/yelmuratoff/ispect/tree/main/packages/ispect_jira/example"
  click WebViewer "https://github.com/yelmuratoff/ispect/blob/main/web_logs_viewer/lib/main.dart"
  click ReadmeGen "https://github.com/yelmuratoff/ispect/blob/main/readme_generator/generate_readme.dart"
  click BashScripts "https://github.com/yelmuratoff/ispect/tree/main/bash/"
  click GitHubActions "https://github.com/yelmuratoff/ispect/tree/main/.github/workflows/"
```
