docs: Update AGENTS.md

[overcut-ai]

🔄 Overcut automatically updated AGENTS.md with latest repository analysis.

Summary

This PR introduces a comprehensive AGENTS.md guide that documents the amplication/sample-app monorepo, outlining each service’s purpose, configuration, tooling, and recommended workflows. It centralizes environment variable references, messaging integrations, and security considerations to help contributors understand how to work safely across the generated services.

Changes

• Documentation: Added a detailed AGENTS guide describing project layout, technology stack, and how the three services relate.
• Documentation: Captured environment variable tables, tooling commands, and day-to-day development workflows for each service.
• Documentation: Documented Kafka/NATS integrations, testing expectations, and security guardrails to keep regenerated code safe.

Commits

• 520b759 docs: update AGENTS.md

Testing

• Review AGENTS.md for accuracy against the current repository structure and service READMEs.
• Validate that documented environment variables and scripts match the configurations inside each service’s package.json and compose files.
• Ensure the described messaging pathways (Kafka/NATS topics) align with the existing backend implementations.

[overcut-ai]

Completed Working on "Auto PR Description"

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

Completed Working on "Auto PR Description"

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

Summary: 5 MAJOR findings (0 BLOCKER, 0 CRITICAL, 0 MINOR, 0 SUGGESTION, 0 PRAISE).

Key themes:

1. Service environment tables omit required Kafka/NATS variables or misname actual build-time keys, so operators following this doc will end up with broken deployments.
2. Messaging guidance over-promises: the logistic server guide claims Kafka + NATS wiring/handlers that are not implemented, which misleads anyone relying on those subscribers.
3. Several sections describe runtime behaviors (connectMicroservices, handler coverage) that don’t exist in code today, creating a dangerous drift between reference doc and application reality.

Next steps:

• Update the ecommerce-server, logistic-server, and ecommerce-admin env var tables to list the real variables enforced by code (KAFKA_*, NATS_SERVERS, VITE_REACT_APP_SERVER_URL, etc.) with accurate defaults.
• Align the messaging/connectivity sections with the actual implementation—either add the missing NATS handlers/microservice wiring or clearly document that they are not available yet.
• Re-read the rest of AGENTS.md for similar discrepancies so the reference stays authoritative for automation and new contributors.

[overcut-ai]

[major]: Frontend env var name is wrong

AGENTS.md repeatedly tells contributors to set REACT_APP_SERVER_URL for the admin app, but the Vite client reads import.meta.env.VITE_REACT_APP_SERVER_URL (matching apps/ecommerce-admin/.env). Following the doc leaves the dashboard pointing at undefined. Rename those references to VITE_REACT_APP_SERVER_URL and note that Vite exposes it via import.meta.env.

Suggested fix: Replace each REACT_APP_SERVER_URL reference (tables + workflow steps) with VITE_REACT_APP_SERVER_URL and explain Vite access.

[overcut-ai]

[major]: NATS wiring description inaccurate

The Messaging section claims Kafka and NATS clients are wired in apps/logistic-server/src/connectMicroservices.ts, but that file only registers Kafka. NATS is configured solely through Nest modules, so the guide sends readers on a goose chase for nonexistent bootstrap code.

Suggested fix: Rephrase to say only Kafka is wired via connectMicroservices.ts (or actually add the NATS hookup if intended).

[overcut-ai]

[major]: db:init guidance generates new migrations

The doc instructs everyone to run npm run db:init during setup, yet that script creates a brand-new migration named 'initial version' before applying migrations. Using it routinely dirties the repo and even fails once that migration already exists. The workflow should instead tell contributors to apply existing migrations (e.g., db:migrate-up + seed) and reserve db:init for the first migration only.

Suggested fix: Update the Tooling/Common Tasks steps to recommend db:migrate-up + seed (or db:clean && db:migrate-up) for everyday setup and document db:init as a one-off when creating the initial migration.