120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# 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`
|
||
```bash
|
||
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.
|
||
|
||
* Before committing code run `black` for consistent formatting and execute
|
||
the test suite with `pytest`. All tests should pass.
|
||
|
||
* 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)](https://cc0-icons.jonh.eu/)
|
||
|
||
* 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
|
||
|
||
```plaintext
|
||
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.
|
||
|
||
## Testing
|
||
|
||
Use `pytest` for automated tests. Run the suite from an activated virtual environment and ensure all tests pass before committing:
|
||
|
||
```bash
|
||
pytest -q
|
||
```
|
||
|
||
---
|
||
|
||
## 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
|
||
|