# TODO:

# DOCUMENTATION OF PROJECT AND PLUGGINS IN read the docs

## PYNMON Coding Guidelines

- Type hints are mandatory for all function parameters and return values
- Use built-in types (`list`, `dict`, `tuple`, etc.) — no `typing.List`, `typing.Dict`, etc.
- Document "why" not "what" in comments
- Class and function docstrings should explain purpose and behavior concisely
- Keep functions focused and concise
- Keep inline comments sparse and only for non-obvious intent
- **Limit functions to 20 lines and no more than 3 indentation levels**
- **Keep modules under 400 lines** by splitting features into dedicated files and grouping related logic
- Favor multiple tiny CSS/template files over a single large one; reuse shared snippets
- **No raw dicts for structured data** — use `dataclass` (or `NamedTuple`) so every field is typed and discoverable. Dicts are only acceptable for truly dynamic/unknown-shape data (e.g., MongoDB documents). Config, status objects, API responses between layers, and any data passed between functions must be typed dataclasses.
- Avoid long parameter lists; use `dataclass` bundles with minimal logic and keep business logic in stateless helper functions
- **Always async** — never block the event loop. All route handlers must be `async def`. Wrap synchronous work (DB queries, subprocess calls, file I/O) with `asyncio.to_thread()`. For long-running background work use `asyncio.create_task()`. The backend must stay responsive at all times.

## Mandatory Maintenance on Every Edit

Every time you modify a file in this module you MUST check and enforce these limits before finishing:

1. **Function length** — If any function exceeds 20 lines, extract helpers until it fits. No exceptions.
2. **Indentation depth** — If any code path reaches 4+ indentation levels, refactor into a separate function. Increasing indentation depth for new functionality is NOT allowed; it means a new function is needed.
3. **Module length** — If any `.py` file exceeds 400 lines, split it. Move related functions into a new file (e.g., `analysis.py` → `analysis.py` + `analysis_helpers.py`, or by domain concept).
4. **Parameter lists** — If a function has more than 5 parameters, bundle them into a `NamedTuple` or `dataclass`.

These are not aspirational goals — they are hard limits. Refactor proactively on every edit to keep the codebase within bounds. Do not defer cleanup to a future task.
git push
