AI Agent Guidelines

AI Agent Guidelines - For Web Applications.md

Agent Guidelines

This project is a web application with a Rust (Actix-web) backend and a VueJS frontend.

Architecture

• Backend: Rust, Actix-web, SQLx (Postgres).
• Frontend: Vue 3, Tailwind CSS, Pinia.
• Observability: Prometheus, Grafana, Alertmanager. Structured logs in JSON.
• Config: 15-factor app. Env vars via Doppler or .env.

Development

• TDD: Always write tests first for any change or feature.
• SOLID: Strictly follow SOLID principles in backend development:
  • SRP: Each module/service/function must have a single responsibility.
  • OCP: Design for extension without modification (e.g., use registries/factories).
  • LSP: Ensure derived types are substitutable for their base types.
  • ISP: Use specific traits rather than large, generic ones.
  • DIP: High-level modules should depend on abstractions (traits), not concrete implementations.
• Database: Use migrations in backend/migrations.
• API: Follow OpenAPI/Swagger standards. Annotate controllers with utoipa.
• Auth: Use OAuth2 and JWT.

Notification Systems

• Email: Uses SMTP. For dev, use Mailpit (Port 1025).
• Webhooks: Supports Basic, Bearer, and JSON/XML payloads.
• Push: Web Browser Push Notifications via VAPID.

Setup

• Run docker-compose up -d for dev services.
• Backend default port: 8080.
• Frontend default port: 5173 (Vite).

Agent Operations

• Output Capture: Use the ./agent-output folder to capture any output from tasks, processes, or commands. This folder is ignored by Git.

Code Style

• Follow standard Rust and Vue/JS conventions.
• Use tracing for logging in Rust.