Skip to content

Latest commit

 

History

History
35 lines (24 loc) · 3.17 KB

AGENTS.md

File metadata and controls

35 lines (24 loc) · 3.17 KB

OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open @/openspec/AGENTS.md when the request:

  • Mentions planning or proposals (words like proposal, spec, change, plan)
  • Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
  • Sounds ambiguous and you need the authoritative spec before coding

Use @/openspec/AGENTS.md to learn:

  • How to create and apply change proposals
  • Spec format and conventions
  • Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

Repository Guidelines

Project Structure & Module Organization

The Jmix/Spring backend lives in src/main/java with Flow UI views grouped by feature package. Shared messages and Vaadin themes sit under src/main/resources, while environment-specific configs (application-dev.properties, application-prod.properties, etc.) control data sources and AWS/S3 settings. Tests mirror the backend tree in src/test/java. Web assets, React/Vaadin components, and generated TypeScript live in frontend/, with build artifacts ending up in build/ (Gradle) and target/. Keep significant design docs or product notes in docs/.

Build, Test & Local Development

Run ./gradlew bootRun for a full-stack dev server; it wires the Flow UI frontend and backend APIs together. ./gradlew build produces the production-ready JAR and triggers Vaadin’s vite build. Use ./gradlew test for the backend suite, and npx vite dev --config vite.config.ts inside frontend/ when you need a standalone UI preview. Always run npm install before touching front-end dependencies so the generated VAADIN assets stay in sync.

Coding Style & Naming Conventions

Java uses 4-space indentation, Lombok annotations for DTOs, and the standard Spring naming (*Service, *Repository, *View). Favor package-by-domain organization rather than technical layers. TypeScript/JS files are formatted with 2 spaces and should export PascalCase components. Keep Vaadin routes in frontend/routes.ts, translations in src/main/resources/messages.properties, and name data migrations descriptively (e.g., V20250212__normalize_contacts.groovy).

Testing Guidelines

Prefer JUnit 5 with @SpringBootTest for integrations and FlowuiTestAssist utilities for view logic. Unit test classes should mirror the class under test with a Test suffix (CustomerServiceTest). Add focused UI tests when adding new navigation routes or BPM integrations. Failing tests block CI, so run ./gradlew test before every push; add smoke assertions on new background jobs and cover null/edge cases in DTO mappers.

Commit & Pull Request Guidelines

Follow the lightweight conventional style visible in history (feat:, fix:, chore:). Keep subject lines under 72 characters and describe the reasoning in the body when touching infrastructure or schema. Every PR needs: a short summary, references to Jira/GitHub issues, screenshots/GIFs for UI changes, and notes on manual test steps or migration impacts. Request reviews from both backend and Flow UI owners when the change spans Java and TypeScript.