# chiphuyen/sniffly architecture

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

- Interactive diagram: https://gitdiagram.com/chiphuyen/sniffly
- Repository: https://github.com/chiphuyen/sniffly

## Overview

##### Project type and purpose
- Sniffly is a full-stack analytics dashboard tool for Claude Code.
- It consists of:
- A command-line interface (CLI) to initialize and configure the service
- A Python-based web server that processes logs, serves a dynamic dashboard, and provides an API
- A static “gallery/share” site built with serverless functions (for sharing dashboards publicly)

##### File structure
- Top-level:
- sniffly/ : core Python package
- sniffly-site/ : static site source + Netlify-style serverless functions
- assets/ : screenshots and feature images
- docs/ : developer docs and CLI reference
- CI config in .github/workflows
- pyproject.toml, requirements.txt, lint/test scripts
- sniffly/ layers:
- sniffly/cli.py  → CLI commands (init, config, share)
- sniffly/server.py  → Web server entry point
- sniffly/api/  → REST API handlers (data, messages, shares)
- sniffly/core/  → Processing pipeline (loader, aggregator, stats)
- sniffly/services/  → External logic (e.g., pricing calculation)
- sniffly/utils/  → Caching, logging, file discovery
- sniffly/templates & static/  → Jinja2 HTML views + JS/CSS assets
- sniffly-site/ layers:
- build.py  → Static site generator (gallery + share templates)
- functions/api/*  → Serverless endpoints (Netlify) for public gallery & share data
- gallery-site-server.py & local-dev-*.py  → Local dev servers mirroring production functions
- static/js, static/css, share-template.html  → Frontend code for shared dashboards

##### README for additional insights
- Describes features: usage patterns, error breakdown, message history
- Quickstart: CLI via UV or pip; launches web server on localhost:8081
- Configuration via CLI (port, host, caching)
- “Sharing” flow: user clicks “Share” in dashboard → generated link → public gallery or private share
- Privacy: all processing local, share is opt-in

a. Main components
- User’s machine & CLI
- Local data store (JSONL logs + in-memory cache)
- Processing engine (core loader, aggregator, processor)
- Web server (sniffly/server.py) hosting:
- API layer (sniffly/api)
- Templates & static assets (sniffly/templates, sniffly/static)
- Browser UI
- Static gallery/share site:
- Build pipeline (build.py)
- Serverless functions (Netlify)
- Static hosting (Netlify or similar)
- External CI/CD (GitHub workflows, PyPI publishing)
b. Relationships & interactions
1. User runs `sniffly init` (CLI) → reads config, loads logs from disk → starts Python web server
2. Browser requests dashboard → server endpoints serve HTML + JS/CSS → JS calls REST APIs → server queries in-memory cache/processes logs
3. “Share” button → client posts share data to server → server triggers build or calls serverless function to store share snapshot → returns share URL
4. Public share URL resolves to static site hosted on CDN → serverless function fetches snapshot data → renders share UI
5. CI pipelines run lint/test/build → publish package to PyPI or deploy serverless functions
c. Architectural patterns & design principles
- MVC:
– Model: log data (JSONL), in-memory cache, pricing data
– View: Jinja2 templates + static JS/CSS
– Controller: REST API handlers in sniffly/api
- Modular layering: CLI, core processing, services, API, UI
- Serverless micro-endpoints for share/gallery decoupled from main server
- Configuration via environment or CLI writes to `~/.sniffly/config.json`
d. Key technologies/frameworks
- Python 3.10+, uvicorn (via UV)
- FastAPI or Flask-style routing in `sniffly/api` (could also be pure WSGI)
- Jinja2 templates for HTML
- Vanilla JS for charts and UI interactions
- Netlify functions (JavaScript) for static share/gallery
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Local Environment
    subgraph "Local Environment"
        direction TB
        CLI["CLI Interface"]:::external
        Config["Configuration Module"]:::backend
        Server["Web Server Entry Point"]:::backend
        subgraph "REST API Layer"
            direction TB
            DataAPI["Data API"]:::backend
            DataLoader["Data Loader Endpoint"]:::backend
            MessagesAPI["Messages API"]:::backend
        end
        subgraph "Processing Engine"
            direction TB
            Processor["Processor"]:::backend
            Aggregator["Global Aggregator"]:::backend
            Stats["Statistics"]:::backend
        end
        DataStore["Local Data Store (JSONL Logs + In-Memory Cache)"]:::backend
        subgraph "Templates & Static Assets"
            direction TB
            Templates["Jinja2 Templates"]:::frontend
            StaticJS["Static JS"]:::frontend
            StaticCSS["Static CSS"]:::frontend
            StaticImages["Static Images"]:::frontend
        end
        Browser["Browser UI"]:::frontend

        CLI -->|reads config| Config
        CLI -->|starts server| Server
        Server --> REST_API_Layer
        REST_API_Layer -->|calls| Processor
        Processor -->|loads & aggregates| DataStore
        Processor --> Aggregator
        Processor --> Stats
        Server --> Templates
        Server --> StaticJS
        Server --> StaticCSS
        Server --> StaticImages
        Browser -->|HTTP requests| Server
        Browser -->|API calls| DataAPI
        Browser -->|API calls| DataLoader
        Browser -->|API calls| MessagesAPI
    end

    %% Hosted/Public Environment
    subgraph "Hosted/Public Environment"
        direction TB
        Build["Static Site Generator"]:::backend
        subgraph "Serverless Functions"
            direction TB
            GalleryIndex["Gallery Index"]:::serverless
            SharesAPI["Shares API"]:::serverless
            RootFn["Root Endpoint"]:::serverless
            ShareViewer["Share Viewer"]:::serverless
        end
        CDN["CDN / Static Hosting"]:::serverless
        PublicBrowser["Public Browser"]:::frontend

        Build --> GalleryIndex
        Build --> SharesAPI
        Build --> RootFn
        Build --> ShareViewer
        GalleryIndex --> CDN
        SharesAPI --> CDN
        RootFn --> CDN
        ShareViewer --> CDN
        PublicBrowser --> CDN
        PublicBrowser --> SharesAPI
        PublicBrowser --> ShareViewer
    end

    %% CI/CD Pipeline
    CI["GitHub Workflows"]:::external
    CI -->|deploy| Build
    CI -->|deploy| GalleryIndex
    CI -->|publish| CLI

    %% Click Events
    click CLI "https://github.com/chiphuyen/sniffly/blob/main/sniffly/cli.py"
    click Config "https://github.com/chiphuyen/sniffly/blob/main/sniffly/config.py"
    click Server "https://github.com/chiphuyen/sniffly/blob/main/sniffly/server.py"
    click DataAPI "https://github.com/chiphuyen/sniffly/blob/main/sniffly/api/data.py"
    click DataLoader "https://github.com/chiphuyen/sniffly/blob/main/sniffly/api/data_loader.py"
    click MessagesAPI "https://github.com/chiphuyen/sniffly/blob/main/sniffly/api/messages.py"
    click Processor "https://github.com/chiphuyen/sniffly/blob/main/sniffly/core/processor.py"
    click Aggregator "https://github.com/chiphuyen/sniffly/blob/main/sniffly/core/global_aggregator.py"
    click Stats "https://github.com/chiphuyen/sniffly/blob/main/sniffly/core/stats.py"
    click GalleryIndex "https://github.com/chiphuyen/sniffly/blob/main/sniffly-site/functions/api/gallery-index.json.js"
    click SharesAPI "https://github.com/chiphuyen/sniffly/blob/main/sniffly-site/functions/api/shares.js"
    click RootFn "https://github.com/chiphuyen/sniffly/blob/main/sniffly-site/functions/index.js"
    click ShareViewer "https://github.com/chiphuyen/sniffly/blob/main/sniffly-site/functions/share/[[id]].js"
    click Build "https://github.com/chiphuyen/sniffly/blob/main/sniffly-site/build.py"

    %% Styles
    classDef backend fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef serverless fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#fbb,stroke:#333,stroke-width:1px
```
