AGENTS.md

Purpose

This document outlines general practices and expectations for AI agents assisting with the development of ngxstat, a hybrid log analytics tool for Nginx. The agent’s role includes writing code, testing functionality, and generating documentation, with particular attention to the following technologies and design choices.

Project Overview

Project Name: ngxstat Goal: Per-domain log analysis for Nginx with a hybrid of statically generated reports and lightweight live JSON API endpoints.

Stack & Tooling

Python

Version: 3.10+ recommended
Project isolation: Use venv
```
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
The run-import.sh script can initialize this environment automatically. Always activate the virtual environment before running scripts or tests.

Dependency management: Use requirements.txt or pip-tools
Use standard libraries where feasible (e.g., sqlite3, argparse, datetime)
Adopt typer for CLI command interface (if CLI ergonomics matter)

SQLite

Used for log ingestion and aggregation
Prefer raw SQL or use lightweight ORM (e.g., dataset, sqlite-utils) only if necessary
Index columns used in groupings (e.g., timestamp, domain, status, cache result)

Charting: Chart.js

Use latest CDN version for embedded dashboards
Charts should be rendered from pre-generated JSON blobs in /json/

Tables: DataTables

Use DataTables via CDN for reports with chart: table
Requires jQuery from a CDN
Table data comes from the same /json/ files as charts

Styling: Bulma CSS

Use via CDN or vendored minified copy (to keep reports fully static)
Stick to default components (columns, cards, buttons, etc.)
No JS dependencies from Bulma

Icon Set: Free CC0 Icons (CC0)

License: MIT / CC0-like
Use SVG versions
Download as:
- Individual SVGs in /static/icons/, or
- Pre-bundled sprite/minified set if needed

📄 File Structure Guidelines

ngxstat/
├── scripts/            # Log importers, SQLite tools
├── templates/          # Jinja2 templates for static page generation
├── static/             # CSS, JS, icons (Chart.js, Bulma, icons)
├── output/             # Generated reports
├── database/           # SQLite DBs and schema migrations
├── api/                # Lightweight live API server (Flask/FastAPI)
├── AGENTS.md           # This file
├── README.md

Agentic Behavior Expectations

Code must be modular and documented.
Use consistent naming and formatting.
Err on the side of clarity over cleverness.
Avoid introducing unnecessary dependencies.
Validate SQL statements when modifying schema.
Verify that logs parse cleanly and reject malformed lines.

If uncertain, the agent should prompt the human for clarification before making architectural assumptions.

Future Capabilities

As the project matures, agents may also:

Suggest aggregation logic (e.g., bot detection, per-path stats)
Help build a Dockerized deployable version
Expand dashboard with new view types or filters
Integrate log format autodetection heuristics

Changelog

2025-07-17: Initial version by Jordan + ChatGPT
2025-07-17: Expanded virtual environment usage guidance

3.4 KiB Raw Blame History Unescape Escape