docs: Update AGENTS.md

[overcut-ai]

Summary

This PR adds the new AGENTS guide that documents the structure, workflows, and conventions for the amplication/sample-app monorepo.

Changes

• document project overview, technologies, and layout
• outline backend and frontend development patterns with key scripts
• capture reference paths, naming conventions, and operational guidelines

Why

Keeping AGENTS.md current provides contributors with an accurate onboarding reference for this repository, reducing ramp-up time and clarifying service-specific workflows.

Summary

This PR adds a comprehensive AGENTS.md guide that documents the architecture, tooling, and workflows for the ecommerce, logistics, and admin services in the monorepo. It centralizes onboarding context, outlining service layouts, environment requirements, and operational safeguards for future contributors.

Changes

• Documentation: Added a dedicated AGENTS guide describing the project overview, technologies, and repository structure.
• Documentation: Detailed backend and frontend development workflows, including per-app commands, environment setup, and bootstrap steps.
• Documentation: Captured testing expectations, operational guidelines, and reference examples to keep service conventions aligned.

Commits

• 158aad8 docs: update AGENTS.md

Testing

• Review AGENTS.md for accuracy against the current service structure, scripts, and tooling.
• Verify each referenced command or workflow exists within the corresponding service directories.
• Share the guide with an onboarding contributor to ensure it covers the expected workflows and conventions.

[overcut-ai]

Completed Working on "Auto PR Description"

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

❌ Workflow Failed: "Auto PR Description"

The workflow encountered an error and could not complete successfully.

Error: Step prepare-pr-description failed

---

👉 View complete log

[overcut-ai]

2 MAJOR, 1 MINOR findings across this documentation update. Key themes: the new AGENTS guide diverges from the actual frontend/backend configurations (wrong Vite env var name, inaccurate dev server port) and recommends a Docker shutdown command that deletes local data. Please align the env var names with the Vite implementation, correct or enforce the documented dev server port, and either adjust or clearly warn about the destructive compose:down script so contributors are not misled during setup.

[overcut-ai]

[MAJOR]: Section 3 line 20 and Section 5 line 36 instruct contributors to set REACT_APP_SERVER_URL, but the Vite admin actually consumes import.meta.env.VITE_REACT_APP_SERVER_URL (see apps/ecommerce-admin/src/data-provider/graphqlDataProvider.ts L6-L8 and .env L1-L2). Following the guide leaves the GraphQL client pointing to undefined/graphql, so the UI cannot talk to the backend when onboarding new agents.

Suggested fix: Update every frontend environment reference to VITE_REACT_APP_SERVER_URL (and explain that both the login shortcuts and the GraphQL data provider rely on that name) so the documented setup matches the actual env file and build tooling.

[overcut-ai]

[MINOR]: The frontend command table (line 72) claims npm run start serves Vite on port 3001, but apps/ecommerce-admin/package.json (L16) just runs vite and vite.config.ts (L5-L13) never overrides server.port, so the dev server actually binds to Vite’s default 5173. This misleads anyone wiring proxies or env files based on the guide.

Suggested fix: Either correct the guide to state the real default port (5173) or add server: { port: 3001 } to vite.config.ts so the command behaves as documented.

[overcut-ai]

[MAJOR]: The backend command table (line 56) treats npm run compose:down as the routine way to stop the stack, but both backend packages define that script as docker-compose down --volumes (apps/ecommerce-server/package.json L18-L19 and the logistic variant). Running it as documented wipes the Postgres/MySQL and Kafka volumes every time contributors bring services down, forcing them to recreate databases, reapply migrations, and reseed brokers unexpectedly.

Suggested fix: Either update the guide to warn that compose:down destroys volumes or change the script to a plain docker-compose down and create a separate compose:down:clean for destructive resets.