How chiphuyen/sniffly works
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