AGENTS.md

This file provides information about this project and instructions on how to develop code for it.

Information

• The README.md file contains a section titled “Functionality” that describes the intended functionality of the application.

Commands

The application and its Pyenv environments are managed using a Makefile:

• make env-dev: Activates the Pyenv development environment. This must be done before executing any Python code.
• make run: Activates the Pyenv run environment and starts the development server using gunicorn with eventlet workers.
• make lint: Activates the Pyenv development environment and runs ruff to detect linting mistakes.
• make test: Activates the Pyenv development environment and runs all tests.
• make coverage: Provides a tabular overview of the test code coverage.
• Add new Python dependencies to requirements.base.txt without specifying versions, AND add them with version to requirements.txt. Then, run make envs to install these dependencies in all Pyenv environments.
• Always run make lint, make test and make coverage after making changes to verify the code is lint-free and tests pass and maintain coverage.

Dependencies

The project uses two requirements files:

• requirements.base.txt: Base dependencies without version constraints. Used by tox for testing environments. Always add new dependencies here first.
• requirements.txt: Locked dependencies with specific versions. Used by the runtime environment.

When adding a new dependency:

1. Add the package name to requirements.base.txt (no version)
2. Add the package with version to requirements.txt
3. Run make envs to update all environments

Architecture

The codebase is organized into two directories: modulename and tests.

• The module directory contains the main application logic.
• The tests directory contains unit and integration tests.

The application is built using Baseweb, a wrapper around Flask. It also provides a configured Flask-RESTful instance and access to Flask-SocketIO. Front-end support is provided through Vue and Vuetify. Backend Python code and frontend JavaScript code are kept together in a module directory, which is imported from the main application logic.

Best Practices to Strictly Follow

• VERY IMPORTANT: You MUST avoid using the Bash tool for search commands like find and grep. Instead use Grep, Glob, or Task to search.
• Always begin with an overview of your plan
• Always explain your actions before executing them.
• Always use two spaces for indentation in all file types.
• Always write tests for new functionality and integrate them into the tests directory.
• Ensure that all tests are working at all times.
• Maintain test coverage.
• Ensure that every exception in the backend code is captured gracefully and reported back to the client in a human readable format. Also log the problem with context.
• Ignore the .local folder.
• Ignore the notes folder.
• Continue working on unchecked tasks from the TODO.md file in a top-down manner. Treat each task as the next prompt to process. Cross the Markdown checkbox when a task is completed and move it to the bottom of the file. At the end of each task, request a review before proceeding to the next task.